begriffs open source - ai-pg/blob - full-docs/html/sql-set-transaction.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SET TRANSACTION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-set-session-authorization.html" title="SET SESSION AUTHORIZATION" /><link rel="next" href="sql-show.html" title="SHOW" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SET TRANSACTION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-set-session-authorization.html" title="SET SESSION AUTHORIZATION">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-show.html" title="SHOW">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-SET-TRANSACTION"><div class="titlepage"></div><a id="id-1.9.3.178.1" class="indexterm"></a><a id="id-1.9.3.178.2" class="indexterm"></a><a id="id-1.9.3.178.3" class="indexterm"></a><a id="id-1.9.3.178.4" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SET TRANSACTION</span></h2><p>SET TRANSACTION — set the characteristics of the current transaction</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
   3 SET TRANSACTION <em class="replaceable"><code>transaction_mode</code></em> [, ...]
   4 SET TRANSACTION SNAPSHOT <em class="replaceable"><code>snapshot_id</code></em>
   5 SET SESSION CHARACTERISTICS AS TRANSACTION <em class="replaceable"><code>transaction_mode</code></em> [, ...]
   6
   7 <span class="phrase">where <em class="replaceable"><code>transaction_mode</code></em> is one of:</span>
   8
   9     ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED }
  10     READ WRITE | READ ONLY
  11     [ NOT ] DEFERRABLE
  12 </pre></div><div class="refsect1" id="id-1.9.3.178.8"><h2>Description</h2><p>
  13    The <code class="command">SET TRANSACTION</code> command sets the
  14    characteristics of the current transaction. It has no effect on any
  15    subsequent transactions.  <code class="command">SET SESSION
  16    CHARACTERISTICS</code> sets the default transaction
  17    characteristics for subsequent transactions of a session.  These
  18    defaults can be overridden by <code class="command">SET TRANSACTION</code>
  19    for an individual transaction.
  20   </p><p>
  21    The available transaction characteristics are the transaction
  22    isolation level, the transaction access mode (read/write or
  23    read-only), and the deferrable mode.
  24    In addition, a snapshot can be selected, though only for the current
  25    transaction, not as a session default.
  26   </p><p>
  27    The isolation level of a transaction determines what data the
  28    transaction can see when other transactions are running concurrently:
  29
  30    </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">READ COMMITTED</code></span></dt><dd><p>
  31        A statement can only see rows committed before it began. This
  32        is the default.
  33       </p></dd><dt><span class="term"><code class="literal">REPEATABLE READ</code></span></dt><dd><p>
  34        All statements of the current transaction can only see rows committed
  35        before the first query or data-modification statement was executed in
  36        this transaction.
  37       </p></dd><dt><span class="term"><code class="literal">SERIALIZABLE</code></span></dt><dd><p>
  38        All statements of the current transaction can only see rows committed
  39        before the first query or data-modification statement was executed in
  40        this transaction.  If a pattern of reads and writes among concurrent
  41        serializable transactions would create a situation which could not
  42        have occurred for any serial (one-at-a-time) execution of those
  43        transactions, one of them will be rolled back with a
  44        <code class="literal">serialization_failure</code> error.
  45       </p></dd></dl></div><p>
  46
  47    The SQL standard defines one additional level, <code class="literal">READ
  48    UNCOMMITTED</code>.
  49    In <span class="productname">PostgreSQL</span> <code class="literal">READ
  50    UNCOMMITTED</code> is treated as <code class="literal">READ COMMITTED</code>.
  51   </p><p>
  52    The transaction isolation level cannot be changed after the first query or
  53    data-modification statement (<code class="command">SELECT</code>,
  54    <code class="command">INSERT</code>, <code class="command">DELETE</code>,
  55    <code class="command">UPDATE</code>, <code class="command">MERGE</code>,
  56    <code class="command">FETCH</code>, or
  57    <code class="command">COPY</code>) of a transaction has been executed.  See
  58    <a class="xref" href="mvcc.html" title="Chapter 13. Concurrency Control">Chapter 13</a> for more information about transaction
  59    isolation and concurrency control.
  60   </p><p>
  61    The transaction access mode determines whether the transaction is
  62    read/write or read-only.  Read/write is the default.  When a
  63    transaction is read-only, the following SQL commands are
  64    disallowed: <code class="command">INSERT</code>, <code class="command">UPDATE</code>,
  65    <code class="command">DELETE</code>, <code class="command">MERGE</code>, and
  66    <code class="command">COPY FROM</code> if the
  67    table they would write to is not a temporary table; all
  68    <code class="literal">CREATE</code>, <code class="literal">ALTER</code>, and
  69    <code class="literal">DROP</code> commands; <code class="literal">COMMENT</code>,
  70    <code class="literal">GRANT</code>, <code class="literal">REVOKE</code>,
  71    <code class="literal">TRUNCATE</code>; and <code class="literal">EXPLAIN ANALYZE</code>
  72    and <code class="literal">EXECUTE</code> if the command they would execute is
  73    among those listed.  This is a high-level notion of read-only that
  74    does not prevent all writes to disk.
  75   </p><p>
  76    The <code class="literal">DEFERRABLE</code> transaction property has no effect
  77    unless the transaction is also <code class="literal">SERIALIZABLE</code> and
  78    <code class="literal">READ ONLY</code>.  When all three of these properties are
  79    selected for a
  80    transaction, the transaction may block when first acquiring its snapshot,
  81    after which it is able to run without the normal overhead of a
  82    <code class="literal">SERIALIZABLE</code> transaction and without any risk of
  83    contributing to or being canceled by a serialization failure.  This mode
  84    is well suited for long-running reports or backups.
  85   </p><p>
  86    The <code class="literal">SET TRANSACTION SNAPSHOT</code> command allows a new
  87    transaction to run with the same <em class="firstterm">snapshot</em> as an existing
  88    transaction.  The pre-existing transaction must have exported its snapshot
  89    with the <code class="literal">pg_export_snapshot</code> function (see <a class="xref" href="functions-admin.html#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION" title="9.28.5. Snapshot Synchronization Functions">Section 9.28.5</a>).  That function returns a
  90    snapshot identifier, which must be given to <code class="literal">SET TRANSACTION
  91    SNAPSHOT</code> to specify which snapshot is to be imported.  The
  92    identifier must be written as a string literal in this command, for example
  93    <code class="literal">'00000003-0000001B-1'</code>.
  94    <code class="literal">SET TRANSACTION SNAPSHOT</code> can only be executed at the
  95    start of a transaction, before the first query or
  96    data-modification statement (<code class="command">SELECT</code>,
  97    <code class="command">INSERT</code>, <code class="command">DELETE</code>,
  98    <code class="command">UPDATE</code>, <code class="command">MERGE</code>,
  99    <code class="command">FETCH</code>, or
 100    <code class="command">COPY</code>) of the transaction.  Furthermore, the transaction
 101    must already be set to <code class="literal">SERIALIZABLE</code> or
 102    <code class="literal">REPEATABLE READ</code> isolation level (otherwise, the snapshot
 103    would be discarded immediately, since <code class="literal">READ COMMITTED</code> mode takes
 104    a new snapshot for each command).  If the importing transaction uses
 105    <code class="literal">SERIALIZABLE</code> isolation level, then the transaction that
 106    exported the snapshot must also use that isolation level.  Also, a
 107    non-read-only serializable transaction cannot import a snapshot from a
 108    read-only transaction.
 109   </p></div><div class="refsect1" id="id-1.9.3.178.9"><h2>Notes</h2><p>
 110    If <code class="command">SET TRANSACTION</code> is executed without a prior
 111    <code class="command">START TRANSACTION</code> or <code class="command">BEGIN</code>,
 112    it emits a warning and otherwise has no effect.
 113   </p><p>
 114    It is possible to dispense with <code class="command">SET TRANSACTION</code>
 115    by instead specifying the desired <em class="replaceable"><code>transaction_modes</code></em> in
 116    <code class="command">BEGIN</code> or <code class="command">START TRANSACTION</code>.
 117    But that option is not available for <code class="command">SET TRANSACTION
 118    SNAPSHOT</code>.
 119   </p><p>
 120    The session default transaction modes can also be set or examined via the
 121    configuration parameters <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TRANSACTION-ISOLATION">default_transaction_isolation</a>,
 122    <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TRANSACTION-READ-ONLY">default_transaction_read_only</a>, and
 123    <a class="xref" href="runtime-config-client.html#GUC-DEFAULT-TRANSACTION-DEFERRABLE">default_transaction_deferrable</a>.
 124    (In fact <code class="command">SET SESSION CHARACTERISTICS</code> is just a
 125    verbose equivalent for setting these variables with <code class="command">SET</code>.)
 126    This means the defaults can be set in the configuration file, via
 127    <code class="command">ALTER DATABASE</code>, etc.  Consult <a class="xref" href="runtime-config.html" title="Chapter 19. Server Configuration">Chapter 19</a>
 128    for more information.
 129   </p><p>
 130    The current transaction's modes can similarly be set or examined via the
 131    configuration parameters <a class="xref" href="runtime-config-client.html#GUC-TRANSACTION-ISOLATION">transaction_isolation</a>,
 132    <a class="xref" href="runtime-config-client.html#GUC-TRANSACTION-READ-ONLY">transaction_read_only</a>, and
 133    <a class="xref" href="runtime-config-client.html#GUC-TRANSACTION-DEFERRABLE">transaction_deferrable</a>.  Setting one of these
 134    parameters acts the same as the corresponding <code class="command">SET
 135    TRANSACTION</code> option, with the same restrictions on when it can
 136    be done.  However, these parameters cannot be set in the configuration
 137    file, or from any source other than live SQL.
 138   </p></div><div class="refsect1" id="id-1.9.3.178.10"><h2>Examples</h2><p>
 139    To begin a new transaction with the same snapshot as an already
 140    existing transaction, first export the snapshot from the existing
 141    transaction. That will return the snapshot identifier, for example:
 142
 143 </p><pre class="programlisting">
 144 BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ;
 145 SELECT pg_export_snapshot();
 146  pg_export_snapshot
 147 ---------------------
 148  00000003-0000001B-1
 149 (1 row)
 150 </pre><p>
 151
 152    Then give the snapshot identifier in a <code class="command">SET TRANSACTION
 153    SNAPSHOT</code> command at the beginning of the newly opened
 154    transaction:
 155
 156 </p><pre class="programlisting">
 157 BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ;
 158 SET TRANSACTION SNAPSHOT '00000003-0000001B-1';
 159 </pre></div><div class="refsect1" id="R1-SQL-SET-TRANSACTION-3"><h2>Compatibility</h2><p>
 160    These commands are defined in the <acronym class="acronym">SQL</acronym> standard,
 161    except for the <code class="literal">DEFERRABLE</code> transaction mode
 162    and the <code class="command">SET TRANSACTION SNAPSHOT</code> form, which are
 163    <span class="productname">PostgreSQL</span> extensions.
 164   </p><p>
 165    <code class="literal">SERIALIZABLE</code> is the default transaction
 166    isolation level in the standard.  In
 167    <span class="productname">PostgreSQL</span> the default is ordinarily
 168    <code class="literal">READ COMMITTED</code>, but you can change it as
 169    mentioned above.
 170   </p><p>
 171    In the SQL standard, there is one other transaction characteristic
 172    that can be set with these commands: the size of the diagnostics
 173    area.  This concept is specific to embedded SQL, and therefore is
 174    not implemented in the <span class="productname">PostgreSQL</span> server.
 175   </p><p>
 176    The SQL standard requires commas between successive <em class="replaceable"><code>transaction_modes</code></em>, but for historical
 177    reasons <span class="productname">PostgreSQL</span> allows the commas to be
 178    omitted.
 179   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-set-session-authorization.html" title="SET SESSION AUTHORIZATION">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-show.html" title="SHOW">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SET SESSION AUTHORIZATION </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SHOW</td></tr></table></div></body></html>