begriffs open source - ai-pg/blob - full-docs/man7/SET_TRANSACTION.7

   1 '\" t
   2 .\"     Title: SET TRANSACTION
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "SET TRANSACTION" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 SET_TRANSACTION \- set the characteristics of the current transaction
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 SET TRANSACTION \fItransaction_mode\fR [, \&.\&.\&.]
  36 SET TRANSACTION SNAPSHOT \fIsnapshot_id\fR
  37 SET SESSION CHARACTERISTICS AS TRANSACTION \fItransaction_mode\fR [, \&.\&.\&.]
  38
  39 where \fItransaction_mode\fR is one of:
  40
  41     ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED }
  42     READ WRITE | READ ONLY
  43     [ NOT ] DEFERRABLE
  44 .fi
  45 .SH "DESCRIPTION"
  46 .PP
  47 The
  48 \fBSET TRANSACTION\fR
  49 command sets the characteristics of the current transaction\&. It has no effect on any subsequent transactions\&.
  50 \fBSET SESSION CHARACTERISTICS\fR
  51 sets the default transaction characteristics for subsequent transactions of a session\&. These defaults can be overridden by
  52 \fBSET TRANSACTION\fR
  53 for an individual transaction\&.
  54 .PP
  55 The available transaction characteristics are the transaction isolation level, the transaction access mode (read/write or read\-only), and the deferrable mode\&. In addition, a snapshot can be selected, though only for the current transaction, not as a session default\&.
  56 .PP
  57 The isolation level of a transaction determines what data the transaction can see when other transactions are running concurrently:
  58 .PP
  59 READ COMMITTED
  60 .RS 4
  61 A statement can only see rows committed before it began\&. This is the default\&.
  62 .RE
  63 .PP
  64 REPEATABLE READ
  65 .RS 4
  66 All statements of the current transaction can only see rows committed before the first query or data\-modification statement was executed in this transaction\&.
  67 .RE
  68 .PP
  69 SERIALIZABLE
  70 .RS 4
  71 All statements of the current transaction can only see rows committed before the first query or data\-modification statement was executed in this transaction\&. If a pattern of reads and writes among concurrent serializable transactions would create a situation which could not have occurred for any serial (one\-at\-a\-time) execution of those transactions, one of them will be rolled back with a
  72 serialization_failure
  73 error\&.
  74 .RE
  75 The SQL standard defines one additional level,
  76 READ UNCOMMITTED\&. In
  77 PostgreSQL
  78 READ UNCOMMITTED
  79 is treated as
  80 READ COMMITTED\&.
  81 .PP
  82 The transaction isolation level cannot be changed after the first query or data\-modification statement (\fBSELECT\fR,
  83 \fBINSERT\fR,
  84 \fBDELETE\fR,
  85 \fBUPDATE\fR,
  86 \fBMERGE\fR,
  87 \fBFETCH\fR, or
  88 \fBCOPY\fR) of a transaction has been executed\&. See
  89 Chapter\ \&13
  90 for more information about transaction isolation and concurrency control\&.
  91 .PP
  92 The transaction access mode determines whether the transaction is read/write or read\-only\&. Read/write is the default\&. When a transaction is read\-only, the following SQL commands are disallowed:
  93 \fBINSERT\fR,
  94 \fBUPDATE\fR,
  95 \fBDELETE\fR,
  96 \fBMERGE\fR, and
  97 \fBCOPY FROM\fR
  98 if the table they would write to is not a temporary table; all
  99 CREATE,
 100 ALTER, and
 101 DROP
 102 commands;
 103 COMMENT,
 104 GRANT,
 105 REVOKE,
 106 TRUNCATE; and
 107 EXPLAIN ANALYZE
 108 and
 109 EXECUTE
 110 if the command they would execute is among those listed\&. This is a high\-level notion of read\-only that does not prevent all writes to disk\&.
 111 .PP
 112 The
 113 DEFERRABLE
 114 transaction property has no effect unless the transaction is also
 115 SERIALIZABLE
 116 and
 117 READ ONLY\&. 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
 118 SERIALIZABLE
 119 transaction and without any risk of contributing to or being canceled by a serialization failure\&. This mode is well suited for long\-running reports or backups\&.
 120 .PP
 121 The
 122 SET TRANSACTION SNAPSHOT
 123 command allows a new transaction to run with the same
 124 snapshot
 125 as an existing transaction\&. The pre\-existing transaction must have exported its snapshot with the
 126 pg_export_snapshot
 127 function (see
 128 Section\ \&9.28.5)\&. That function returns a snapshot identifier, which must be given to
 129 SET TRANSACTION SNAPSHOT
 130 to specify which snapshot is to be imported\&. The identifier must be written as a string literal in this command, for example
 131 \*(Aq00000003\-0000001B\-1\*(Aq\&.
 132 SET TRANSACTION SNAPSHOT
 133 can only be executed at the start of a transaction, before the first query or data\-modification statement (\fBSELECT\fR,
 134 \fBINSERT\fR,
 135 \fBDELETE\fR,
 136 \fBUPDATE\fR,
 137 \fBMERGE\fR,
 138 \fBFETCH\fR, or
 139 \fBCOPY\fR) of the transaction\&. Furthermore, the transaction must already be set to
 140 SERIALIZABLE
 141 or
 142 REPEATABLE READ
 143 isolation level (otherwise, the snapshot would be discarded immediately, since
 144 READ COMMITTED
 145 mode takes a new snapshot for each command)\&. If the importing transaction uses
 146 SERIALIZABLE
 147 isolation level, then the transaction that exported the snapshot must also use that isolation level\&. Also, a non\-read\-only serializable transaction cannot import a snapshot from a read\-only transaction\&.
 148 .SH "NOTES"
 149 .PP
 150 If
 151 \fBSET TRANSACTION\fR
 152 is executed without a prior
 153 \fBSTART TRANSACTION\fR
 154 or
 155 \fBBEGIN\fR, it emits a warning and otherwise has no effect\&.
 156 .PP
 157 It is possible to dispense with
 158 \fBSET TRANSACTION\fR
 159 by instead specifying the desired
 160 \fItransaction_modes\fR
 161 in
 162 \fBBEGIN\fR
 163 or
 164 \fBSTART TRANSACTION\fR\&. But that option is not available for
 165 \fBSET TRANSACTION SNAPSHOT\fR\&.
 166 .PP
 167 The session default transaction modes can also be set or examined via the configuration parameters
 168 default_transaction_isolation,
 169 default_transaction_read_only, and
 170 default_transaction_deferrable\&. (In fact
 171 \fBSET SESSION CHARACTERISTICS\fR
 172 is just a verbose equivalent for setting these variables with
 173 \fBSET\fR\&.) This means the defaults can be set in the configuration file, via
 174 \fBALTER DATABASE\fR, etc\&. Consult
 175 Chapter\ \&19
 176 for more information\&.
 177 .PP
 178 The current transaction\*(Aqs modes can similarly be set or examined via the configuration parameters
 179 transaction_isolation,
 180 transaction_read_only, and
 181 transaction_deferrable\&. Setting one of these parameters acts the same as the corresponding
 182 \fBSET TRANSACTION\fR
 183 option, with the same restrictions on when it can be done\&. However, these parameters cannot be set in the configuration file, or from any source other than live SQL\&.
 184 .SH "EXAMPLES"
 185 .PP
 186 To begin a new transaction with the same snapshot as an already existing transaction, first export the snapshot from the existing transaction\&. That will return the snapshot identifier, for example:
 187 .sp
 188 .if n \{\
 189 .RS 4
 190 .\}
 191 .nf
 192 BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ;
 193 SELECT pg_export_snapshot();
 194  pg_export_snapshot
 195 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 196  00000003\-0000001B\-1
 197 (1 row)
 198 .fi
 199 .if n \{\
 200 .RE
 201 .\}
 202 .sp
 203 Then give the snapshot identifier in a
 204 \fBSET TRANSACTION SNAPSHOT\fR
 205 command at the beginning of the newly opened transaction:
 206 .sp
 207 .if n \{\
 208 .RS 4
 209 .\}
 210 .nf
 211 BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ;
 212 SET TRANSACTION SNAPSHOT \*(Aq00000003\-0000001B\-1\*(Aq;
 213 .fi
 214 .if n \{\
 215 .RE
 216 .\}
 217 .SH "COMPATIBILITY"
 218 .PP
 219 These commands are defined in the
 220 SQL
 221 standard, except for the
 222 DEFERRABLE
 223 transaction mode and the
 224 \fBSET TRANSACTION SNAPSHOT\fR
 225 form, which are
 226 PostgreSQL
 227 extensions\&.
 228 .PP
 229 SERIALIZABLE
 230 is the default transaction isolation level in the standard\&. In
 231 PostgreSQL
 232 the default is ordinarily
 233 READ COMMITTED, but you can change it as mentioned above\&.
 234 .PP
 235 In the SQL standard, there is one other transaction characteristic that can be set with these commands: the size of the diagnostics area\&. This concept is specific to embedded SQL, and therefore is not implemented in the
 236 PostgreSQL
 237 server\&.
 238 .PP
 239 The SQL standard requires commas between successive
 240 \fItransaction_modes\fR, but for historical reasons
 241 PostgreSQL
 242 allows the commas to be omitted\&.