begriffs open source - ai-pg/blob - full-docs/txt/sql-prepare-transaction.txt

   1
   2 PREPARE TRANSACTION
   3
   4    PREPARE TRANSACTION — prepare the current transaction for two-phase
   5    commit
   6
   7 Synopsis
   8
   9 PREPARE TRANSACTION transaction_id
  10
  11 Description
  12
  13    PREPARE TRANSACTION prepares the current transaction for two-phase
  14    commit. After this command, the transaction is no longer associated
  15    with the current session; instead, its state is fully stored on disk,
  16    and there is a very high probability that it can be committed
  17    successfully, even if a database crash occurs before the commit is
  18    requested.
  19
  20    Once prepared, a transaction can later be committed or rolled back with
  21    COMMIT PREPARED or ROLLBACK PREPARED, respectively. Those commands can
  22    be issued from any session, not only the one that executed the original
  23    transaction.
  24
  25    From the point of view of the issuing session, PREPARE TRANSACTION is
  26    not unlike a ROLLBACK command: after executing it, there is no active
  27    current transaction, and the effects of the prepared transaction are no
  28    longer visible. (The effects will become visible again if the
  29    transaction is committed.)
  30
  31    If the PREPARE TRANSACTION command fails for any reason, it becomes a
  32    ROLLBACK: the current transaction is canceled.
  33
  34 Parameters
  35
  36    transaction_id
  37           An arbitrary identifier that later identifies this transaction
  38           for COMMIT PREPARED or ROLLBACK PREPARED. The identifier must be
  39           written as a string literal, and must be less than 200 bytes
  40           long. It must not be the same as the identifier used for any
  41           currently prepared transaction.
  42
  43 Notes
  44
  45    PREPARE TRANSACTION is not intended for use in applications or
  46    interactive sessions. Its purpose is to allow an external transaction
  47    manager to perform atomic global transactions across multiple databases
  48    or other transactional resources. Unless you're writing a transaction
  49    manager, you probably shouldn't be using PREPARE TRANSACTION.
  50
  51    This command must be used inside a transaction block. Use BEGIN to
  52    start one.
  53
  54    It is not currently allowed to PREPARE a transaction that has executed
  55    any operations involving temporary tables or the session's temporary
  56    namespace, created any cursors WITH HOLD, or executed LISTEN, UNLISTEN,
  57    or NOTIFY. Those features are too tightly tied to the current session
  58    to be useful in a transaction to be prepared.
  59
  60    If the transaction modified any run-time parameters with SET (without
  61    the LOCAL option), those effects persist after PREPARE TRANSACTION, and
  62    will not be affected by any later COMMIT PREPARED or ROLLBACK PREPARED.
  63    Thus, in this one respect PREPARE TRANSACTION acts more like COMMIT
  64    than ROLLBACK.
  65
  66    All currently available prepared transactions are listed in the
  67    pg_prepared_xacts system view.
  68
  69 Caution
  70
  71    It is unwise to leave transactions in the prepared state for a long
  72    time. This will interfere with the ability of VACUUM to reclaim
  73    storage, and in extreme cases could cause the database to shut down to
  74    prevent transaction ID wraparound (see Section 24.1.5). Keep in mind
  75    also that the transaction continues to hold whatever locks it held. The
  76    intended usage of the feature is that a prepared transaction will
  77    normally be committed or rolled back as soon as an external transaction
  78    manager has verified that other databases are also prepared to commit.
  79
  80    If you have not set up an external transaction manager to track
  81    prepared transactions and ensure they get closed out promptly, it is
  82    best to keep the prepared-transaction feature disabled by setting
  83    max_prepared_transactions to zero. This will prevent accidental
  84    creation of prepared transactions that might then be forgotten and
  85    eventually cause problems.
  86
  87 Examples
  88
  89    Prepare the current transaction for two-phase commit, using foobar as
  90    the transaction identifier:
  91 PREPARE TRANSACTION 'foobar';
  92
  93 Compatibility
  94
  95    PREPARE TRANSACTION is a PostgreSQL extension. It is intended for use
  96    by external transaction management systems, some of which are covered
  97    by standards (such as X/Open XA), but the SQL side of those systems is
  98    not standardized.
  99
 100 See Also
 101
 102    COMMIT PREPARED, ROLLBACK PREPARED