Database.PostgreSQL.Typed.Protocol

The Protocol module allows for direct, low-level communication with a PostgreSQL server over TCP/IP. You probably don't want to use this module directly.

Documentation

data PGDatabase

Information for how to connect to a database, to be passed to pgConnect.

Constructors

PGDatabase

Fields

• pgDBAddr :: Either (HostName, ServiceName) SockAddr

  The address to connect to the server

• pgDBName :: ByteString

  The name of the database

• pgDBUser, pgDBPass :: ByteString
• pgDBParams :: [(ByteString, ByteString)]

  Extra parameters to set for the connection (e.g., (TimeZone, UTC))

• pgDBDebug :: Bool

  Log all low-level server messages

• pgDBLogMessage :: MessageFields -> IO ()

  How to log server notice messages (e.g., print . PGError)

• pgDBTLS :: PGTlsMode

  TLS mode

Instances

Eq PGDatabase

Defined in Database.PostgreSQL.Typed.Protocol

Methods

(==) :: PGDatabase -> PGDatabase -> Bool

(/=) :: PGDatabase -> PGDatabase -> Bool

Show PGDatabase

Defined in Database.PostgreSQL.Typed.Protocol

Methods

showsPrec :: Int -> PGDatabase -> ShowS

show :: PGDatabase -> String

showList :: [PGDatabase] -> ShowS

defaultPGDatabase :: PGDatabase

A database connection with sane defaults: localhost:5432:postgres

data PGConnection

An established connection to the PostgreSQL server. These objects are not thread-safe and must only be used for a single request at a time.

newtype PGError

PGException is thrown upon encountering an ErrorResponse with severity of ERROR, FATAL, or PANIC. It holds the message of the error.

Constructors

PGError

Fields

• pgErrorFields :: MessageFields

Instances

Show PGError

Defined in Database.PostgreSQL.Typed.Protocol

Methods

showsPrec :: Int -> PGError -> ShowS

show :: PGError -> String

showList :: [PGError] -> ShowS

Exception PGError

Defined in Database.PostgreSQL.Typed.Protocol

Methods

toException :: PGError -> SomeException

fromException :: SomeException -> Maybe PGError

displayException :: PGError -> String

data PGTlsMode

Constructors

TlsDisabled

TLS is disabled

TlsNoValidate

TlsValidate PGTlsValidateMode SignedCertificate

Instances

Eq PGTlsMode

Defined in Database.PostgreSQL.Typed.Protocol

Methods

(==) :: PGTlsMode -> PGTlsMode -> Bool

(/=) :: PGTlsMode -> PGTlsMode -> Bool

Show PGTlsMode

Defined in Database.PostgreSQL.Typed.Protocol

Methods

showsPrec :: Int -> PGTlsMode -> ShowS

show :: PGTlsMode -> String

showList :: [PGTlsMode] -> ShowS

data PGTlsValidateMode

Constructors

TlsValidateFull

Equivalent to sslmode=verify-full. Ie: Check the FQHN against the certicate's CN

TlsValidateCA

Equivalent to sslmode=verify-ca. Ie: Only check that the certificate has been signed by the root certificate we provide

Instances

Eq PGTlsValidateMode

Defined in Database.PostgreSQL.Typed.Protocol

Methods

(==) :: PGTlsValidateMode -> PGTlsValidateMode -> Bool

(/=) :: PGTlsValidateMode -> PGTlsValidateMode -> Bool

Show PGTlsValidateMode

Defined in Database.PostgreSQL.Typed.Protocol

Methods

showsPrec :: Int -> PGTlsValidateMode -> ShowS

show :: PGTlsValidateMode -> String

showList :: [PGTlsValidateMode] -> ShowS

pgErrorCode :: PGError -> ByteString

Message SQLState code. See http://www.postgresql.org/docs/current/static/errcodes-appendix.html.

pgConnectionDatabase :: PGConnection -> PGDatabase

The database information for this connection.

pgTypeEnv :: PGConnection -> PGTypeEnv

The type environment for this connection.

pgConnect :: PGDatabase -> IO PGConnection

Connect to a PostgreSQL server.

pgDisconnect

Arguments

:: PGConnection

a handle from pgConnect

-> IO ()

Disconnect cleanly from the PostgreSQL server.

pgReconnect :: PGConnection -> PGDatabase -> IO PGConnection

Possibly re-open a connection to a different database, either reusing the connection if the given database is already connected or closing it and opening a new one. Regardless, the input connection must not be used afterwards.

Query operations

pgDescribe

Arguments

:: PGConnection

-> ByteString

SQL string

-> [OID]

Optional type specifications

-> Bool

Guess nullability, otherwise assume everything is

-> IO ([OID], [(ByteString, OID, Bool)])

a list of parameter types, and a list of result field names, types, and nullability indicators.

Describe a SQL statement/query. A statement description consists of 0 or more parameter descriptions (a PostgreSQL type) and zero or more result field descriptions (for queries) (consist of the name of the field, the type of the field, and a nullability indicator).

pgSimpleQuery

Arguments

:: PGConnection

-> ByteString

SQL string

-> IO (Int, [PGValues])

The number of rows affected and a list of result rows

A simple query is one which requires sending only a single SimpleQuery message to the PostgreSQL server. The query is sent as a single string; you cannot bind parameters. Note that queries can return 0 results (an empty list).

pgSimpleQueries_

Arguments

:: PGConnection

-> ByteString

SQL string

-> IO ()

A simple query which may contain multiple queries (separated by semi-colons) whose results are all ignored. This function can also be used for "SET" parameter queries if necessary, but it's safer better to use pgDBParams.

pgPreparedQuery

Arguments

:: PGConnection

-> ByteString

SQL statement with placeholders

-> [OID]

Optional type specifications (only used for first call)

-> PGValues

Paremeters to bind to placeholders

-> [Bool]

Requested binary format for result columns

-> IO (Int, [PGValues])

Prepare a statement, bind it, and execute it. If the given statement has already been prepared (and not yet closed) on this connection, it will be re-used.

pgPreparedLazyQuery

Arguments

:: PGConnection

-> ByteString

-> [OID]

-> PGValues

-> [Bool]

-> Word32

Chunk size (1 is common, 0 is all-at-once)

-> IO [PGValues]

Like pgPreparedQuery but requests results lazily in chunks of the given size. Does not use a named portal, so other requests may not intervene.

pgCloseStatement :: PGConnection -> ByteString -> [OID] -> IO ()

Close a previously prepared query (if necessary).

Transactions

pgBegin :: PGConnection -> IO ()

Begin a new transaction. If there is already a transaction in progress (created with pgBegin or pgTransaction) instead creates a savepoint.

pgCommit :: PGConnection -> IO ()

Commit the most recent pgBegin.

pgRollback :: PGConnection -> IO ()

Rollback to the most recent pgBegin.

pgCommitAll :: PGConnection -> IO ()

Commit all active pgBegins.

pgRollbackAll :: PGConnection -> IO ()

Rollback all active pgBegins.

pgTransaction :: PGConnection -> IO a -> IO a

Wrap a computation in a pgBegin, pgCommit block, or pgRollback on exception.

HDBC support

pgDisconnectOnce

Arguments

:: PGConnection

a handle from pgConnect

-> IO ()

Disconnect cleanly from the PostgreSQL server, but only if it's still connected.

pgRun :: PGConnection -> ByteString -> [OID] -> PGValues -> IO (Maybe Integer)

Prepare, bind, execute, and close a single (unnamed) query, and return the number of rows affected, or Nothing if there are (ignored) result rows.

data PGPreparedStatement

Instances

Eq PGPreparedStatement

Defined in Database.PostgreSQL.Typed.Protocol

Methods

(==) :: PGPreparedStatement -> PGPreparedStatement -> Bool

(/=) :: PGPreparedStatement -> PGPreparedStatement -> Bool

Show PGPreparedStatement

Defined in Database.PostgreSQL.Typed.Protocol

Methods

showsPrec :: Int -> PGPreparedStatement -> ShowS

show :: PGPreparedStatement -> String

showList :: [PGPreparedStatement] -> ShowS

pgPrepare :: PGConnection -> ByteString -> [OID] -> IO PGPreparedStatement

Prepare a single query and return its handle.

pgClose :: PGConnection -> PGPreparedStatement -> IO ()

Close a previously prepared query.

data PGColDescription

Constructors

PGColDescription

Fields

• pgColName :: ByteString
• pgColTable :: !OID
• pgColNumber :: !Int16
• pgColType :: !OID
• pgColSize :: !Int16
• pgColModifier :: !Int32
• pgColBinary :: !Bool

Instances

Show PGColDescription

Defined in Database.PostgreSQL.Typed.Protocol

Methods

showsPrec :: Int -> PGColDescription -> ShowS

show :: PGColDescription -> String

showList :: [PGColDescription] -> ShowS

type PGRowDescription = [PGColDescription]

pgBind :: PGConnection -> PGPreparedStatement -> PGValues -> IO PGRowDescription

Bind a prepared statement, and return the row description. After pgBind, you must either call pgFetch until it completes (returns (_, Just _)) or pgFinish before calling pgBind again on the same prepared statement.

pgFetch

Arguments

:: PGConnection

-> PGPreparedStatement

-> Word32

Maximum number of rows to return, or 0 for all

-> IO ([PGValues], Maybe Integer)

Fetch some rows from an executed prepared statement, returning the next N result rows (if any) and number of affected rows when complete.

Notifications

data PGNotification

Constructors

PGNotification

Fields

• pgNotificationPid :: !Word32
• pgNotificationChannel :: !ByteString
• pgNotificationPayload :: ByteString

Instances

Show PGNotification

Defined in Database.PostgreSQL.Typed.Protocol

Methods

showsPrec :: Int -> PGNotification -> ShowS

show :: PGNotification -> String

showList :: [PGNotification] -> ShowS

pgGetNotification :: PGConnection -> IO PGNotification

Retrieve a notifications, blocking if necessary.

pgGetNotifications :: PGConnection -> IO [PGNotification]

Retrieve any pending notifications. Non-blocking.

TLS Helpers

pgTlsValidate :: PGTlsValidateMode -> ByteString -> Either String PGTlsMode

Constructs a PGTlsMode to validate the server certificate with given root certificate (in PEM format)

pgSupportsTls :: PGConnection -> Bool