Change the default value of max_prepared_transactions to zero, and add

tglsfdc · tglsfdc · commit 8d4f2ecd4131 · 2009-04-23T00:23:46.000Z
documentation warnings against setting it nonzero unless active use of
prepared transactions is intended and a suitable transaction manager has been
installed.  This should help to prevent the type of scenario we've seen
several times now where a prepared transaction is forgotten and eventually
causes severe maintenance problems (or even anti-wraparound shutdown).

The only real reason we had the default be nonzero in the first place was to
support regression testing of the feature.  To still be able to do that,
tweak pg_regress to force a nonzero value during "make check".  Since we
cannot force a nonzero value in "make installcheck", add a variant regression
test "expected" file that shows the results that will be obtained when
max_prepared_transactions is zero.

Also, extend the HINT messages for transaction wraparound warnings to mention
the possibility that old prepared transactions are causing the problem.

All per today's discussion.
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.214 2009/04/02 22:44:10 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.215 2009/04/23 00:23:45 tgl Exp $ -->
 
 <chapter Id="runtime-config">
   <title>Server Configuration</title>
@@ -785,18 +785,18 @@ SET ENABLE_SEQSCAN TO OFF;
         <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 five transactions.
+        Setting this parameter to zero (which is the default)
+        disables the prepared-transaction feature.
         This parameter can only be set at server start.
        </para>
 
        <para>
-        If you are not using prepared transactions, this parameter may as
-        well be set to zero.  If you are using them, you will probably
-        want <varname>max_prepared_transactions</varname> to be at least
-        as large as <xref linkend="guc-max-connections">, to avoid unwanted
-        failures at the prepare step.
+        If you are not planning to use prepared transactions, this parameter
+        should be set to zero to prevent accidental creation of prepared
+        transactions.  If you are using prepared transactions, you will
+        probably want <varname>max_prepared_transactions</varname> to be at
+        least as large as <xref linkend="guc-max-connections">, so that every
+        session can have a prepared transaction pending.
        </para>
 
        <para>
diff --git a/doc/src/sgml/ref/prepare_transaction.sgml b/doc/src/sgml/ref/prepare_transaction.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.8 2008/11/14 10:22:47 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.9 2009/04/23 00:23:45 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -30,7 +30,7 @@ PREPARE TRANSACTION <replaceable class="PARAMETER">transaction_id</replaceable>
 
   <para>
    <command>PREPARE TRANSACTION</command> prepares the current transaction
-   for two-phase commit. After this command, the transaction is no longer 
+   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
@@ -100,7 +100,7 @@ PREPARE TRANSACTION <replaceable class="PARAMETER">transaction_id</replaceable>
    If the transaction modified any run-time parameters with <command>SET</>
    (without the <literal>LOCAL</> option),
    those effects persist after <command>PREPARE TRANSACTION</>, and will not
-   be affected by any later <command>COMMIT PREPARED</command> or 
+   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</>.
@@ -112,34 +112,36 @@ PREPARE TRANSACTION <replaceable class="PARAMETER">transaction_id</replaceable>
    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>
-
-  <para>
-   If you make any serious use of prepared transactions, you will probably
-   want to increase the value of <xref
-   linkend="guc-max-prepared-transactions">, as the default setting is
-   quite small (to avoid wasting resources for those who don't use it).
-   It is recommendable to make it at least equal to
-   <xref linkend="guc-max-connections">, so that every session can have
-   a prepared transaction pending.
-  </para>
+  <caution>
+   <para>
+    It is unwise to leave transactions in the prepared state for a long time.
+    This will interfere with the ability of <command>VACUUM</> to reclaim
+    storage, and in extreme cases could cause the database to shut down
+    to prevent transaction ID wraparound (see <xref
+    linkend="vacuum-for-wraparound">).  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>
+
+   <para>
+    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
+    <xref linkend="guc-max-prepared-transactions"> to zero.  This will
+    prevent accidental creation of prepared transactions that might then
+    be forgotten and eventually cause problems.
+   </para>
+  </caution>
  </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>
diff --git a/src/backend/access/transam/twophase.c b/src/backend/access/transam/twophase.c
@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1994, Regents of the University of California
  *
  * IDENTIFICATION
- *		$PostgreSQL: pgsql/src/backend/access/transam/twophase.c,v 1.51 2009/01/01 17:23:36 momjian Exp $
+ *		$PostgreSQL: pgsql/src/backend/access/transam/twophase.c,v 1.52 2009/04/23 00:23:45 tgl Exp $
  *
  * NOTES
  *		Each global transaction is associated with a global transaction
@@ -68,7 +68,7 @@
 #define TWOPHASE_DIR "pg_twophase"
 
 /* GUC variable, can't be changed after startup */
-int			max_prepared_xacts = 5;
+int			max_prepared_xacts = 0;
 
 /*
  * This struct describes one global transaction that is in prepared state
@@ -228,6 +228,13 @@ MarkAsPreparing(TransactionId xid, const char *gid,
 				 errmsg("transaction identifier \"%s\" is too long",
 						gid)));
 
+	/* fail immediately if feature is disabled */
+	if (max_prepared_xacts == 0)
+		ereport(ERROR,
+				(errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
+				 errmsg("prepared transactions are disabled"),
+				 errhint("Set max_prepared_transactions to a nonzero value.")));
+
 	LWLockAcquire(TwoPhaseStateLock, LW_EXCLUSIVE);
 
 	/*
diff --git a/src/backend/access/transam/varsup.c b/src/backend/access/transam/varsup.c
@@ -6,7 +6,7 @@
  * Copyright (c) 2000-2009, PostgreSQL Global Development Group
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/access/transam/varsup.c,v 1.83 2009/01/01 17:23:36 momjian Exp $
+ *	  $PostgreSQL: pgsql/src/backend/access/transam/varsup.c,v 1.84 2009/04/23 00:23:45 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -86,14 +86,16 @@ GetNewTransactionId(bool isSubXact)
 					(errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
 					 errmsg("database is not accepting commands to avoid wraparound data loss in database \"%s\"",
 							NameStr(ShmemVariableCache->limit_datname)),
-					 errhint("Stop the postmaster and use a standalone backend to vacuum database \"%s\".",
+					 errhint("Stop the postmaster and use a standalone backend to vacuum database \"%s\".\n"
+							 "You might also need to commit or roll back old prepared transactions.",
 							 NameStr(ShmemVariableCache->limit_datname))));
 		else if (TransactionIdFollowsOrEquals(xid, ShmemVariableCache->xidWarnLimit))
 			ereport(WARNING,
 			(errmsg("database \"%s\" must be vacuumed within %u transactions",
 					NameStr(ShmemVariableCache->limit_datname),
 					ShmemVariableCache->xidWrapLimit - xid),
-			 errhint("To avoid a database shutdown, execute a database-wide VACUUM in \"%s\".",
+			 errhint("To avoid a database shutdown, execute a database-wide VACUUM in \"%s\".\n"
+					 "You might also need to commit or roll back old prepared transactions.",
 					 NameStr(ShmemVariableCache->limit_datname))));
 	}
 
@@ -299,7 +301,8 @@ SetTransactionIdLimit(TransactionId oldest_datfrozenxid,
 		   (errmsg("database \"%s\" must be vacuumed within %u transactions",
 				   NameStr(*oldest_datname),
 				   xidWrapLimit - curXid),
-			errhint("To avoid a database shutdown, execute a database-wide VACUUM in \"%s\".",
+			errhint("To avoid a database shutdown, execute a database-wide VACUUM in \"%s\".\n"
+					"You might also need to commit or roll back old prepared transactions.",
 					NameStr(*oldest_datname))));
 }
 
diff --git a/src/backend/utils/misc/guc.c b/src/backend/utils/misc/guc.c
@@ -10,7 +10,7 @@
  * Written by Peter Eisentraut <peter_e@gmx.net>.
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/utils/misc/guc.c,v 1.502 2009/04/07 23:27:34 momjian Exp $
+ *	  $PostgreSQL: pgsql/src/backend/utils/misc/guc.c,v 1.503 2009/04/23 00:23:45 tgl Exp $
  *
  *--------------------------------------------------------------------
  */
@@ -1504,7 +1504,7 @@ static struct config_int ConfigureNamesInt[] =
 			NULL
 		},
 		&max_prepared_xacts,
-		5, 0, INT_MAX, NULL, NULL
+		0, 0, INT_MAX / 4, NULL, NULL
 	},
 
 #ifdef LOCK_DEBUG
diff --git a/src/backend/utils/misc/postgresql.conf.sample b/src/backend/utils/misc/postgresql.conf.sample
@@ -106,10 +106,12 @@
 #shared_buffers = 32MB			# min 128kB
 					# (change requires restart)
 #temp_buffers = 8MB			# min 800kB
-#max_prepared_transactions = 5		# can be 0 or more
+#max_prepared_transactions = 0		# zero disables the feature
 					# (change requires restart)
 # Note:  Increasing max_prepared_transactions costs ~600 bytes of shared memory
 # per transaction slot, plus lock space (see max_locks_per_transaction).
+# It is not advisable to set max_prepared_transactions nonzero unless you
+# actively intend to use prepared transactions.
 #work_mem = 1MB				# min 64kB
 #maintenance_work_mem = 16MB		# min 1MB
 #max_stack_depth = 2MB			# min 100kB
diff --git a/src/test/regress/expected/prepared_xacts.out b/src/test/regress/expected/prepared_xacts.out
@@ -214,4 +214,6 @@ SELECT gid FROM pg_prepared_xacts;
 
 -- Clean up
 DROP TABLE pxtest2;
+DROP TABLE pxtest3;  -- will still be there if prepared xacts are disabled
+ERROR:  table "pxtest3" does not exist
 DROP TABLE pxtest4;
diff --git a/src/test/regress/expected/prepared_xacts_1.out b/src/test/regress/expected/prepared_xacts_1.out
diff --git a/src/test/regress/pg_regress.c b/src/test/regress/pg_regress.c
diff --git a/src/test/regress/sql/prepared_xacts.sql b/src/test/regress/sql/prepared_xacts.sql
