squeal-postgresql-0.9.0.0: Squeal PostgreSQL Library
Copyright(c) Eitan Chatav 2019
Maintainereitan@morphism.tech
Stabilityexperimental
Safe HaskellNone
LanguageHaskell2010

Squeal.PostgreSQL.Session.Transaction

Description

transaction control language

Synopsis

Transaction

type Transaction db x = forall m. (MonadPQ db m, MonadResult m, MonadCatch m) => m x Source #

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

transactionally Source #

Arguments

:: (MonadMask tx, MonadResult tx, MonadPQ db tx) 
=> TransactionMode 
-> Transaction db x

run inside a transaction

-> tx x 

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

transactionally_ Source #

Arguments

:: (MonadMask tx, MonadResult tx, MonadPQ db tx) 
=> Transaction db x

run inside a transaction

-> tx x 

Run a computation transactionally_, in defaultMode.

transactionallyRetry Source #

Arguments

:: (MonadMask tx, MonadResult tx, MonadPQ db tx) 
=> TransactionMode 
-> Transaction db x

run inside a transaction

-> tx x 

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_ Source #

Arguments

:: (MonadMask tx, MonadResult tx, MonadPQ db tx) 
=> Transaction db x

run inside a transaction

-> tx x 

ephemerally Source #

Arguments

:: (MonadMask tx, MonadResult tx, MonadPQ db tx) 
=> TransactionMode 
-> Transaction db x

run inside an ephemeral transaction

-> tx x 

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

ephemerally_ Source #

Arguments

:: (MonadMask tx, MonadResult tx, MonadPQ db tx) 
=> Transaction db x

run inside an ephemeral transaction

-> tx x 

Run a computation ephemerally in defaultMode.

withSavepoint Source #

Arguments

:: ByteString

savepoint name

-> Transaction db (Either e x) 
-> Transaction db (Either e x) 

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.

Transaction Mode

longRunningMode :: TransactionMode Source #

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

retryMode :: TransactionMode Source #

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

data IsolationLevel Source #

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.

Constructors

Serializable

Dirty read is not possible. Nonrepeatable read is not possible. Phantom read is not possible. Serialization anomaly is not possible.

RepeatableRead

Dirty read is not possible. Nonrepeatable read is not possible. Phantom read is not possible. Serialization anomaly is possible.

ReadCommitted

Dirty read is not possible. Nonrepeatable read is possible. Phantom read is possible. Serialization anomaly is possible.

ReadUncommitted

Dirty read is not possible. Nonrepeatable read is possible. Phantom read is possible. Serialization anomaly is possible.

data AccessMode Source #

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.

Constructors

ReadWrite 
ReadOnly 

data DeferrableMode Source #

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.

Constructors

Deferrable 
NotDeferrable