| 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 { }
- type TypeInfoCache = IntMap TypeInfo
-
data
Connection
=
Connection
{
- connectionHandle :: !( MVar Connection )
- connectionObjects :: !( MVar TypeInfoCache )
- connectionTempNameCounter :: !( IORef Int64 )
- data SqlError = SqlError { }
- fatalError :: ByteString -> SqlError
- data QueryError = QueryError { }
-
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 { }
- newtype RowParser a = RP { }
- 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
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
type TypeInfoCache = IntMap TypeInfo Source #
data Connection Source #
Constructors
| Connection | |
|
Fields
|
|
Instances
| Eq Connection Source # | |
|
Defined in Database.PostgreSQL.Simple.Internal Methods (==) :: Connection -> Connection -> Bool Source # (/=) :: Connection -> Connection -> Bool Source # |
|
Constructors
| SqlError | |
|
Fields |
|
Instances
| Eq SqlError Source # | |
| Show SqlError Source # | |
| Exception SqlError Source # | |
|
Defined in Database.PostgreSQL.Simple.Internal Methods toException :: SqlError -> SomeException Source # fromException :: SomeException -> Maybe SqlError Source # displayException :: SqlError -> String 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 | |
Instances
| Eq QueryError Source # | |
|
Defined in Database.PostgreSQL.Simple.Internal Methods (==) :: QueryError -> QueryError -> Bool Source # (/=) :: QueryError -> QueryError -> Bool Source # |
|
| Show QueryError Source # | |
|
Defined in Database.PostgreSQL.Simple.Internal |
|
| Exception QueryError Source # | |
|
Defined in Database.PostgreSQL.Simple.Internal Methods toException :: QueryError -> SomeException Source # fromException :: SomeException -> Maybe QueryError Source # displayException :: QueryError -> String 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
|
|
Instances
| Eq FormatError Source # | |
|
Defined in Database.PostgreSQL.Simple.Internal Methods (==) :: FormatError -> FormatError -> Bool Source # (/=) :: FormatError -> FormatError -> Bool Source # |
|
| Show FormatError Source # | |
|
Defined in Database.PostgreSQL.Simple.Internal |
|
| Exception FormatError Source # | |
|
Defined in Database.PostgreSQL.Simple.Internal Methods toException :: FormatError -> SomeException Source # fromException :: SomeException -> Maybe FormatError Source # displayException :: FormatError -> String Source # |
|
data ConnectInfo Source #
Constructors
| ConnectInfo | |
|
Fields
|
|
Instances
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 #
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.
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 #
withConnection :: Connection -> ( Connection -> IO a) -> IO a Source #
Atomically perform an action with the database handle, if there is one.
close :: Connection -> IO () Source #
Instances
| Monad RowParser Source # | |
| Functor RowParser Source # | |
| Applicative RowParser Source # | |
| Alternative RowParser Source # | |
liftRowParser :: IO a -> RowParser a Source #
newtype Conversion a Source #
Constructors
| Conversion | |
|
Fields
|
|
Instances
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 #
fmtErrorBs :: Query -> [ Action ] -> ByteString -> a Source #
quote :: Query -> [ Action ] -> Either ByteString ByteString -> Builder Source #
Quote bytestring or throw
FormatError
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 #