A query string. This type is intended to make it difficult to construct a SQL query by concatenating string fragments, as that is an extremely common way to accidentally introduce SQL injection vulnerabilities into an application.

This type is an instance of IsString, so the easiest way to construct a query is to enable the OverloadedStrings language extension and then simply write the query in double quotes.

{-# LANGUAGE OverloadedStrings #-}

import Database.PostgreSQL.Simple

q :: Query
q = "select ?"

The underlying type is a ByteString, and literal Haskell strings that contain Unicode characters will be correctly transformed to UTF-8.

A collection type that can be turned into a list of rendering Actions.

Instances should use the toField method of the ToField class to perform conversion of each element of the collection.

You can derive ToRow for your data type using GHC generics, like this:

{-# LANGUAGE DeriveAnyClass #-}
{-# LANGUAGE DeriveGeneric  #-}

import GHC.Generics (Generic)
import Database.PostgreSQL.Simple (ToRow)

data User = User { name :: String, fileQuota :: Int }
  deriving (Generic, ToRow)

Note that this only works for product types (e.g. records) and does not support sum types or recursive types.

A collection type that can be converted from a sequence of fields. Instances are provided for tuples up to 10 elements and lists of any length.

Note that instances can be defined outside of postgresql-simple, which is often useful. For example, here's an instance for a user-defined pair:

data User = User { name :: String, fileQuota :: Int }

instance FromRow User where
    fromRow = User <$> field <*> field

The number of calls to field must match the number of fields returned in a single row of the query result. Otherwise, a ConversionFailed exception will be thrown.

You can also derive FromRow for your data type using GHC generics, like this:

{-# LANGUAGE DeriveAnyClass #-}
{-# LANGUAGE DeriveGeneric  #-}

import GHC.Generics (Generic)
import Database.PostgreSQL.Simple (FromRow)

data User = User { name :: String, fileQuota :: Int }
  deriving (Generic, FromRow)

Note that this only works for product types (e.g. records) and does not support sum types or recursive types.

Note that field evaluates its result to WHNF, so the caveats listed in mysql-simple and very early versions of postgresql-simple no longer apply. Instead, look at the caveats associated with user-defined implementations of fromField.

Wrap a list of values for use in an IN clause. Replaces a single "?" character with a parenthesized list of rendered values.

Example:

query c "select * from whatever where id in ?" (Only (In [3,4,5]))

Note that In [] expands to (null), which works as expected in the query above, but evaluates to the logical null value on every row instead of TRUE. This means that changing the query above to ... id NOT in ? and supplying the empty list as the parameter returns zero rows, instead of all of them as one would expect.

Since postgresql doesn't seem to provide a syntax for actually specifying an empty list, which could solve this completely, there are two workarounds particularly worth mentioning, namely:

1. Use postgresql-simple's Values type instead, which can handle the empty case correctly. Note however that while specifying the postgresql type "int4" is mandatory in the empty case, specifying the haskell type Values (Only Int) would not normally be needed in realistic use cases.

   query c "select * from whatever where id not in ?"
           (Only (Values ["int4"] [] :: Values (Only Int)))

2. Use sql's COALESCE operator to turn a logical null into the correct boolean. Note however that the correct boolean depends on the use case:

   query c "select * from whatever where coalesce(id NOT in ?, TRUE)"
           (Only (In [] :: In [Int]))

   query c "select * from whatever where coalesce(id IN ?, FALSE)"
           (Only (In [] :: In [Int]))

   Note that at as of PostgreSQL 9.4, the query planner cannot see inside the COALESCE operator, so if you have an index on id then you probably don't want to write the last example with COALESCE, which would result in a table scan. There are further caveats if id can be null or you want null treated sensibly as a component of IN or NOT IN.

Wrap binary data for use as a bytea value.

The 1-tuple type or single-value "collection".

This type is structurally equivalent to the Identity type, but its intent is more about serving as the anonymous 1-tuple type missing from Haskell for attaching typeclass instances.

Parameter usage example:

encodeSomething (Only (42::Int))

Result usage example:

xs <- decodeSomething
forM_ xs $ \(Only id) -> {- ... -}

A composite type to parse your custom data structures without having to define dummy newtype wrappers every time.

instance FromRow MyData where ...

instance FromRow MyData2 where ...

then I can do the following for free:

res <- query' c "..."
forM res $ \(MyData{..} :. MyData2{..}) -> do
  ....

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.

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

Exception thrown if conversion from a SQL value to a Haskell value fails.

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.

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

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" }

Turns a ConnectInfo data structure into a libpq connection string.

Perform a SELECT or other SQL query that is expected to return results. All results are retrieved and converted before this function returns.

When processing large results, this function will consume a lot of client-side memory. Consider using fold instead.

Exceptions that may be thrown:

• FormatError: the query string could not be formatted correctly.
• QueryError: the result contains no columns (i.e. you should be using execute instead of query).
• ResultError: result conversion failed.
• SqlError: the postgresql backend returned an error, e.g. a syntax or type error, or an incorrect table or column name.

A version of query that does not perform query substitution.

A version of query taking parser as argument

A version of query_ taking parser as argument

Number of rows to fetch at a time. Automatic currently defaults to 256 rows, although it might be nice to make this more intelligent based on e.g. the average size of the rows.

defaults to Automatic, and TransactionMode ReadCommitted ReadOnly

Perform a SELECT or other SQL query that is expected to return results. Results are streamed incrementally from the server, and consumed via a left fold.

When dealing with small results, it may be simpler (and perhaps faster) to use query instead.

This fold is not strict. The stream consumer is responsible for forcing the evaluation of its result to avoid space leaks.

This is implemented using a database cursor. As such, this requires a transaction. This function will detect whether or not there is a transaction in progress, and will create a ReadCommitted ReadOnly transaction if needed. The cursor is given a unique temporary name, so the consumer may itself call fold.

Exceptions that may be thrown:

• FormatError: the query string could not be formatted correctly.
• QueryError: the result contains no columns (i.e. you should be using execute instead of query).
• ResultError: result conversion failed.
• SqlError: the postgresql backend returned an error, e.g. a syntax or type error, or an incorrect table or column name.

The same as fold, but this provides a bit more control over lower-level details. Currently, the number of rows fetched per round-trip to the server and the transaction mode may be adjusted accordingly. If the connection is already in a transaction, then the existing transaction is used and thus the transactionMode option is ignored.

A version of fold that does not perform query substitution.

A version of fold that does not transform a state value.

A version of forEach that does not perform query substitution.

Execute INSERT ... RETURNING, UPDATE ... RETURNING, or other SQL query that accepts multi-row input and is expected to return results. Note that it is possible to write query conn "INSERT ... RETURNING ..." ... in cases where you are only inserting a single row, and do not need functionality analogous to executeMany.

If the list of parameters is empty, this function will simply return [] without issuing the query to the backend. If this is not desired, consider using the Values constructor instead.

Throws FormatError if the query could not be formatted correctly.

A version of fold taking a parser as an argument

A version of foldWithOptions taking a parser as an argument

A version of fold_ taking a parser as an argument

A version of foldWithOptions_ taking a parser as an argument

A version of forEach taking a parser as an argument

A version of returning taking parser as argument

Execute an INSERT, UPDATE, or other SQL query that is not expected to return results.

Returns the number of rows affected.

Throws FormatError if the query could not be formatted correctly, or a SqlError exception if the backend returns an error.

A version of execute that does not perform query substitution.

Execute a multi-row INSERT, UPDATE, or other SQL query that is not expected to return results.

Returns the number of rows affected. If the list of parameters is empty, this function will simply return 0 without issuing the query to the backend. If this is not desired, consider using the Values constructor instead.

Throws FormatError if the query could not be formatted correctly, or a SqlError exception if the backend returns an error.

For example, here's a command that inserts two rows into a table with two columns:

executeMany c [sql|
    INSERT INTO sometable VALUES (?,?)
 |] [(1, "hello"),(2, "world")]

Here's an canonical example of a multi-row update command:

executeMany c [sql|
    UPDATE sometable
       SET y = upd.y
      FROM (VALUES (?,?)) as upd(x,y)
     WHERE sometable.x = upd.x
 |] [(1, "hello"),(2, "world")]

Execute an action inside a SQL transaction.

This function initiates a transaction with a "begin transaction" statement, then executes the supplied action. If the action succeeds, the transaction will be completed with commit before this function returns.

If the action throws any kind of exception (not just a PostgreSQL-related exception), the transaction will be rolled back using rollback, then the exception will be rethrown.

For nesting transactions, see withSavepoint.

Create a savepoint, and roll back to it if an error occurs. This may only be used inside of a transaction, and provides a sort of "nested transaction".

See https://www.postgresql.org/docs/9.5/static/sql-savepoint.html

Begin a transaction.

Commit a transaction.

Rollback a transaction.

Format a query string with a variable number of rows.

This function is exposed to help with debugging and logging. Do not use it to prepare queries for execution.

The query string must contain exactly one substitution group, identified by the SQL keyword "VALUES" (case insensitive) followed by an "(" character, a series of one or more "?" characters separated by commas, and a ")" character. White space in a substitution group is permitted.

Throws FormatError if the query string could not be formatted correctly.

Format a query string.

This function is exposed to help with debugging and logging. Do not use it to prepare queries for execution.

String parameters are escaped according to the character set in use on the Connection.

Throws FormatError if the query string could not be formatted correctly.