Changes from Vince Vielhaber to allow the optional clauses of CREATE

USER and ALTER USER to appear in any order, not only the fixed order
they used to be required to appear in.
Also, some changes from Tom Lane to create a FULL option for VACUUM;
it doesn't do anything yet, but I needed to change many of the same
files to make that happen, so now seemed like a good time.

4 files changed, 99 insertions, 40 deletions

diff --git a/doc/src/sgml/ref/alter_user.sgml b/doc/src/sgml/ref/alter_user.sgml
index 8579b4f09a1..534d2a7eb2d 100644
--- a/doc/src/sgml/ref/alter_user.sgml
+++ b/doc/src/sgml/ref/alter_user.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_user.sgml,v 1.13 2000/07/22 04:30:26 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_user.sgml,v 1.14 2001/07/10 22:09:27 tgl Exp $
 Postgres documentation
 -->
 
@@ -20,13 +20,17 @@ Postgres documentation
  </refnamediv>
  <refsynopsisdiv>
   <refsynopsisdivinfo>
-   <date>1999-07-20</date>
+   <date>2001-07-10</date>
   </refsynopsisdivinfo>
   <synopsis>
-ALTER USER <replaceable class="PARAMETER">username</replaceable>
-    [ WITH PASSWORD '<replaceable class="PARAMETER">password</replaceable>' ]
-    [ CREATEDB | NOCREATEDB ] [ CREATEUSER | NOCREATEUSER ]
-    [ VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>' ]
+ALTER USER <replaceable class="PARAMETER">username</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
+
+where <replaceable class="PARAMETER">option</replaceable> can be:
+
+	  PASSWORD '<replaceable class="PARAMETER">password</replaceable>' 
+        | CREATEDB | NOCREATEDB
+        | CREATEUSER | NOCREATEUSER 
+        | VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>'
   </synopsis>
 
   <refsect2 id="R2-SQL-ALTERUSER-1">
@@ -138,11 +142,20 @@ ERROR:  ALTER USER: user "username" does not exist
   </title>
   <para>
    <command>ALTER USER</command> is used to change the attributes of a user's
-   <productname>Postgres</productname> account. Only a database superuser
+   <productname>Postgres</productname> account.  Attributes not mentioned
+   in the command retain their previous settings.
+  </para>
+  <para>
+   Only a database superuser
    can change privileges and password expiration with this command. Ordinary
    users can only change their own password.
   </para>
   <para>
+   <command>ALTER USER</command> cannot change a user's group memberships.
+   Use <xref linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title">
+   to do that.
+  </para>
+  <para>
    Use <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
    to create a new user and <xref linkend="SQL-DROPUSER"
    endterm="SQL-DROPUSER-title"> to remove a user.
diff --git a/doc/src/sgml/ref/create_user.sgml b/doc/src/sgml/ref/create_user.sgml
index df98765c7f5..8c97dbcf867 100644
--- a/doc/src/sgml/ref/create_user.sgml
+++ b/doc/src/sgml/ref/create_user.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_user.sgml,v 1.16 2000/10/12 22:08:42 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_user.sgml,v 1.17 2001/07/10 22:09:27 tgl Exp $
 Postgres documentation
 -->
 
@@ -20,16 +20,19 @@ Postgres documentation
  </refnamediv>
  <refsynopsisdiv>
   <refsynopsisdivinfo>
-   <date>1999-07-20</date>
+   <date>2001-07-10</date>
   </refsynopsisdivinfo>
   <synopsis>
-CREATE USER <replaceable class="PARAMETER">username</replaceable>
-    [ WITH
-     [ SYSID <replaceable class="PARAMETER">uid</replaceable> ]
-     [ PASSWORD '<replaceable class="PARAMETER">password</replaceable>' ] ]
-    [ CREATEDB   | NOCREATEDB ] [ CREATEUSER | NOCREATEUSER ]
-    [ IN GROUP     <replaceable class="PARAMETER">groupname</replaceable> [, ...] ]
-    [ VALID UNTIL  '<replaceable class="PARAMETER">abstime</replaceable>' ]
+CREATE USER <replaceable class="PARAMETER">username</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
+
+where <replaceable class="PARAMETER">option</replaceable> can be:
+    
+	  SYSID <replaceable class="PARAMETER">uid</replaceable> 
+        | PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
+        | CREATEDB | NOCREATEDB
+        | CREATEUSER | NOCREATEUSER
+        | IN GROUP <replaceable class="PARAMETER">groupname</replaceable> [, ...]
+        | VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>' 
   </synopsis>
   
   <refsect2 id="R2-SQL-CREATEUSER-1">
@@ -115,6 +118,7 @@ CREATE USER <replaceable class="PARAMETER">username</replaceable>
       <listitem>
        <para>
 	A name of a group into which to insert the user as a new member.
+	Multiple group names may be listed.
        </para>
       </listitem>
      </varlistentry>
@@ -164,7 +168,7 @@ CREATE USER <replaceable class="PARAMETER">username</replaceable>
    Description
   </title>
   <para>
-   CREATE USER will add a new user to an instance of 
+   <command>CREATE USER</command> will add a new user to an instance of 
    <productname>Postgres</productname>. Refer to the administrator's
    guide for information about managing users and authentication.
    You must be a database superuser to use this command.
@@ -173,7 +177,8 @@ CREATE USER <replaceable class="PARAMETER">username</replaceable>
    Use <xref linkend="SQL-ALTERUSER" endterm="SQL-ALTERUSER-title">
    to change a user's password and privileges, and <xref linkend="SQL-DROPUSER"
    endterm="SQL-DROPUSER-title"> to remove a user.
-   Use <command>ALTER GROUP</command> to add or remove the user from other groups.
+   Use <xref linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title">
+   to add or remove the user from other groups.
    <productname>Postgres</productname>
    comes with a script <xref linkend="APP-CREATEUSER"
    endterm="APP-CREATEUSER-title">
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 7ce61b72cc8..e8374725b34 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.16 2001/05/25 15:45:31 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.17 2001/07/10 22:09:28 tgl Exp $
 Postgres documentation
 -->
 
@@ -20,16 +20,16 @@ Postgres documentation
  </refnamediv>
  <refsynopsisdiv>
   <refsynopsisdivinfo>
-   <date>2001-05-04</date>
+   <date>2001-07-10</date>
   </refsynopsisdivinfo>
   <synopsis>
-VACUUM [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> ]
-VACUUM [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">table</replaceable> [ (<replaceable class="PARAMETER">column</replaceable> [, ...] ) ] ]
+VACUUM [ FULL ] [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> ]
+VACUUM [ FULL ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">table</replaceable> [ (<replaceable class="PARAMETER">column</replaceable> [, ...] ) ] ]
   </synopsis>
 
   <refsect2 id="R2-SQL-VACUUM-1">
    <refsect2info>
-    <date>1998-10-04</date>
+    <date>2001-07-10</date>
    </refsect2info>
    <title>
     Inputs
@@ -38,6 +38,15 @@ VACUUM [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">table</replaceable>
    <para>
     <variablelist>
      <varlistentry>
+      <term>FULL</term>
+      <listitem>
+       <para>
+        Selects <quote>full</quote> vacuum, which may reclaim more space,
+	but takes much longer and exclusively locks the table.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
       <term>VERBOSE</term>
       <listitem>
        <para>
@@ -58,7 +67,8 @@ VACUUM [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">table</replaceable>
       <term><replaceable class="PARAMETER">table</replaceable></term>
       <listitem>
        <para>
-	The name of a specific table to vacuum. Defaults to all tables.
+	The name of a specific table to vacuum. Defaults to all tables
+	in the current database.
        </para>
       </listitem>
      </varlistentry>
@@ -138,7 +148,7 @@ NOTICE:  Index <replaceable class="PARAMETER">index</replaceable>: Pages 28;
 
  <refsect1 id="R1-SQL-VACUUM-1">
   <refsect1info>
-   <date>1998-10-04</date>
+   <date>2001-07-10</date>
   </refsect1info>
   <title>
    Description
@@ -159,6 +169,16 @@ NOTICE:  Index <replaceable class="PARAMETER">index</replaceable>: Pages 28;
   </para>
 
   <para>
+   Plain <command>VACUUM</command> simply reclaims space and makes it
+   available for re-use.  This form of the command can operate in parallel
+   with normal reading and writing of the table.  <command>VACUUM
+   FULL</command> does more extensive processing, including moving of tuples
+   across blocks to try to compact the table to the minimum number of disk
+   blocks.  This is much slower and requires an exclusive lock on each table
+   while it is being processed.
+  </para>
+
+  <para>
    <command>VACUUM ANALYZE</command> performs a <command>VACUUM</command>
    and then an <command>ANALYZE</command> for each selected table.  This
    is a handy combination form for routine maintenance scripts.  See
@@ -168,7 +188,7 @@ NOTICE:  Index <replaceable class="PARAMETER">index</replaceable>: Pages 28;
 
   <refsect2 id="R2-SQL-VACUUM-3">
    <refsect2info>
-    <date>1998-10-04</date>
+    <date>2001-07-10</date>
    </refsect2info>
    <title>
     Notes
@@ -176,8 +196,8 @@ NOTICE:  Index <replaceable class="PARAMETER">index</replaceable>: Pages 28;
 
    <para>
     We recommend that active production databases be
-    <command>VACUUM</command>-ed nightly, in order to remove
-    expired rows. After copying a large table into
+    <command>VACUUM</command>-ed frequently (at least nightly), in order to
+    remove expired rows. After copying a large table into
     <productname>Postgres</productname> or after deleting a large number
     of records, it may be a good idea to issue a <command>VACUUM
     ANALYZE</command> command for the affected table. This will update the
@@ -187,6 +207,14 @@ NOTICE:  Index <replaceable class="PARAMETER">index</replaceable>: Pages 28;
     choices in planning user queries.
    </para>
 
+   <para>
+    The <option>FULL</option> option is not recommended for routine use,
+    but may be useful in special cases.  An example is when you have deleted
+    most of the rows in a table and would like the table to physically shrink
+    to occupy less disk space.  <command>VACUUM FULL</command> will usually
+    shrink the table more than a plain <command>VACUUM</command> would.
+   </para>
+
   </refsect2>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index 1efa7fce93b..141d2dcd57b 100644
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.16 2001/03/17 16:27:31 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.17 2001/07/10 22:09:28 tgl Exp $
 Postgres documentation
 -->
 
@@ -24,8 +24,9 @@ Postgres documentation
    <command>vacuumdb</command>
    <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
    <arg><arg>-d</arg> <replaceable>dbname</replaceable></arg>
-   <group><arg>--analyze</arg><arg>-z</arg></group>
+   <group><arg>--full</arg><arg>-f</arg></group>
    <group><arg>--verbose</arg><arg>-v</arg></group>
+   <group><arg>--analyze</arg><arg>-z</arg></group>
    <arg>--table '<replaceable>table</replaceable>
     <arg>( <replaceable class="parameter">column</replaceable> [,...] )</arg>'
    </arg>
@@ -33,8 +34,9 @@ Postgres documentation
    <command>vacuumdb</command>
    <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
    <group><arg>--all</arg><arg>-a</arg></group>
-   <group><arg>--analyze</arg><arg>-z</arg></group>
+   <group><arg>--full</arg><arg>-f</arg></group>
    <group><arg>--verbose</arg><arg>-v</arg></group>
+   <group><arg>--analyze</arg><arg>-z</arg></group>
   </cmdsynopsis>
 
   <refsect2 id="R2-APP-VACUUMDB-1">
@@ -56,21 +58,21 @@ Postgres documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-z</term>
-      <term>--analyze</term>
+      <term>-a</term>
+      <term>--alldb</term>
       <listitem>
        <para>
-	Calculate statistics on the database for use by the optimizer.
+	Vacuum all databases.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-a</term>
-      <term>--alldb</term>
+      <term>-f</term>
+      <term>--full</term>
       <listitem>
        <para>
-	Vacuum all databases.
+        Perform <quote>full</quote> vacuuming.
        </para>
       </listitem>
      </varlistentry>
@@ -86,6 +88,16 @@ Postgres documentation
      </varlistentry>
 
      <varlistentry>
+      <term>-z</term>
+      <term>--analyze</term>
+      <listitem>
+       <para>
+	Calculate statistics for use by the optimizer.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term>-t <replaceable class="parameter">table</replaceable> [ (<replaceable class="parameter">column</replaceable> [,...]) ]</term>
       <term>--table <replaceable class="parameter">table</replaceable> [ (<replaceable class="parameter">column</replaceable> [,...]) ]</term>
       <listitem>
@@ -257,7 +269,7 @@ Postgres documentation
 
   <informalexample>
    <para>
-    To analyze for the optimzer a database named
+    To clean and analyze for the optimizer a database named
     <literal>bigdb</literal>:
 <screen>
 <prompt>$ </prompt><userinput>vacuumdb --analyze bigdb</userinput>
@@ -267,9 +279,10 @@ Postgres documentation
 
   <informalexample>
    <para>
-    To analyze a single column <literal>bar</literal> in table
+    To clean a single table
     <literal>foo</literal> in a database named
-    <literal>xyzzy</literal> for the optimizer:
+    <literal>xyzzy</literal>, and analyze a single column
+    <literal>bar</literal> of the table for the optimizer:
 <screen>
 <prompt>$ </prompt><userinput>vacuumdb --analyze --verbose --table 'foo(bar)' xyzzy</userinput>
 </screen>