From d0a89683a3a4dd8e76ef0a99101355999e519df5 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Fri, 17 Jun 2005 22:32:51 +0000 Subject: Two-phase commit. Original patch by Heikki Linnakangas, with additional hacking by Alvaro Herrera and Tom Lane. --- doc/src/sgml/catalogs.sgml | 94 +++++++++++++++++- doc/src/sgml/ref/allfiles.sgml | 5 +- doc/src/sgml/ref/commit_prepared.sgml | 111 +++++++++++++++++++++ doc/src/sgml/ref/prepare_transaction.sgml | 160 ++++++++++++++++++++++++++++++ doc/src/sgml/ref/rollback_prepared.sgml | 111 +++++++++++++++++++++ doc/src/sgml/reference.sgml | 5 +- doc/src/sgml/runtime.sgml | 31 +++++- 7 files changed, 510 insertions(+), 7 deletions(-) create mode 100644 doc/src/sgml/ref/commit_prepared.sgml create mode 100644 doc/src/sgml/ref/prepare_transaction.sgml create mode 100644 doc/src/sgml/ref/rollback_prepared.sgml (limited to 'doc/src') diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 41d7a4e34d5..c5473b9501b 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -1,6 +1,6 @@ @@ -3932,6 +3932,11 @@ currently held locks + + pg_prepared_xacts + currently prepared transactions + + pg_rules rules @@ -4167,8 +4172,10 @@ pid integer - process ID of the server process holding or awaiting this - lock + + Process ID of the server process holding or awaiting this + lock. Zero if the lock is held by a prepared transaction. + mode @@ -4250,6 +4257,87 @@ + + <structname>pg_prepared_xacts</structname> + + + pg_prepared_xacts + + + + The view pg_prepared_xacts displays + information about transactions that are currently prepared for two-phase + commit (see for details). + + + + pg_prepared_xacts contains one row per prepared + transaction. An entry is removed when the transaction is committed or + rolled back. + + + + <structname>pg_prepared_xacts</> Columns + + + + + Name + Type + References + Description + + + + + transaction + xid + + + Numeric transaction identifier of the prepared transaction + + + + gid + text + + + Global transaction identifier that was assigned to the transaction + + + + owner + name + pg_shadow.usename + + Name of the user that executed the transaction + + + + database + name + pg_database.datname + + Name of the database in which the transaction was executed + + + + +
+ + + When the pg_prepared_xacts view is accessed, the + internal transaction manager data structures are momentarily locked, and + a copy is made for the view to display. This ensures that the + view produces a consistent set of results, while not blocking + normal operations longer than necessary. Nonetheless + there could be some impact on database performance if this view is + read often. + + + + <structname>pg_rules</structname> diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index 6326f96f72f..33e9e68b9d5 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -1,5 +1,5 @@ @@ -30,6 +30,7 @@ Complete list of usable sgml source files in this directory. + @@ -88,11 +89,13 @@ Complete list of usable sgml source files in this directory. + + diff --git a/doc/src/sgml/ref/commit_prepared.sgml b/doc/src/sgml/ref/commit_prepared.sgml new file mode 100644 index 00000000000..b18175815b2 --- /dev/null +++ b/doc/src/sgml/ref/commit_prepared.sgml @@ -0,0 +1,111 @@ + + + + + COMMIT PREPARED + SQL - Language Statements + + + + COMMIT PREPARED + commit a transaction that was earlier prepared for two-phase commit + + + + COMMIT PREPARED + + + + +COMMIT PREPARED transaction_id + + + + + Description + + + COMMIT PREPARED commits a transaction that is in + prepared state. + + + + + Parameters + + + + transaction_id + + + The transaction identifier of the transaction that is to be + committed. + + + + + + + + Notes + + + To commit a prepared transaction, you must be either the same user that + executed the transaction originally, or a superuser. But you do not + have to be in the same session that executed the transaction. + + + + This command cannot be executed inside a transaction block. The prepared + transaction is committed immediately. + + + + All currently available prepared transactions are listed in the + pg_prepared_xacts system view. + + + + + Examples + + Commit the transaction identified by the transaction + identifier foobar: + + +COMMIT PREPARED 'foobar'; + + + + + + + See Also + + + + + + + + + + diff --git a/doc/src/sgml/ref/prepare_transaction.sgml b/doc/src/sgml/ref/prepare_transaction.sgml new file mode 100644 index 00000000000..773689ae06d --- /dev/null +++ b/doc/src/sgml/ref/prepare_transaction.sgml @@ -0,0 +1,160 @@ + + + + + PREPARE TRANSACTION + SQL - Language Statements + + + + PREPARE TRANSACTION + prepare the current transaction for two-phase commit + + + + PREPARE TRANSACTION + + + + +PREPARE TRANSACTION transaction_id + + + + + Description + + + PREPARE TRANSACTION 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. + + + + Once prepared, a transaction can later be committed or rolled + back with COMMIT PREPARED or + ROLLBACK PREPARED, respectively. Those commands + can be issued from any session, not only the one that executed the + original transaction. + + + + From the point of view of the issuing session, PREPARE + TRANSACTION is not unlike a ROLLBACK 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.) + + + + If the PREPARE TRANSACTION command fails for any + reason, it becomes a ROLLBACK: the current transaction + is canceled. + + + + + Parameters + + + + transaction_id + + + An arbitrary identifier that later identifies this transaction for + COMMIT PREPARED or ROLLBACK PREPARED. + 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. + + + + + + + + Notes + + + This command must be used inside a transaction block. Use + BEGIN to start one. + + + + It is not currently allowed to PREPARE a transaction that + has executed any operations involving temporary tables nor + created any cursors WITH HOLD. Those features are too tightly + tied to the current session to be useful in a transaction to be prepared. + + + + If the transaction modified any run-time parameters with SET, + those effects persist after PREPARE TRANSACTION, and will not + be affected by any later COMMIT PREPARED or + ROLLBACK PREPARED. Thus, in this one respect + PREPARE TRANSACTION acts more like COMMIT than + ROLLBACK. + + + + All currently available prepared transactions are listed in the + pg_prepared_xacts system view. + + + + From a performance standpoint, it is unwise to leave transactions in + the prepared state for a long time: this will for instance interfere with + the ability of VACUUM to reclaim storage. 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. + + + + + Examples + + Prepare the current transaction for two-phase commit, using + foobar as the transaction identifier: + + +PREPARE TRANSACTION 'foobar'; + + + + + + See Also + + + + + + + + + + diff --git a/doc/src/sgml/ref/rollback_prepared.sgml b/doc/src/sgml/ref/rollback_prepared.sgml new file mode 100644 index 00000000000..51df9226321 --- /dev/null +++ b/doc/src/sgml/ref/rollback_prepared.sgml @@ -0,0 +1,111 @@ + + + + + ROLLBACK PREPARED + SQL - Language Statements + + + + ROLLBACK PREPARED + cancel a transaction that was earlier prepared for two-phase commit + + + + ROLLBACK PREPARED + + + + +ROLLBACK PREPARED transaction_id + + + + + Description + + + ROLLBACK PREPARED rolls back a transaction that is in + prepared state. + + + + + Parameters + + + + transaction_id + + + The transaction identifier of the transaction that is to be + rolled back. + + + + + + + + Notes + + + To roll back a prepared transaction, you must be either the same user that + executed the transaction originally, or a superuser. But you do not + have to be in the same session that executed the transaction. + + + + This command cannot be executed inside a transaction block. The prepared + transaction is rolled back immediately. + + + + All currently available prepared transactions are listed in the + pg_prepared_xacts system view. + + + + + Examples + + Roll back the transaction identified by the transaction + identifier foobar: + + +ROLLBACK PREPARED 'foobar'; + + + + + + + See Also + + + + + + + + + + diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index 01dc578b9d3..4edec85c122 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -1,5 +1,5 @@ @@ -62,6 +62,7 @@ PostgreSQL Reference Manual &cluster; &commentOn; &commit; + &commitPrepared; ©Table; &createAggregate; &createCast; @@ -120,11 +121,13 @@ PostgreSQL Reference Manual &move; ¬ify; &prepare; + &prepareTransaction; &reindex; &releaseSavepoint; &reset; &revoke; &rollback; + &rollbackPrepared; &rollbackTo; &savepoint; &select; diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml index dfb86511c3e..1a2a9935cc3 100644 --- a/doc/src/sgml/runtime.sgml +++ b/doc/src/sgml/runtime.sgml @@ -1,5 +1,5 @@ @@ -956,7 +956,7 @@ SET ENABLE_SEQSCAN TO OFF; Sets the location of the Kerberos server key file. See for details. This parameter - can only be set at server start. + can only be set at server start. @@ -1113,6 +1113,33 @@ SET ENABLE_SEQSCAN TO OFF; + + max_prepared_transactions (integer) + + max_prepared_transactions configuration parameter + + + + Sets the maximum number of transactions that can be in the + prepared state simultaneously (see ). + Setting this parameter to zero disables the prepared-transaction + feature. + The default is 50. + This option can only be set at server start. + + + + Increasing this parameter may cause PostgreSQL + to request more System V shared + memory than your operating system's default configuration + allows. See for information on how to + adjust those parameters, if necessary. + + + + work_mem (integer) -- cgit v1.2.3