Combines the result of a query along with a set of locked tables. Used as a return value for the lockingFor_ function.

An explicit lock against some tables. You can create a value of this type using the locked_ function. You can combine these values monoidally to combine multiple locks for use with the withLocks_ function.

Specifies the level of lock that will be taken against a row. See the manual section for more information.

Specifies how we should handle lock conflicts.

See the manual section for more information

Like lockingFor_, but does not require an explicit set of locked tables. This produces an empty FOR .. OF clause.

Lock some tables during the execution of a query. This is rather complicated, and there are several usage examples in the user guide

The Postgres locking clause is rather complex, and beam currently does not check several pre-conditions. It is assumed you kinda know what you're doing.

Things which postgres doesn't like, but beam will do

• Using aggregates within a query that has a locking clause
• Using UNION, INTERSECT, or EXCEPT

See here for more details.

This function accepts a locking strength (UPDATE, SHARE, KEY SHARE, etc), an optional locking option (NOWAIT or SKIP LOCKED), and a query whose rows to lock. The query should return its result wrapped in PgWithLocking, via the withLocks_ or lockAll_ function.

If you want to use the most common behavior (lock all rows in every table mentioned), the lockingAllTablesFor_ function may be what you're after.

Join with a table while locking it explicitly. Provides a PgLockedTables value that can be used with withLocks_ to explicitly lock a table during a SELECT statement

Use with lockingFor_ to lock all tables mentioned in the query

Return and lock the given tables. Typically used as an infix operator. See the the user guide for usage examples

Postgres LATERAL JOIN support

Allows the use of variables introduced on the left side of a JOIN to be used on the right hand side.

Because of the default scoping rules, we can't use the typical monadic bind (>>=) operator to create this join.

Instead, lateral_ takes two arguments. The first is the left hand side of the JOIN. The second is a function that takes the result of the first join and uses those variables to create the right hand side.

For example, to join table A with a subquery that returns the first three rows in B which matches a column in A, ordered by another column in B:

lateral_ (_tableA database) $ \tblA ->
  limit_ 3 $
  ordering_ (\(_, b) -> asc_ (_bField2 b)) $ do
    b <- _tableB database
    guard_ (_bField1 b ==. _aField1 a)
    pure (a, b0

A beam-postgres-specific version of insert, which provides fuller support for the much richer Postgres INSERT syntax. This allows you to specify ON CONFLICT actions. For even more complete support, see insertReturning.

The full Postgres INSERT syntax, supporting conflict actions and the RETURNING CLAUSE. See PgInsertOnConflict for how to specify a conflict action or provide onConflictDefault to preserve the behavior without any ON CONFLICT clause. The last argument takes a newly inserted row and returns the expression to be returned as part of the RETURNING clause. For a backend-agnostic version of this functionality see MonadBeamInsertReturning. Use runInsertReturning to get the results.

The Postgres DEFAULT VALUES clause for the INSERT command.

The most general kind of INSERT that postgres can perform

What to do when an INSERT statement inserts a row into the table tbl that violates a constraint.

By default, Postgres will throw an error when a conflict is detected. This preserves that functionality.

Tells postgres what to do on an INSERT conflict. The first argument is the type of conflict to provide an action for. For example, to only provide an action for certain fields, use conflictingFields. Or to only provide an action over certain fields where a particular condition is met, use conflictingFields. If you have a particular constraint violation in mind, use conflictingConstraint. To perform an action on any conflict, use anyConflict.

See the Postgres documentation.

Perform the action only if the given named constraint is violated

The most general kind of UPDATE that postgres can perform

You can build this from a SqlUpdate by using returning

update tbl where `returning` projection

Run the result with runPgUpdateReturningList

Postgres UPDATE ... RETURNING statement support. The last argument takes the newly inserted row and returns the values to be returned. Use runUpdateReturning to get the results.

The most general kind of DELETE that postgres can perform

You can build this from a SqlDelete by using returning

delete tbl where `returning` projection

Run the result with runPgDeleteReturningList

Postgres DELETE ... RETURNING statement support. The last argument takes the newly inserted row and returns the values to be returned. Use runDeleteReturning to get the results.