'\" t
.\"     Title: PREPARE TRANSACTION
.\"    Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2023
.\"    Manual: PostgreSQL 11.22 Documentation
.\"    Source: PostgreSQL 11.22
.\"  Language: English
.\"
.TH "PREPARE TRANSACTION" "7" "2023" "PostgreSQL 11.22" "PostgreSQL 11.22 Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
PREPARE_TRANSACTION \- prepare the current transaction for two\-phase commit
.SH "SYNOPSIS"
.sp
.nf
PREPARE TRANSACTION \fItransaction_id\fR
.fi
.SH "DESCRIPTION"
.PP
\fBPREPARE TRANSACTION\fR
prepares the current transaction for two\-phase commit\&. After this command, the transaction is no longer associated with the current session; instead, its state is fully stored on disk, and there is a very high probability that it can be committed successfully, even if a database crash occurs before the commit is requested\&.
.PP
Once prepared, a transaction can later be committed or rolled back with
COMMIT PREPARED (\fBCOMMIT_PREPARED\fR(7))
or
ROLLBACK PREPARED (\fBROLLBACK_PREPARED\fR(7)), respectively\&. Those commands can be issued from any session, not only the one that executed the original transaction\&.
.PP
From the point of view of the issuing session,
\fBPREPARE TRANSACTION\fR
is not unlike a
\fBROLLBACK\fR
command: after executing it, there is no active current transaction, and the effects of the prepared transaction are no longer visible\&. (The effects will become visible again if the transaction is committed\&.)
.PP
If the
\fBPREPARE TRANSACTION\fR
command fails for any reason, it becomes a
\fBROLLBACK\fR: the current transaction is canceled\&.
.SH "PARAMETERS"
.PP
\fItransaction_id\fR
.RS 4
An arbitrary identifier that later identifies this transaction for
\fBCOMMIT PREPARED\fR
or
\fBROLLBACK PREPARED\fR\&. The identifier must be written as a string literal, and must be less than 200 bytes long\&. It must not be the same as the identifier used for any currently prepared transaction\&.
.RE
.SH "NOTES"
.PP
\fBPREPARE TRANSACTION\fR
is not intended for use in applications or interactive sessions\&. Its purpose is to allow an external transaction manager to perform atomic global transactions across multiple databases or other transactional resources\&. Unless you\*(Aqre writing a transaction manager, you probably shouldn\*(Aqt be using
\fBPREPARE TRANSACTION\fR\&.
.PP
This command must be used inside a transaction block\&. Use
\fBBEGIN\fR(7)
to start one\&.
.PP
It is not currently allowed to
\fBPREPARE\fR
a transaction that has executed any operations involving temporary tables or the session\*(Aqs temporary namespace, created any cursors
WITH HOLD, or executed
\fBLISTEN\fR,
\fBUNLISTEN\fR, or
\fBNOTIFY\fR\&. Those features are too tightly tied to the current session to be useful in a transaction to be prepared\&.
.PP
If the transaction modified any run\-time parameters with
\fBSET\fR
(without the
LOCAL
option), those effects persist after
\fBPREPARE TRANSACTION\fR, and will not be affected by any later
\fBCOMMIT PREPARED\fR
or
\fBROLLBACK PREPARED\fR\&. Thus, in this one respect
\fBPREPARE TRANSACTION\fR
acts more like
\fBCOMMIT\fR
than
\fBROLLBACK\fR\&.
.PP
All currently available prepared transactions are listed in the
pg_prepared_xacts
system view\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBCaution\fR
.ps -1
.br
.PP
It is unwise to leave transactions in the prepared state for a long time\&. This will interfere with the ability of
\fBVACUUM\fR
to reclaim storage, and in extreme cases could cause the database to shut down to prevent transaction ID wraparound (see
Section\ \&24.1.5)\&. Keep in mind also that the transaction continues to hold whatever locks it held\&. The intended usage of the feature is that a prepared transaction will normally be committed or rolled back as soon as an external transaction manager has verified that other databases are also prepared to commit\&.
.PP
If you have not set up an external transaction manager to track prepared transactions and ensure they get closed out promptly, it is best to keep the prepared\-transaction feature disabled by setting
max_prepared_transactions
to zero\&. This will prevent accidental creation of prepared transactions that might then be forgotten and eventually cause problems\&.
.sp .5v
.RE
.SH "EXAMPLES"
.PP
Prepare the current transaction for two\-phase commit, using
foobar
as the transaction identifier:
.sp
.if n \{\
.RS 4
.\}
.nf
PREPARE TRANSACTION \*(Aqfoobar\*(Aq;
.fi
.if n \{\
.RE
.\}
.SH "COMPATIBILITY"
.PP
\fBPREPARE TRANSACTION\fR
is a
PostgreSQL
extension\&. It is intended for use by external transaction management systems, some of which are covered by standards (such as X/Open XA), but the SQL side of those systems is not standardized\&.
.SH "SEE ALSO"
COMMIT PREPARED (\fBCOMMIT_PREPARED\fR(7)), ROLLBACK PREPARED (\fBROLLBACK_PREPARED\fR(7))