| Current File : //usr/share/doc/postgresql-9.2.24/html/sql-set-transaction.html |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>SET TRANSACTION</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.2.24 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="SQL Commands"
HREF="sql-commands.html"><LINK
REL="PREVIOUS"
TITLE="SET SESSION AUTHORIZATION"
HREF="sql-set-session-authorization.html"><LINK
REL="NEXT"
TITLE="SHOW"
HREF="sql-show.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2017-11-06T22:43:11"></HEAD
><BODY
CLASS="REFENTRY"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.2.24 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="SET SESSION AUTHORIZATION"
HREF="sql-set-session-authorization.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="sql-commands.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="SHOW"
HREF="sql-show.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="SQL-SET-TRANSACTION"
></A
>SET TRANSACTION</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN79051"
></A
><H2
>Name</H2
>SET TRANSACTION -- set the characteristics of the current transaction</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN79065"
></A
><H2
>Synopsis</H2
><PRE
CLASS="SYNOPSIS"
>SET TRANSACTION <TT
CLASS="REPLACEABLE"
><I
>transaction_mode</I
></TT
> [, ...]
SET TRANSACTION SNAPSHOT <TT
CLASS="REPLACEABLE"
><I
>snapshot_id</I
></TT
>
SET SESSION CHARACTERISTICS AS TRANSACTION <TT
CLASS="REPLACEABLE"
><I
>transaction_mode</I
></TT
> [, ...]
<SPAN
CLASS="phrase"
><SPAN
CLASS="PHRASE"
>where <TT
CLASS="REPLACEABLE"
><I
>transaction_mode</I
></TT
> is one of:</SPAN
></SPAN
>
ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED }
READ WRITE | READ ONLY
[ NOT ] DEFERRABLE</PRE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN79072"
></A
><H2
>Description</H2
><P
> The <TT
CLASS="COMMAND"
>SET TRANSACTION</TT
> command sets the
characteristics of the current transaction. It has no effect on any
subsequent transactions. <TT
CLASS="COMMAND"
>SET SESSION
CHARACTERISTICS</TT
> sets the default transaction
characteristics for subsequent transactions of a session. These
defaults can be overridden by <TT
CLASS="COMMAND"
>SET TRANSACTION</TT
>
for an individual transaction.
</P
><P
> 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.
</P
><P
> The isolation level of a transaction determines what data the
transaction can see when other transactions are running concurrently:
<P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>READ COMMITTED</TT
></DT
><DD
><P
> A statement can only see rows committed before it began. This
is the default.
</P
></DD
><DT
><TT
CLASS="LITERAL"
>REPEATABLE READ</TT
></DT
><DD
><P
> All statements of the current transaction can only see rows committed
before the first query or data-modification statement was executed in
this transaction.
</P
></DD
><DT
><TT
CLASS="LITERAL"
>SERIALIZABLE</TT
></DT
><DD
><P
> 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
<TT
CLASS="LITERAL"
>serialization_failure</TT
> error.
</P
></DD
></DL
></DIV
><P>
The SQL standard defines one additional level, <TT
CLASS="LITERAL"
>READ
UNCOMMITTED</TT
>.
In <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> <TT
CLASS="LITERAL"
>READ
UNCOMMITTED</TT
> is treated as <TT
CLASS="LITERAL"
>READ COMMITTED</TT
>.
</P
><P
> The transaction isolation level cannot be changed after the first query or
data-modification statement (<TT
CLASS="COMMAND"
>SELECT</TT
>,
<TT
CLASS="COMMAND"
>INSERT</TT
>, <TT
CLASS="COMMAND"
>DELETE</TT
>,
<TT
CLASS="COMMAND"
>UPDATE</TT
>, <TT
CLASS="COMMAND"
>FETCH</TT
>, or
<TT
CLASS="COMMAND"
>COPY</TT
>) of a transaction has been executed. See
<A
HREF="mvcc.html"
>Chapter 13</A
> for more information about transaction
isolation and concurrency control.
</P
><P
> 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: <TT
CLASS="LITERAL"
>INSERT</TT
>, <TT
CLASS="LITERAL"
>UPDATE</TT
>,
<TT
CLASS="LITERAL"
>DELETE</TT
>, and <TT
CLASS="LITERAL"
>COPY FROM</TT
> if the
table they would write to is not a temporary table; all
<TT
CLASS="LITERAL"
>CREATE</TT
>, <TT
CLASS="LITERAL"
>ALTER</TT
>, and
<TT
CLASS="LITERAL"
>DROP</TT
> commands; <TT
CLASS="LITERAL"
>COMMENT</TT
>,
<TT
CLASS="LITERAL"
>GRANT</TT
>, <TT
CLASS="LITERAL"
>REVOKE</TT
>,
<TT
CLASS="LITERAL"
>TRUNCATE</TT
>; and <TT
CLASS="LITERAL"
>EXPLAIN ANALYZE</TT
>
and <TT
CLASS="LITERAL"
>EXECUTE</TT
> 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.
</P
><P
> The <TT
CLASS="LITERAL"
>DEFERRABLE</TT
> transaction property has no effect
unless the transaction is also <TT
CLASS="LITERAL"
>SERIALIZABLE</TT
> and
<TT
CLASS="LITERAL"
>READ ONLY</TT
>. 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
<TT
CLASS="LITERAL"
>SERIALIZABLE</TT
> 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.
</P
><P
> The <TT
CLASS="LITERAL"
>SET TRANSACTION SNAPSHOT</TT
> command allows a new
transaction to run with the same <I
CLASS="FIRSTTERM"
>snapshot</I
> as an existing
transaction. The pre-existing transaction must have exported its snapshot
with the <TT
CLASS="LITERAL"
>pg_export_snapshot</TT
> function (see <A
HREF="functions-admin.html#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION"
>Section 9.26.5</A
>). That function returns a
snapshot identifier, which must be given to <TT
CLASS="LITERAL"
>SET TRANSACTION
SNAPSHOT</TT
> to specify which snapshot is to be imported. The
identifier must be written as a string literal in this command, for example
<TT
CLASS="LITERAL"
>'000003A1-1'</TT
>.
<TT
CLASS="LITERAL"
>SET TRANSACTION SNAPSHOT</TT
> can only be executed at the
start of a transaction, before the first query or
data-modification statement (<TT
CLASS="COMMAND"
>SELECT</TT
>,
<TT
CLASS="COMMAND"
>INSERT</TT
>, <TT
CLASS="COMMAND"
>DELETE</TT
>,
<TT
CLASS="COMMAND"
>UPDATE</TT
>, <TT
CLASS="COMMAND"
>FETCH</TT
>, or
<TT
CLASS="COMMAND"
>COPY</TT
>) of the transaction. Furthermore, the transaction
must already be set to <TT
CLASS="LITERAL"
>SERIALIZABLE</TT
> or
<TT
CLASS="LITERAL"
>REPEATABLE READ</TT
> isolation level (otherwise, the snapshot
would be discarded immediately, since <TT
CLASS="LITERAL"
>READ COMMITTED</TT
> mode takes
a new snapshot for each command). If the importing transaction uses
<TT
CLASS="LITERAL"
>SERIALIZABLE</TT
> 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.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN79146"
></A
><H2
>Notes</H2
><P
> If <TT
CLASS="COMMAND"
>SET TRANSACTION</TT
> is executed without a prior
<TT
CLASS="COMMAND"
>START TRANSACTION</TT
> or <TT
CLASS="COMMAND"
>BEGIN</TT
>,
it will appear to have no effect, since the transaction will immediately
end.
</P
><P
> It is possible to dispense with <TT
CLASS="COMMAND"
>SET TRANSACTION</TT
>
by instead specifying the desired <TT
CLASS="REPLACEABLE"
><I
>transaction_modes</I
></TT
> in
<TT
CLASS="COMMAND"
>BEGIN</TT
> or <TT
CLASS="COMMAND"
>START TRANSACTION</TT
>.
But that option is not available for <TT
CLASS="COMMAND"
>SET TRANSACTION
SNAPSHOT</TT
>.
</P
><P
> The session default transaction modes can also be set by setting the
configuration parameters <A
HREF="runtime-config-client.html#GUC-DEFAULT-TRANSACTION-ISOLATION"
>default_transaction_isolation</A
>,
<A
HREF="runtime-config-client.html#GUC-DEFAULT-TRANSACTION-READ-ONLY"
>default_transaction_read_only</A
>, and
<A
HREF="runtime-config-client.html#GUC-DEFAULT-TRANSACTION-DEFERRABLE"
>default_transaction_deferrable</A
>.
(In fact <TT
CLASS="COMMAND"
>SET SESSION CHARACTERISTICS</TT
> is just a
verbose equivalent for setting these variables with <TT
CLASS="COMMAND"
>SET</TT
>.)
This means the defaults can be set in the configuration file, via
<TT
CLASS="COMMAND"
>ALTER DATABASE</TT
>, etc. Consult <A
HREF="runtime-config.html"
>Chapter 18</A
>
for more information.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN79166"
></A
><H2
>Examples</H2
><P
> 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:
</P><PRE
CLASS="PROGRAMLISTING"
>BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ;
SELECT pg_export_snapshot();
pg_export_snapshot
--------------------
000003A1-1
(1 row)</PRE
><P>
Then give the snapshot identifier in a <TT
CLASS="COMMAND"
>SET TRANSACTION
SNAPSHOT</TT
> command at the beginning of the newly opened
transaction:
</P><PRE
CLASS="PROGRAMLISTING"
>BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ;
SET TRANSACTION SNAPSHOT '000003A1-1';</PRE
><P></P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="R1-SQL-SET-TRANSACTION-3"
></A
><H2
>Compatibility</H2
><P
> These commands are defined in the <ACRONYM
CLASS="ACRONYM"
>SQL</ACRONYM
> standard,
except for the <TT
CLASS="LITERAL"
>DEFERRABLE</TT
> transaction mode
and the <TT
CLASS="COMMAND"
>SET TRANSACTION SNAPSHOT</TT
> form, which are
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> extensions.
</P
><P
> <TT
CLASS="LITERAL"
>SERIALIZABLE</TT
> is the default transaction
isolation level in the standard. In
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> the default is ordinarily
<TT
CLASS="LITERAL"
>READ COMMITTED</TT
>, but you can change it as
mentioned above.
</P
><P
> 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 <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> server.
</P
><P
> The SQL standard requires commas between successive <TT
CLASS="REPLACEABLE"
><I
>transaction_modes</I
></TT
>, but for historical
reasons <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> allows the commas to be
omitted.
</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="sql-set-session-authorization.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="sql-show.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>SET SESSION AUTHORIZATION</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="sql-commands.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>SHOW</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>