postgresql-simple-0.7.0.1: Mid-Level PostgreSQL client library

Copyright | (c) 2011-2015 Leon P Smith
License | BSD3
Maintainer | Leon P Smith <leon@melding-monads.com>
Stability | experimental
Safe Haskell | None
Language | Haskell2010

Database.PostgreSQL.Simple.Internal

Description

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.

Synopsis

- data Field = Field {
  - result :: !Result
  - column :: !Column
  - typeOid :: !Oid
  }
- type TypeInfoCache = IntMap TypeInfo
- data Connection = Connection {
  - connectionHandle :: !(MVar Connection)
  - connectionObjects :: !(MVar TypeInfoCache)
  - connectionTempNameCounter :: !(IORef Int64)
  }
- data SomePostgreSqlException = Exception e => SomePostgreSqlException e
- postgresqlExceptionToException :: Exception e => e -> SomeException
- postgresqlExceptionFromException :: Exception e => SomeException -> Maybe e
- data SqlError = SqlError {
  - sqlState :: ByteString
  - sqlExecStatus :: ExecStatus
  - sqlErrorMsg :: ByteString
  - sqlErrorDetail :: ByteString
  - sqlErrorHint :: ByteString
  }
- fatalError :: ByteString -> SqlError
- data QueryError = QueryError {
  - qeMessage :: String
  - qeQuery :: Query
  }
- data FormatError = FormatError {
  - fmtMessage :: String
  - fmtQuery :: Query
  - fmtParams :: [ByteString]
  }
- data ConnectInfo = ConnectInfo {
  - connectHost :: String
  - connectPort :: Word16
  - connectUser :: String
  - connectPassword :: String
  - connectDatabase :: String
  }
- defaultConnectInfo :: ConnectInfo
- connect :: ConnectInfo -> IO Connection
- withConnect :: ConnectInfo -> (Connection -> IO c) -> IO c
- connectPostgreSQL :: ByteString -> IO Connection
- connectdb :: ByteString -> IO Connection
- postgreSQLConnectionString :: ConnectInfo -> ByteString
- oid2int :: Oid -> Int
- exec :: Connection -> ByteString -> IO Result
- execute_ :: Connection -> Query -> IO Int64
- finishExecute :: Connection -> Query -> Result -> IO Int64
- throwResultError :: ByteString -> Result -> ExecStatus -> IO a
- disconnectedError :: SqlError
- withConnection :: Connection -> (Connection -> IO a) -> IO a
- close :: Connection -> IO ()
- newNullConnection :: IO Connection
- data Row = Row {
  - row :: !Row
  - rowresult :: !Result
  }
- newtype RowParser a = RP {
  - unRP :: ReaderT Row (StateT Column Conversion) a
  }
- liftRowParser :: IO a -> RowParser a
- newtype Conversion a = Conversion {
  - runConversion :: Connection -> IO (Ok a)
  }
- 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
- buildAction :: Connection -> Query -> [Action] -> Action -> 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)
- breakOnSingleQuestionMark :: ByteString -> (ByteString, ByteString)

# Documentation

data Field Source #

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 Source #

data Connection Source #

Constructors

Connection |

Fields

- connectionHandle :: !(MVar Connection)
- connectionObjects :: !(MVar TypeInfoCache)
- connectionTempNameCounter :: !(IORef Int64)

#### Instances

Instances details

Eq Connection Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods (==) :: Connection -> Connection -> Bool Source # (/=) :: Connection -> Connection -> Bool Source #

data SomePostgreSqlException Source #

Superclass for postgresql exceptions

Constructors

Exception e => SomePostgreSqlException e |

#### Instances

Instances details

Exception SomePostgreSqlException Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods toException :: SomePostgreSqlException -> SomeException Source # fromException :: SomeException -> Maybe SomePostgreSqlException Source # displayException :: SomePostgreSqlException -> String Source # backtraceDesired :: SomePostgreSqlException -> Bool Source #
Show SomePostgreSqlException Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods showsPrec :: Int -> SomePostgreSqlException -> ShowS Source # show :: SomePostgreSqlException -> String Source # showList :: [SomePostgreSqlException] -> ShowS Source #

postgresqlExceptionToException :: Exception e => e -> SomeException Source #

postgresqlExceptionFromException :: Exception e => SomeException -> Maybe e Source #

data SqlError Source #

Constructors

SqlError |

Fields

- sqlState :: ByteString
- sqlExecStatus :: ExecStatus
- sqlErrorMsg :: ByteString
- sqlErrorDetail :: ByteString
- sqlErrorHint :: ByteString

#### Instances

Instances details

Exception SqlError Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods toException :: SqlError -> SomeException Source # fromException :: SomeException -> Maybe SqlError Source # displayException :: SqlError -> String Source # backtraceDesired :: SqlError -> Bool Source #
Show SqlError Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods showsPrec :: Int -> SqlError -> ShowS Source # show :: SqlError -> String Source # showList :: [SqlError] -> ShowS Source #
Eq SqlError Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods (==) :: SqlError -> SqlError -> Bool Source # (/=) :: SqlError -> SqlError -> Bool Source #

fatalError :: ByteString -> SqlError Source #

data QueryError Source #

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

Instances details

Exception QueryError Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods toException :: QueryError -> SomeException Source # fromException :: SomeException -> Maybe QueryError Source # displayException :: QueryError -> String Source # backtraceDesired :: QueryError -> Bool Source #
Show QueryError Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods showsPrec :: Int -> QueryError -> ShowS Source # show :: QueryError -> String Source # showList :: [QueryError] -> ShowS Source #
Eq QueryError Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods (==) :: QueryError -> QueryError -> Bool Source # (/=) :: QueryError -> QueryError -> Bool Source #

data FormatError Source #

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

Instances details

Exception FormatError Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods toException :: FormatError -> SomeException Source # fromException :: SomeException -> Maybe FormatError Source # displayException :: FormatError -> String Source # backtraceDesired :: FormatError -> Bool Source #
Show FormatError Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods showsPrec :: Int -> FormatError -> ShowS Source # show :: FormatError -> String Source # showList :: [FormatError] -> ShowS Source #
Eq FormatError Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods (==) :: FormatError -> FormatError -> Bool Source # (/=) :: FormatError -> FormatError -> Bool Source #

data ConnectInfo Source #

Constructors

ConnectInfo |

Fields

- connectHost :: String
- connectPort :: Word16
- connectUser :: String
- connectPassword :: String
- connectDatabase :: String

#### Instances

Instances details

Generic ConnectInfo Source # |

Instance details

Defined in Database.PostgreSQL.Simple.Internal

Associated Types

type Rep ConnectInfo |

Instance details

Defined in Database.PostgreSQL.Simple.Internal

type Rep ConnectInfo = D1 ('MetaData "ConnectInfo" "Database.PostgreSQL.Simple.Internal" "postgresql-simple-0.7.0.1-2UIwxyVGztGAfJcoklGg9" 'False) (C1 ('MetaCons "ConnectInfo" 'PrefixI 'True) ((S1 ('MetaSel ('Just "connectHost") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String) :*: S1 ('MetaSel ('Just "connectPort") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Word16)) :*: (S1 ('MetaSel ('Just "connectUser") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String) :*: (S1 ('MetaSel ('Just "connectPassword") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String) :*: S1 ('MetaSel ('Just "connectDatabase") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String)))))

Methods

from :: ConnectInfo -> Rep ConnectInfo x Source #

to :: Rep ConnectInfo x -> ConnectInfo Source #

Read ConnectInfo Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods readsPrec :: Int -> ReadS ConnectInfo Source # readList :: ReadS [ConnectInfo] Source # readPrec :: ReadPrec ConnectInfo Source # readListPrec :: ReadPrec [ConnectInfo] Source #
Show ConnectInfo Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods showsPrec :: Int -> ConnectInfo -> ShowS Source # show :: ConnectInfo -> String Source # showList :: [ConnectInfo] -> ShowS Source #
Eq ConnectInfo Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods (==) :: ConnectInfo -> ConnectInfo -> Bool Source # (/=) :: ConnectInfo -> ConnectInfo -> Bool Source #
type Rep ConnectInfo Source # |

Instance details

Defined in Database.PostgreSQL.Simple.Internal

type Rep ConnectInfo = D1 ('MetaData "ConnectInfo" "Database.PostgreSQL.Simple.Internal" "postgresql-simple-0.7.0.1-2UIwxyVGztGAfJcoklGg9" 'False) (C1 ('MetaCons "ConnectInfo" 'PrefixI 'True) ((S1 ('MetaSel ('Just "connectHost") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String) :*: S1 ('MetaSel ('Just "connectPort") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Word16)) :*: (S1 ('MetaSel ('Just "connectUser") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String) :*: (S1 ('MetaSel ('Just "connectPassword") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String) :*: S1 ('MetaSel ('Just "connectDatabase") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String)))))

defaultConnectInfo :: ConnectInfo Source #

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 Source #

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

withConnect :: ConnectInfo -> (Connection -> IO c) -> IO c Source #

Memory bracket around `connect` and `close`.

Since: 0.6.5

connectPostgreSQL :: ByteString -> IO Connection Source #

Attempt to make a connection based on a libpq connection string. See https://www.postgresql.org/docs/9.5/static/libpq-connect.html#LIBPQ-CONNSTRING for more information. Also note that environment variables also affect parameters not provided, parameters provided as the empty string, and a few other things; see https://www.postgresql.org/docs/9.5/static/libpq-envars.html for details. 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. The path of the `pgpass` file may be specified by setting the `PGPASSFILE` environment variable. See https://www.postgresql.org/docs/9.5/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 https://www.postgresql.org/docs/9.5/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 connection parameters. In particular, `sslmode` needs to be set to `require`, `verify-ca`, or `verify-full` in order to perform certificate validation. When `sslmode` is `require`, then you will also need to specify 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. See https://www.postgresql.org/docs/9.5/static/libpq-ssl.html for detailed information regarding libpq and SSL.

connectdb :: ByteString -> IO Connection Source #

postgreSQLConnectionString :: ConnectInfo -> ByteString Source #

Turns a `ConnectInfo` data structure into a libpq connection string.

oid2int :: Oid -> Int Source #

exec :: Connection -> ByteString -> IO Result Source #

execute_ :: Connection -> Query -> IO Int64 Source #

A version of `execute` that does not perform query substitution.

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

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

disconnectedError :: SqlError Source #

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

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

close :: Connection -> IO () Source #

newNullConnection :: IO Connection Source #

data Row Source #

Constructors

Row |

Fields

- row :: !Row
- rowresult :: !Result

newtype RowParser a Source #

Constructors

RP |

Fields

- unRP :: ReaderT Row (StateT Column Conversion) a

#### Instances

Instances details

Alternative RowParser Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods empty :: RowParser a Source # (<|>) :: RowParser a -> RowParser a -> RowParser a Source # some :: RowParser a -> RowParser [a] Source # many :: RowParser a -> RowParser [a] Source #
Applicative RowParser Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods pure :: a -> RowParser a Source # (<*>) :: RowParser (a -> b) -> RowParser a -> RowParser b Source # liftA2 :: (a -> b -> c) -> RowParser a -> RowParser b -> RowParser c Source # (*>) :: RowParser a -> RowParser b -> RowParser b Source # (<*) :: RowParser a -> RowParser b -> RowParser a Source #
Functor RowParser Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods fmap :: (a -> b) -> RowParser a -> RowParser b Source # (<$) :: a -> RowParser b -> RowParser a Source #
Monad RowParser Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods (>>=) :: RowParser a -> (a -> RowParser b) -> RowParser b Source # (>>) :: RowParser a -> RowParser b -> RowParser b Source # return :: a -> RowParser a Source #

liftRowParser :: IO a -> RowParser a Source #

newtype Conversion a Source #

Constructors

Conversion |

Fields

- runConversion :: Connection -> IO (Ok a)

#### Instances

Instances details

Alternative Conversion Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods empty :: Conversion a Source # (<|>) :: Conversion a -> Conversion a -> Conversion a Source # some :: Conversion a -> Conversion [a] Source # many :: Conversion a -> Conversion [a] Source #
Applicative Conversion Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods pure :: a -> Conversion a Source # (<*>) :: Conversion (a -> b) -> Conversion a -> Conversion b Source # liftA2 :: (a -> b -> c) -> Conversion a -> Conversion b -> Conversion c Source # (*>) :: Conversion a -> Conversion b -> Conversion b Source # (<*) :: Conversion a -> Conversion b -> Conversion a Source #
Functor Conversion Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods fmap :: (a -> b) -> Conversion a -> Conversion b Source # (<$) :: a -> Conversion b -> Conversion a Source #
Monad Conversion Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods (>>=) :: Conversion a -> (a -> Conversion b) -> Conversion b Source # (>>) :: Conversion a -> Conversion b -> Conversion b Source # return :: a -> Conversion a Source #
MonadPlus Conversion Source # |
Instance details Defined in Database.PostgreSQL.Simple.Internal Methods mzero :: Conversion a Source # mplus :: Conversion a -> Conversion a -> Conversion a Source #

liftConversion :: IO a -> Conversion a Source #

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

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

newTempName :: Connection -> IO Query Source #

fdError :: ByteString -> IOError Source #

libPQError :: ByteString -> IOError Source #

throwLibPQError :: Connection -> ByteString -> IO a Source #

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

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

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

Quote bytestring or throw `FormatError`

buildAction Source #

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) Source #

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

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

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

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

breakOnSingleQuestionMark :: ByteString -> (ByteString, ByteString) Source #