Database.PostgreSQL.Simple.Internal

Internal bits. This interface is less stable and can change at any time. In particular this means that while the rest of the postgresql-simple package endeavors to follow the package versioning policy, this module does not. Also, at the moment there are things in here that aren't particularly internal and are exported elsewhere; these will eventually disappear from this module.

Documentation

data Field

A Field represents metadata about a particular field

You don't particularly want to retain these structures for a long period of time, as they will retain the entire query result, not just the field metadata

Constructors

Field

Fields

result :: !Result

column :: !Column

typeOid :: !Oid

This returns the type oid associated with the column. Analogous to libpq's PQftype.

type TypeInfoCache = IntMap TypeInfo

data Connection

Constructors

Connection

Fields

connectionHandle :: !(MVar Connection)

connectionObjects :: !(MVar TypeInfoCache)

connectionTempNameCounter :: !(IORef Int64)

data SqlError

Constructors

SqlError

Fields

sqlState :: ByteString

sqlExecStatus :: ExecStatus

sqlErrorMsg :: ByteString

sqlErrorDetail :: ByteString

sqlErrorHint :: ByteString

Instances

Show SqlError

Exception SqlError

Typeable * SqlError

fatalError :: ByteString -> SqlError

data QueryError

Exception thrown if query is used to perform an INSERT-like operation, or execute is used to perform a SELECT-like operation.

Constructors

QueryError

Fields

qeMessage :: String

qeQuery :: Query

Instances

Eq QueryError

Show QueryError

Exception QueryError

Typeable * QueryError

data FormatError

Exception thrown if a Query could not be formatted correctly. This may occur if the number of '?' characters in the query string does not match the number of parameters provided.

Constructors

FormatError

Fields

fmtMessage :: String

fmtQuery :: Query

fmtParams :: [ByteString]

Instances

Eq FormatError

Show FormatError

Exception FormatError

Typeable * FormatError

data ConnectInfo

Constructors

ConnectInfo

Fields

connectHost :: String

connectPort :: Word16

connectUser :: String

connectPassword :: String

connectDatabase :: String

Instances

Eq ConnectInfo

Read ConnectInfo

Show ConnectInfo

Typeable * ConnectInfo

defaultConnectInfo :: ConnectInfo

Default information for setting up a connection.

Defaults are as follows:

• Server on localhost
• Port on 5432
• User postgres
• No password
• Database postgres

Use as in the following example:

connect defaultConnectInfo { connectHost = "db.example.com" }

connect :: ConnectInfo -> IO Connection

Connect with the given username to the given database. Will throw an exception if it cannot connect.

connectPostgreSQL :: ByteString -> IO Connection

Attempt to make a connection based on a libpq connection string. See http://www.postgresql.org/docs/9.3/static/libpq-connect.html#LIBPQ-CONNSTRING for more information. Here is an example with some of the most commonly used parameters:

host='db.somedomain.com' port=5432 ...

This attempts to connect to db.somedomain.com:5432. Omitting the port will normally default to 5432.

On systems that provide unix domain sockets, omitting the host parameter will cause libpq to attempt to connect via unix domain sockets. The default filesystem path to the socket is constructed from the port number and the DEFAULT_PGSOCKET_DIR constant defined in the pg_config_manual.h header file. Connecting via unix sockets tends to use the peer authentication method, which is very secure and does not require a password.

On Windows and other systems without unix domain sockets, omitting the host will default to localhost.

... dbname='postgres' user='postgres' password='secret \' \\ pw'

This attempts to connect to a database named postgres with user postgres and password secret ' \ pw. Backslash characters will have to be double-quoted in literal Haskell strings, of course. Omitting dbname and user will both default to the system username that the client process is running as.

Omitting password will default to an appropriate password found in the pgpass file, or no password at all if a matching line is not found. See http://www.postgresql.org/docs/9.3/static/libpq-pgpass.html for more information regarding this file.

As all parameters are optional and the defaults are sensible, the empty connection string can be useful for development and exploratory use, assuming your system is set up appropriately.

On Unix, such a setup would typically consist of a local postgresql server listening on port 5432, as well as a system user, database user, and database sharing a common name, with permissions granted to the user on the database.

On Windows, in addition you will either need pg_hba.conf to specify the use of the trust authentication method for the connection, which may not be appropriate for multiuser or production machines, or you will need to use a pgpass file with the password or md5 authentication methods.

See http://www.postgresql.org/docs/9.3/static/client-authentication.html for more information regarding the authentication process.

SSL/TLS will typically "just work" if your postgresql server supports or requires it. However, note that libpq is trivially vulnerable to a MITM attack without setting additional SSL parameters in the connection string. In particular, sslmode needs to set be require, verify-ca, or verify-full to perform certificate validation. When sslmode is require, then you will also need to have a sslrootcert file, otherwise no validation of the server's identity will be performed. Client authentication via certificates is also possible via the sslcert and sslkey parameters.

connectdb :: ByteString -> IO Connection

postgreSQLConnectionString :: ConnectInfo -> ByteString

Turns a ConnectInfo data structure into a libpq connection string.

oid2int :: Oid -> Int

exec :: Connection -> ByteString -> IO Result

execute_ :: Connection -> Query -> IO Int64

A version of execute that does not perform query substitution.

finishExecute :: Connection -> Query -> Result -> IO Int64

throwResultError :: ByteString -> Result -> ExecStatus -> IO a

disconnectedError :: SqlError

withConnection :: Connection -> (Connection -> IO a) -> IO a

Atomically perform an action with the database handle, if there is one.

close :: Connection -> IO ()

newNullConnection :: IO Connection

data Row

Constructors

Row

Fields

row :: !Row

rowresult :: !Result

newtype RowParser a

Constructors

RP

Fields

unRP :: ReaderT Row (StateT Column Conversion) a

Instances

Alternative RowParser

Monad RowParser

Functor RowParser

Applicative RowParser

liftRowParser :: IO a -> RowParser a

newtype Conversion a

Constructors

Conversion

Fields

runConversion :: Connection -> IO (Ok a)

Instances

Alternative Conversion

Monad Conversion

Functor Conversion

MonadPlus Conversion

Applicative Conversion

liftConversion :: IO a -> Conversion a

conversionMap :: (Ok a -> Ok b) -> Conversion a -> Conversion b

conversionError :: Exception err => err -> Conversion a

newTempName :: Connection -> IO Query

fdError :: ByteString -> IOError

libPQError :: ByteString -> IOError

throwLibPQError :: Connection -> ByteString -> IO a

fmtError :: String -> Query -> [Action] -> a

fmtErrorBs :: Query -> [Action] -> ByteString -> a

quote :: Query -> [Action] -> Either ByteString ByteString -> Builder

Quote bytestring or throw FormatError

buildAction

Arguments

:: Connection

Connection for string escaping

-> Query

Query for message error

-> [Action]

List of parameters for message error

-> Action

Action to build

-> IO Builder

checkError :: Connection -> Maybe a -> IO (Either ByteString a)

escapeWrap :: (Connection -> ByteString -> IO (Maybe ByteString)) -> Connection -> ByteString -> IO (Either ByteString ByteString)

escapeStringConn :: Connection -> ByteString -> IO (Either ByteString ByteString)

escapeIdentifier :: Connection -> ByteString -> IO (Either ByteString ByteString)

escapeByteaConn :: Connection -> ByteString -> IO (Either ByteString ByteString)