Documentation

Create a PostgreSQL connection pool and run the given action. The pool is properly released after the action finishes using it. Note that you should not use the given ConnectionPool outside the action since it may already have been released. The provided action should use runSqlConn and *not* runReaderT because the former brackets the database action with transaction begin/commit.

Same as withPostgresPool, but takes a callback for obtaining the server version (to work around an Amazon Redshift bug).

Since: 2.6.2

Same as withPostgresqlPool, but can be configured with PostgresConf and PostgresConfHooks.

Since: 2.11.0.0

Same as withPostgresqlPool, but with the createPostgresqlPoolModified feature.

Since: 2.13.5.0

Same as withPostgresqlPool, but with the createPostgresqlPoolModifiedWithVersion feature.

Since: 2.13.5.0

Same as withPostgresqlPool, but instead of opening a pool of connections, only one connection is opened. The provided action should use runSqlConn and *not* runReaderT because the former brackets the database action with transaction begin/commit.

Same as withPostgresqlConn, but takes a callback for obtaining the server version (to work around an Amazon Redshift bug).

Since: 2.6.2

Create a PostgreSQL connection pool. Note that it's your responsibility to properly close the connection pool when unneeded. Use withPostgresqlPool for an automatic resource control.

Same as createPostgresqlPool, but additionally takes a callback function for some connection-specific tweaking to be performed after connection creation. This could be used, for example, to change the schema. For more information, see:

https://groups.google.com/d/msg/yesodweb/qUXrEN_swEo/O0pFwqwQIdcJ

Since: 2.1.3

Same as other similarly-named functions in this module, but takes callbacks for obtaining the server version (to work around an Amazon Redshift bug) and connection-specific tweaking (to change the schema).

Since: 2.6.2

Same as createPostgresqlPoolModifiedWithVersion, but takes a custom connection-creation function.

The only time you should reach for this function is if you need to write custom logic for creating a connection to the database.

Since: 2.13.6

Same as createPostgresqlPool, but can be configured with PostgresConf and PostgresConfHooks.

Since: 2.11.0.0

A libpq connection string. A simple example of connection string would be "host=localhost port=5432 user=test dbname=test password=test". Please read libpq's documentation at https://www.postgresql.org/docs/current/static/libpq-connect.html for more details on how to create such strings.

This type is used to determine how to update rows using Postgres' INSERT ... ON CONFLICT KEY UPDATE functionality, exposed via upsertWhere and upsertManyWhere in this library.

Since: 2.12.1.0

Copy the field directly from the record.

Since: 2.12.1.0

Copy the field into the database only if the value in the corresponding record is non-NULL.

@since 2.12.1.0

Copy the field into the database only if the value in the corresponding record is non-empty, where "empty" means the Monoid definition for mempty. Useful for Text, String, ByteString, etc.

The resulting HandleUpdateCollision type is useful for the upsertManyWhere function.

@since 2.12.1.0

Copy the field into the database only if the field is not equal to the provided value. This is useful to avoid copying weird nullary data into the database.

The resulting HandleUpdateCollision type is useful for the upsertMany function.

@since 2.12.1.0

Exclude any record field if it doesn't match the filter record. Used only in upsertWhere and upsertManyWhere

TODO: we could probably make a sum type for the Filter record that's passed into the upsertWhere and upsertManyWhere methods that has similar behavior to the HandleCollisionUpdate type.

Since: 2.12.1.0

Information required to connect to a PostgreSQL database using persistent's generic facilities. These values are the same that are given to withPostgresqlPool.

Represent Postgres interval using NominalDiffTime

Since: 2.11.0.0

Postgres specific upsertWhere. This method does the following: It will insert a record if no matching unique key exists. If a unique key exists, it will update the relevant field with a user-supplied value, however, it will only do this update on a user-supplied condition. For example, here's how this method could be called like such:

upsertWhere record [recordField =. newValue] [recordField /= newValue]

Called thusly, this method will insert a new record (if none exists) OR update a recordField with a new value assuming the condition in the last block is met.

Since: 2.12.1.0

Postgres specific upsertManyWhere.

The first argument is a list of new records to insert.

If there's unique key collisions for some or all of the proposed insertions, you can use the second argument to specify which fields, under which conditions (using HandleUpdateCollision strategies,) will be copied from each proposed, conflicting new record onto its corresponding row already present in the database. Helpers such as copyField, copyUnlessEq, copyUnlessNull and copyUnlessEmpty are exported from this module to help with this, as well as the constructors for HandleUpdateCollision. For example, you may have a patch of updates to apply, some of which are NULL to represent "no change"; you'd use copyUnlessNull for each applicable field in this case so any new values in the patch which are NULL don't accidentally overwrite existing values in the database which are non-NULL.

Further updates to the matching records already in the database can be specified in the third argument, these are arbitrary updates independent of the new records proposed for insertion. For example, you can use this to update a timestamp or a counter for all conflicting rows.

You can use the fourth argument to provide arbitrary conditions to constrain the above updates. This way, you can choose to only alter a subset of the conflicting existing rows while leaving the others alone. For example, you may want to copy fields from new records and update a timestamp only when the corresponding existing row hasn't been soft-deleted.

For example,

  upsertManyWhere
    [record]                         -- (1)
    [ copyField recordField1         -- (2)
    , copyUnlessEq recordField2      -- (3)
    , copyUnlessNull recordField3    -- (4)
    ]
    [recordField4 =. arbitraryValue] -- (5)
    [recordField4 !=. anotherValue]  -- (6)

1. new records to insert if there's no conflicts
2. for each conflicting existing row, replace the value of recordField1 with the one present in the conflicting new record
3. only replace the existing value if it's different from the one present in the conflicting new record
4. only replace the existing value if the new value is non-NULL (i.e. don't replace existing values with NULLs.)
5. update recordField4 with an arbitrary new value
6. only apply the above updates for conflicting rows that meet this condition

Called thusly, this method will insert a new record (if none exists) OR it will copy three fields (recordField1, recordField2, recordField3) from the record proposed from insertion onto the existing row in the database following three different HandleUpdateCollision strategies, it will also update recordField4 with an arbitrary arbitraryValue. Both sets of updates will only be applied if the row already present in the database has a recordField4 whose value is not arbitraryValue. The corresponding SQL might look like this:

  INSERT INTO table(recordField1, recordField2, recordField3, recordField4, recordField5)
  VALUES
    (newValue1, newValue2, newValue3, newValue4, newValue5)
  ON CONFLICT (recordField2, recordField3) -- let's imagine these two columns define a unique constraint
  DO UPDATE
    SET
      recordField1 = EXCLUDED.newValue1, -- EXCLUDED points to the new, conflicting, record; so we're always replacing the old value.
      recordField2 = COALESCE(NULLIF(EXCLUDED.newValue2, table.recordField2), table.recordField2), -- if the values are the same, the NULLIF returns NULL and we coalesce into setting the column to the value it already had (i.e. no change)
      recordField3 = COALESCE(NULLIF(EXCLUDED.newValue3, NULL), table.recordField3), -- if the new value is not null, it will be set; if it's null, we coalesce into not changing the existing value.
      recordField4 = arbitraryValue -- an arbitrary update independent of what's in the EXCLUDED (new) record
    WHERE
      recordField4 <> anotherValue -- only do the above updates if the value for the existing row's recordField4 is not "anotherValue"

Since: 2.12.1.0

Generate a SqlBackend from a Connection.

Generate a SqlBackend from a Connection, but takes a callback for obtaining the server version.

Since: 2.9.1

Gets the PostgreSQL server version

Since: 2.13.6

Access underlying connection, returning Nothing if the SqlBackend provided isn't backed by postgresql-simple.

Since: 2.13.0

Get the SQL string for the table that a PersistEntity represents. Useful for raw SQL queries.

Get the SQL string for the field that an EntityField represents. Useful for raw SQL queries.

Mock a migration even when the database is not present. This function performs the same functionality of printMigration with the difference that an actual database is not needed.

Enable a Postgres extension. See https://www.postgresql.org/docs/current/static/contrib.html for a list.

Hooks for configuring the Persistent/its connection to Postgres

Since: 2.11.0

Default settings for PostgresConfHooks. See the individual fields of PostgresConfHooks for the default values.

Since: 2.11.0

Wrapper for persistent SqlBackends that carry the corresponding Connection.

Since: 2.13.1.0

Create a PostgreSQL connection pool which also exposes the raw connection. The raw counterpart to createPostgresqlPool.

Since: 2.13.1.0

The raw counterpart to createPostgresqlPoolModified.

Since: 2.13.1.0

The raw counterpart to createPostgresqlPoolModifiedWithVersion.

Since: 2.13.1.0

The raw counterpart to createPostgresqlPoolWithConf.

Since: 2.13.1.0

Create the backend given a logging function, server version, mutable statement cell, and connection.

Since: 2.13.6