A type of "safe" Transactions, do-blocks that permit only database operations, pure functions, and synchronous exception handling forbidding arbitrary IO operations.

To permit arbitrary IO,

>>> import qualified Squeal.PostgreSQL.Session.Transaction.Unsafe as Unsafe

Then use the Unsafe qualified form of the functions below.

A safe Transaction can be run in two ways,

1) it can be run directly in IO because as a universally quantified type, Transaction db x permits interpretation in "subtypes" like (MonadPQ db m, MonadIO m, MonadCatch m) => m x or PQ db db IO x

2) it can be run in a transaction block, using transactionally, ephemerally, or transactionallyRetry

Run a computation transactionally; first begin, then run the computation, onException rollback and rethrow the exception, otherwise commit and return the result.

Run a computation transactionally_, in defaultMode.

transactionallyRetry a computation;

• first begin,
• then try the computation,
• if it raises a serialization failure or deadloack detection, then rollback and restart the transaction,
• if it raises any other exception then rollback and rethrow the exception,
• otherwise commit and return the result.

transactionallyRetry in retryMode.

Run a computation ephemerally; Like transactionally but always rollback, useful in testing.

Run a computation ephemerally in defaultMode.

withSavepoint, used in a transaction block, allows a form of nested transactions, creating a savepoint, then running a transaction, rolling back to the savepoint if it returned Left, then releasing the savepoint and returning transaction's result.

Make sure to run withSavepoint in a transaction block, not directly or you will provoke a SQL exception.

The available transaction characteristics are the transaction IsolationLevel, the transaction AccessMode (ReadWrite or ReadOnly), and the DeferrableMode.

TransactionMode with a ReadCommitted IsolationLevel, ReadWrite AccessMode and NotDeferrable DeferrableMode.

TransactionMode with a Serializable IsolationLevel, ReadOnly AccessMode and Deferrable DeferrableMode. This mode is well suited for long-running reports or backups.

TransactionMode with a Serializable IsolationLevel, ReadWrite AccessMode and NotDeferrable DeferrableMode, appropriate for short-lived queries or manipulations.

The SQL standard defines four levels of transaction isolation. The most strict is Serializable, which is defined by the standard in a paragraph which says that any concurrent execution of a set of Serializable transactions is guaranteed to produce the same effect as running them one at a time in some order. The other three levels are defined in terms of phenomena, resulting from interaction between concurrent transactions, which must not occur at each level. The phenomena which are prohibited at various levels are:

Dirty read: A transaction reads data written by a concurrent uncommitted transaction.

Nonrepeatable read: A transaction re-reads data it has previously read and finds that data has been modified by another transaction (that committed since the initial read).

Phantom read: A transaction re-executes a query returning a set of rows that satisfy a search condition and finds that the set of rows satisfying the condition has changed due to another recently-committed transaction.

Serialization anomaly: The result of successfully committing a group of transactions is inconsistent with all possible orderings of running those transactions one at a time.

In PostgreSQL, you can request any of the four standard transaction isolation levels, but internally only three distinct isolation levels are implemented, i.e. PostgreSQL's ReadUncommitted mode behaves like ReadCommitted. This is because it is the only sensible way to map the standard isolation levels to PostgreSQL's multiversion concurrency control architecture.

The transaction access mode determines whether the transaction is ReadWrite or ReadOnly. ReadWrite is the default. When a transaction is ReadOnly, the following SQL commands are disallowed: INSERT, UPDATE, DELETE, and COPY FROM if the table they would write to is not a temporary table; all CREATE, ALTER, and DROP commands; COMMENT, GRANT, REVOKE, TRUNCATE; and EXPLAIN ANALYZE and EXECUTE if the command they would execute is among those listed. This is a high-level notion of ReadOnly that does not prevent all writes to disk.

The Deferrable transaction property has no effect unless the transaction is also Serializable and ReadOnly. When all three of these properties are selected for a transaction, the transaction may block when first acquiring its snapshot, after which it is able to run without the normal overhead of a Serializable transaction and without any risk of contributing to or being canceled by a serialization failure. This longRunningMode is well suited for long-running reports or backups.