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

pgDBHost :: HostName

The hostname (ignored if pgDBPort is UnixSocket)

pgDBPort :: PortID

The port, likely either PortNumber 5432 or UnixSocket "/tmp/.s.PGSQL.5432"

pgDBName :: ByteString

The name of the database

pgDBUser, pgDBPass :: ByteString

pgDBDebug :: Bool

Log all low-level server messages

pgDBLogMessage :: MessageFields -> IO ()

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

Instances

Eq PGDatabase

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.

data 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

Exception PGError

pgErrorCode :: PGError -> ByteString

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

pgTypeEnv :: PGConnection -> PGTypeEnv

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.

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.

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

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