To reduce confusion over whether VACUUM FULL is needed for anti-wraparound

tglsfdc · tglsfdc · commit 17dc17366093 · 2008-12-11T18:16:18.000Z
vacuuming (it's not), say "database-wide VACUUM" instead of "full-database
VACUUM" in the relevant hint messages.  Also, document the permissions needed
to do this.  Per today's discussion.
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.87 2008/12/08 20:30:58 mha Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.88 2008/12/11 18:16:18 tgl Exp $ -->
 
 <chapter id="maintenance">
  <title>Routine Database Maintenance Tasks</title>
@@ -472,9 +472,13 @@ SELECT datname, age(datfrozenxid) FROM pg_database;
 
 <programlisting>
 WARNING:  database "mydb" must be vacuumed within 177009986 transactions
-HINT:  To avoid a database shutdown, execute a full-database VACUUM in "mydb".
+HINT:  To avoid a database shutdown, execute a database-wide VACUUM in "mydb".
 </programlisting>
 
+    (A manual <command>VACUUM</> should fix the problem, as suggested by the
+    hint; but note that the <command>VACUUM</> must be performed by a
+    superuser, else it will fail to process system catalogs and thus not
+    be able to advance the database's <structfield>datfrozenxid</>.)
     If these warnings are
     ignored, the system will shut down and refuse to execute any new
     transactions once there are fewer than 1 million transactions left
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.53 2008/11/14 10:22:47 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.54 2008/12/11 18:16:18 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -40,8 +40,8 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">
 
   <para>
    With no parameter, <command>VACUUM</command> processes every table in the
-   current database.  With a parameter, <command>VACUUM</command> processes
-   only that table.
+   current database that the current user has permission to vacuum.
+   With a parameter, <command>VACUUM</command> processes only that table.
   </para>
 
   <para>
@@ -146,6 +146,16 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">
  <refsect1>
   <title>Notes</title>
 
+   <para>
+    To vacuum a table, one must ordinarily be the table's owner or a
+    superuser.  However, database owners are allowed to
+    vacuum all tables in their databases, except shared catalogs.
+    (The restriction for shared catalogs means that a true database-wide
+    <command>VACUUM</> can only be performed by a superuser.)
+    <command>VACUUM</> will skip over any tables that the calling user
+    does not have permission to vacuum.
+   </para>
+
    <para>
     <command>VACUUM</> cannot be executed inside a transaction block.
    </para>
diff --git a/src/backend/access/transam/varsup.c b/src/backend/access/transam/varsup.c
@@ -6,7 +6,7 @@
  * Copyright (c) 2000-2008, PostgreSQL Global Development Group
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/access/transam/varsup.c,v 1.81 2008/01/01 19:45:48 momjian Exp $
+ *	  $PostgreSQL: pgsql/src/backend/access/transam/varsup.c,v 1.82 2008/12/11 18:16:18 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -93,7 +93,7 @@ GetNewTransactionId(bool isSubXact)
 			(errmsg("database \"%s\" must be vacuumed within %u transactions",
 					NameStr(ShmemVariableCache->limit_datname),
 					ShmemVariableCache->xidWrapLimit - xid),
-			 errhint("To avoid a database shutdown, execute a full-database VACUUM in \"%s\".",
+			 errhint("To avoid a database shutdown, execute a database-wide VACUUM in \"%s\".",
 					 NameStr(ShmemVariableCache->limit_datname))));
 	}
 
@@ -299,7 +299,7 @@ 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 full-database VACUUM in \"%s\".",
+			errhint("To avoid a database shutdown, execute a database-wide VACUUM in \"%s\".",
 					NameStr(*oldest_datname))));
 }
 

Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`	`* Copyright (c) 2000-2008, PostgreSQL Global Development Group`
`7`	`7`	`*`
`8`	`8`	`* IDENTIFICATION`
`9`		`- * $PostgreSQL: pgsql/src/backend/access/transam/varsup.c,v 1.81 2008/01/01 19:45:48 momjian Exp $`
	`9`	`+ * $PostgreSQL: pgsql/src/backend/access/transam/varsup.c,v 1.82 2008/12/11 18:16:18 tgl Exp $`
`10`	`10`	`*`
`11`	`11`	`*-------------------------------------------------------------------------`
`12`	`12`	`*/`
`@@ -93,7 +93,7 @@ GetNewTransactionId(bool isSubXact)`
`93`	`93`	`(errmsg("database \"%s\" must be vacuumed within %u transactions",`
`94`	`94`	`NameStr(ShmemVariableCache->limit_datname),`
`95`	`95`	`ShmemVariableCache->xidWrapLimit - xid),`
`96`		`- errhint("To avoid a database shutdown, execute a full-database VACUUM in \"%s\".",`
	`96`	`+ errhint("To avoid a database shutdown, execute a database-wide VACUUM in \"%s\".",`
`97`	`97`	`NameStr(ShmemVariableCache->limit_datname))));`
`98`	`98`	`}`
`99`	`99`
`@@ -299,7 +299,7 @@ SetTransactionIdLimit(TransactionId oldest_datfrozenxid,`
`299`	`299`	`(errmsg("database \"%s\" must be vacuumed within %u transactions",`
`300`	`300`	`NameStr(*oldest_datname),`
`301`	`301`	`xidWrapLimit - curXid),`
`302`		`- errhint("To avoid a database shutdown, execute a full-database VACUUM in \"%s\".",`
	`302`	`+ errhint("To avoid a database shutdown, execute a database-wide VACUUM in \"%s\".",`
`303`	`303`	`NameStr(*oldest_datname))));`
`304`	`304`	`}`
`305`	`305`