Copyright | (c) Eitan Chatav 2019 |
---|---|
Maintainer | eitan@morphism.tech |
Stability | experimental |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
Squeal.PostgreSQL.Session.Transaction
Contents
Description
transaction control language
Synopsis
- type Transaction db x = forall m. (MonadPQ db m, MonadResult m, MonadCatch m) => m x
- transactionally :: (MonadMask tx, MonadResult tx, MonadPQ db tx) => TransactionMode -> Transaction db x -> tx x
- transactionally_ :: (MonadMask tx, MonadResult tx, MonadPQ db tx) => Transaction db x -> tx x
- transactionallyRetry :: (MonadMask tx, MonadResult tx, MonadPQ db tx) => TransactionMode -> Transaction db x -> tx x
- transactionallyRetry_ :: (MonadMask tx, MonadResult tx, MonadPQ db tx) => Transaction db x -> tx x
- ephemerally :: (MonadMask tx, MonadResult tx, MonadPQ db tx) => TransactionMode -> Transaction db x -> tx x
- ephemerally_ :: (MonadMask tx, MonadResult tx, MonadPQ db tx) => Transaction db x -> tx x
- withSavepoint :: ByteString -> Transaction db (Either e x) -> Transaction db (Either e x)
- data TransactionMode = TransactionMode {}
- defaultMode :: TransactionMode
- longRunningMode :: TransactionMode
- retryMode :: TransactionMode
- data IsolationLevel
- data AccessMode
- data DeferrableMode
Transaction
type Transaction db x = forall m. (MonadPQ db m, MonadResult m, MonadCatch m) => m x Source #
A type of "safe" Transaction
s,
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
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.
Arguments
:: (MonadMask tx, MonadResult tx, MonadPQ db tx) | |
=> Transaction db x | run inside a transaction |
-> tx x |
Run a computation transactionally_
, in defaultMode
.
Arguments
:: (MonadMask tx, MonadResult tx, MonadPQ db tx) | |
=> TransactionMode | |
-> Transaction db x | run inside a transaction |
-> tx x |
transactionallyRetry_ Source #
Arguments
:: (MonadMask tx, MonadResult tx, MonadPQ db tx) | |
=> Transaction db x | run inside a transaction |
-> tx x |
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.
Arguments
:: (MonadMask tx, MonadResult tx, MonadPQ db tx) | |
=> Transaction db x | run inside an ephemeral transaction |
-> tx x |
Run a computation ephemerally
in defaultMode
.
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
data TransactionMode Source #
The available transaction characteristics are the transaction IsolationLevel
,
the transaction AccessMode
(ReadWrite
or ReadOnly
), and the DeferrableMode
.
Constructors
TransactionMode | |
Fields |
Instances
Show TransactionMode Source # | |
Defined in Squeal.PostgreSQL.Session.Transaction.Unsafe Methods showsPrec :: Int -> TransactionMode -> ShowS # show :: TransactionMode -> String # showList :: [TransactionMode] -> ShowS # | |
Eq TransactionMode Source # | |
Defined in Squeal.PostgreSQL.Session.Transaction.Unsafe Methods (==) :: TransactionMode -> TransactionMode -> Bool # (/=) :: TransactionMode -> TransactionMode -> Bool # | |
RenderSQL TransactionMode Source # | Render a |
Defined in Squeal.PostgreSQL.Session.Transaction.Unsafe Methods |
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. |
Instances
Show IsolationLevel Source # | |
Defined in Squeal.PostgreSQL.Session.Transaction.Unsafe Methods showsPrec :: Int -> IsolationLevel -> ShowS # show :: IsolationLevel -> String # showList :: [IsolationLevel] -> ShowS # | |
Eq IsolationLevel Source # | |
Defined in Squeal.PostgreSQL.Session.Transaction.Unsafe Methods (==) :: IsolationLevel -> IsolationLevel -> Bool # (/=) :: IsolationLevel -> IsolationLevel -> Bool # | |
RenderSQL IsolationLevel Source # | Render an |
Defined in Squeal.PostgreSQL.Session.Transaction.Unsafe Methods renderSQL :: IsolationLevel -> ByteString Source # |
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.
Instances
Show AccessMode Source # | |
Defined in Squeal.PostgreSQL.Session.Transaction.Unsafe Methods showsPrec :: Int -> AccessMode -> ShowS # show :: AccessMode -> String # showList :: [AccessMode] -> ShowS # | |
Eq AccessMode Source # | |
Defined in Squeal.PostgreSQL.Session.Transaction.Unsafe | |
RenderSQL AccessMode Source # | Render an |
Defined in Squeal.PostgreSQL.Session.Transaction.Unsafe Methods renderSQL :: AccessMode -> ByteString Source # |
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 |
Instances
Show DeferrableMode Source # | |
Defined in Squeal.PostgreSQL.Session.Transaction.Unsafe Methods showsPrec :: Int -> DeferrableMode -> ShowS # show :: DeferrableMode -> String # showList :: [DeferrableMode] -> ShowS # | |
Eq DeferrableMode Source # | |
Defined in Squeal.PostgreSQL.Session.Transaction.Unsafe Methods (==) :: DeferrableMode -> DeferrableMode -> Bool # (/=) :: DeferrableMode -> DeferrableMode -> Bool # | |
RenderSQL DeferrableMode Source # | Render a |
Defined in Squeal.PostgreSQL.Session.Transaction.Unsafe Methods renderSQL :: DeferrableMode -> ByteString Source # |