diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/catalogs.sgml | 94 | ||||
| -rw-r--r-- | doc/src/sgml/ref/allfiles.sgml | 5 | ||||
| -rw-r--r-- | doc/src/sgml/ref/commit_prepared.sgml | 111 | ||||
| -rw-r--r-- | doc/src/sgml/ref/prepare_transaction.sgml | 160 | ||||
| -rw-r--r-- | doc/src/sgml/ref/rollback_prepared.sgml | 111 | ||||
| -rw-r--r-- | doc/src/sgml/reference.sgml | 5 | ||||
| -rw-r--r-- | doc/src/sgml/runtime.sgml | 31 |
7 files changed, 510 insertions, 7 deletions
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 @@ <!-- Documentation of the system catalogs, directed toward PostgreSQL developers - $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.103 2005/06/13 23:14:47 tgl Exp $ + $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.104 2005/06/17 22:32:41 tgl Exp $ --> <chapter id="catalogs"> @@ -3933,6 +3933,11 @@ </row> <row> + <entry><link linkend="view-pg-prepared-xacts"><structname>pg_prepared_xacts</structname></link></entry> + <entry>currently prepared transactions</entry> + </row> + + <row> <entry><link linkend="view-pg-rules"><structname>pg_rules</structname></link></entry> <entry>rules</entry> </row> @@ -4167,8 +4172,10 @@ <entry><structfield>pid</structfield></entry> <entry><type>integer</type></entry> <entry></entry> - <entry>process ID of the server process holding or awaiting this - lock</entry> + <entry> + Process ID of the server process holding or awaiting this + lock. Zero if the lock is held by a prepared transaction. + </entry> </row> <row> <entry><structfield>mode</structfield></entry> @@ -4250,6 +4257,87 @@ </sect1> + <sect1 id="view-pg-prepared-xacts"> + <title><structname>pg_prepared_xacts</structname></title> + + <indexterm zone="view-pg-prepared-xacts"> + <primary>pg_prepared_xacts</primary> + </indexterm> + + <para> + The view <structname>pg_prepared_xacts</structname> displays + information about transactions that are currently prepared for two-phase + commit (see <xref linkend="sql-prepare-transaction" + endterm="sql-prepare-transaction-title"> for details). + </para> + + <para> + <structname>pg_prepared_xacts</structname> contains one row per prepared + transaction. An entry is removed when the transaction is committed or + rolled back. + </para> + + <table> + <title><structname>pg_prepared_xacts</> Columns</title> + + <tgroup cols=4> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>References</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><structfield>transaction</structfield></entry> + <entry><type>xid</type></entry> + <entry></entry> + <entry> + Numeric transaction identifier of the prepared transaction + </entry> + </row> + <row> + <entry><structfield>gid</structfield></entry> + <entry><type>text</type></entry> + <entry></entry> + <entry> + Global transaction identifier that was assigned to the transaction + </entry> + </row> + <row> + <entry><structfield>owner</structfield></entry> + <entry><type>name</type></entry> + <entry><literal><link linkend="catalog-pg-shadow"><structname>pg_shadow</structname></link>.usename</literal></entry> + <entry> + Name of the user that executed the transaction + </entry> + </row> + <row> + <entry><structfield>database</structfield></entry> + <entry><type>name</type></entry> + <entry><literal><link linkend="catalog-pg-database"><structname>pg_database</structname></link>.datname</literal></entry> + <entry> + Name of the database in which the transaction was executed + </entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + When the <structname>pg_prepared_xacts</structname> 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. + </para> + + </sect1> + <sect1 id="view-pg-rules"> <title><structname>pg_rules</structname></title> 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 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.62 2004/08/21 16:16:04 tgl Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.63 2005/06/17 22:32:42 tgl Exp $ PostgreSQL documentation Complete list of usable sgml source files in this directory. --> @@ -30,6 +30,7 @@ Complete list of usable sgml source files in this directory. <!entity cluster system "cluster.sgml"> <!entity commentOn system "comment.sgml"> <!entity commit system "commit.sgml"> +<!entity commitPrepared system "commit_prepared.sgml"> <!entity copyTable system "copy.sgml"> <!entity createAggregate system "create_aggregate.sgml"> <!entity createCast system "create_cast.sgml"> @@ -88,11 +89,13 @@ Complete list of usable sgml source files in this directory. <!entity move system "move.sgml"> <!entity notify system "notify.sgml"> <!entity prepare system "prepare.sgml"> +<!entity prepareTransaction system "prepare_transaction.sgml"> <!entity reindex system "reindex.sgml"> <!entity releaseSavepoint system "release_savepoint.sgml"> <!entity reset system "reset.sgml"> <!entity revoke system "revoke.sgml"> <!entity rollback system "rollback.sgml"> +<!entity rollbackPrepared system "rollback_prepared.sgml"> <!entity rollbackTo system "rollback_to.sgml"> <!entity savepoint system "savepoint.sgml"> <!entity select system "select.sgml"> 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 @@ +<!-- +$PostgreSQL: pgsql/doc/src/sgml/ref/commit_prepared.sgml,v 1.1 2005/06/17 22:32:42 tgl Exp $ +PostgreSQL documentation +--> + +<refentry id="SQL-COMMIT-PREPARED"> + <refmeta> + <refentrytitle id="sql-commit-prepared-title">COMMIT PREPARED</refentrytitle> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>COMMIT PREPARED</refname> + <refpurpose>commit a transaction that was earlier prepared for two-phase commit</refpurpose> + </refnamediv> + + <indexterm zone="sql-commit-prepared"> + <primary>COMMIT PREPARED</primary> + </indexterm> + + <refsynopsisdiv> +<synopsis> +COMMIT PREPARED <replaceable class="PARAMETER">transaction_id</replaceable> +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>COMMIT PREPARED</command> commits a transaction that is in + prepared state. + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="PARAMETER">transaction_id</replaceable></term> + <listitem> + <para> + The transaction identifier of the transaction that is to be + committed. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + 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. + </para> + + <para> + This command cannot be executed inside a transaction block. The prepared + transaction is committed immediately. + </para> + + <para> + All currently available prepared transactions are listed in the + <structname>pg_prepared_xacts</> system view. + </para> + </refsect1> + + <refsect1 id="sql-commit-prepared-examples"> + <title id="sql-commit-prepared-examples-title">Examples</title> + <para> + Commit the transaction identified by the transaction + identifier <literal>foobar</>: + +<programlisting> +COMMIT PREPARED 'foobar'; +</programlisting> + </para> + + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-prepare-transaction" endterm="sql-prepare-transaction-title"></member> + <member><xref linkend="sql-rollback-prepared" endterm="sql-rollback-prepared-title"></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../reference.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:"/usr/lib/sgml/catalog" +sgml-local-ecat-files:nil +End: +--> 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 @@ +<!-- +$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.1 2005/06/17 22:32:42 tgl Exp $ +PostgreSQL documentation +--> + +<refentry id="SQL-PREPARE-TRANSACTION"> + <refmeta> + <refentrytitle id="sql-prepare-transaction-title">PREPARE TRANSACTION</refentrytitle> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>PREPARE TRANSACTION</refname> + <refpurpose>prepare the current transaction for two-phase commit</refpurpose> + </refnamediv> + + <indexterm zone="sql-prepare-transaction"> + <primary>PREPARE TRANSACTION</primary> + </indexterm> + + <refsynopsisdiv> +<synopsis> +PREPARE TRANSACTION <replaceable class="PARAMETER">transaction_id</replaceable> +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>PREPARE TRANSACTION</command> 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. + </para> + + <para> + Once prepared, a transaction can later be committed or rolled + back with <command>COMMIT PREPARED</command> or + <command>ROLLBACK PREPARED</command>, respectively. Those commands + can be issued from any session, not only the one that executed the + original transaction. + </para> + + <para> + From the point of view of the issuing session, <command>PREPARE + TRANSACTION</command> is not unlike a <command>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.) + </para> + + <para> + If the <command>PREPARE TRANSACTION</command> command fails for any + reason, it becomes a <command>ROLLBACK</>: the current transaction + is canceled. + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="PARAMETER">transaction_id</replaceable></term> + <listitem> + <para> + An arbitrary identifier that later identifies this transaction for + <command>COMMIT PREPARED</> or <command>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. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + This command must be used inside a transaction block. Use + <command>BEGIN</command> to start one. + </para> + + <para> + It is not currently allowed to <command>PREPARE</> a transaction that + has executed any operations involving temporary tables nor + created any cursors <literal>WITH HOLD</>. Those features are too tightly + tied to the current session to be useful in a transaction to be prepared. + </para> + + <para> + If the transaction modified any run-time parameters with <command>SET</>, + those effects persist after <command>PREPARE TRANSACTION</>, and will not + be affected by any later <command>COMMIT PREPARED</command> or + <command>ROLLBACK PREPARED</command>. Thus, in this one respect + <command>PREPARE TRANSACTION</> acts more like <command>COMMIT</> than + <command>ROLLBACK</>. + </para> + + <para> + All currently available prepared transactions are listed in the + <structname>pg_prepared_xacts</> system view. + </para> + + <para> + 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 <command>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. + </para> + </refsect1> + + <refsect1 id="sql-prepare-transaction-examples"> + <title id="sql-prepare-transaction-examples-title">Examples</title> + <para> + Prepare the current transaction for two-phase commit, using + <literal>foobar</> as the transaction identifier: + +<programlisting> +PREPARE TRANSACTION 'foobar'; +</programlisting> + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-commit-prepared" endterm="sql-commit-prepared-title"></member> + <member><xref linkend="sql-rollback-prepared" endterm="sql-rollback-prepared-title"></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../reference.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:"/usr/lib/sgml/catalog" +sgml-local-ecat-files:nil +End: +--> 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 @@ +<!-- +$PostgreSQL: pgsql/doc/src/sgml/ref/rollback_prepared.sgml,v 1.1 2005/06/17 22:32:42 tgl Exp $ +PostgreSQL documentation +--> + +<refentry id="SQL-ROLLBACK-PREPARED"> + <refmeta> + <refentrytitle id="sql-rollback-prepared-title">ROLLBACK PREPARED</refentrytitle> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>ROLLBACK PREPARED</refname> + <refpurpose>cancel a transaction that was earlier prepared for two-phase commit</refpurpose> + </refnamediv> + + <indexterm zone="sql-rollback-prepared"> + <primary>ROLLBACK PREPARED</primary> + </indexterm> + + <refsynopsisdiv> +<synopsis> +ROLLBACK PREPARED <replaceable class="PARAMETER">transaction_id</replaceable> +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>ROLLBACK PREPARED</command> rolls back a transaction that is in + prepared state. + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="PARAMETER">transaction_id</replaceable></term> + <listitem> + <para> + The transaction identifier of the transaction that is to be + rolled back. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + 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. + </para> + + <para> + This command cannot be executed inside a transaction block. The prepared + transaction is rolled back immediately. + </para> + + <para> + All currently available prepared transactions are listed in the + <structname>pg_prepared_xacts</> system view. + </para> + </refsect1> + + <refsect1 id="sql-rollback-prepared-examples"> + <title id="sql-rollback-prepared-examples-title">Examples</title> + <para> + Roll back the transaction identified by the transaction + identifier <literal>foobar</>: + +<programlisting> +ROLLBACK PREPARED 'foobar'; +</programlisting> + </para> + + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-prepare-transaction" endterm="sql-prepare-transaction-title"></member> + <member><xref linkend="sql-commit-prepared" endterm="sql-commit-prepared-title"></member> + </simplelist> + </refsect1> + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../reference.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:"/usr/lib/sgml/catalog" +sgml-local-ecat-files:nil +End: +--> 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 @@ <!-- reference.sgml -$PostgreSQL: pgsql/doc/src/sgml/reference.sgml,v 1.52 2004/08/21 16:16:03 tgl Exp $ +$PostgreSQL: pgsql/doc/src/sgml/reference.sgml,v 1.53 2005/06/17 22:32:42 tgl Exp $ PostgreSQL Reference Manual --> @@ -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 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.328 2005/06/17 13:12:01 momjian Exp $ +$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.329 2005/06/17 22:32:42 tgl Exp $ --> <chapter Id="runtime"> @@ -956,7 +956,7 @@ SET ENABLE_SEQSCAN TO OFF; <para> Sets the location of the Kerberos server key file. See <xref linkend="kerberos-auth"> for details. This parameter - can only be set at server start. + can only be set at server start. </para> </listitem> </varlistentry> @@ -1113,6 +1113,33 @@ SET ENABLE_SEQSCAN TO OFF; </listitem> </varlistentry> + <varlistentry id="guc-max-prepared-transactions" xreflabel="max_prepared_transactions"> + <term><varname>max_prepared_transactions</varname> (<type>integer</type>)</term> + <indexterm> + <primary><varname>max_prepared_transactions</> configuration parameter</primary> + </indexterm> + <listitem> + <para> + Sets the maximum number of transactions that can be in the + <quote>prepared</> state simultaneously (see <xref + linkend="sql-prepare-transaction" + endterm="sql-prepare-transaction-title">). + Setting this parameter to zero disables the prepared-transaction + feature. + The default is 50. + This option can only be set at server start. + </para> + + <para> + Increasing this parameter may cause <productname>PostgreSQL</> + to request more <systemitem class="osname">System V</> shared + memory than your operating system's default configuration + allows. See <xref linkend="sysvipc"> for information on how to + adjust those parameters, if necessary. + </para> + </listitem> + </varlistentry> + <varlistentry id="guc-work-mem" xreflabel="work_mem"> <term><varname>work_mem</varname> (<type>integer</type>)</term> <indexterm> |