Rename --accounts-only to --globals-only, polish documentation.

diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index ac61de92b9677039f78640b46ebfa5ccf2e614ad..3025ad689429aaaa974a34ec46de4303a132fc24 100644 (file)
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -1,316 +1,156 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.16 2000/11/30 23:20:50 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.17 2000/12/19 22:12:46 petere Exp $
 Postgres documentation
 -->
 
-<refentry id="APP-PGDUMPALL">
+<refentry id="APP-PG-DUMPALL">
+ <docinfo>
+  <date>2000-12-19</date>
+ </docinfo>
+
  <refmeta>
-  <refentrytitle id="APP-PGDUMPALL-TITLE">
-   <application>pg_dumpall</application>
-  </refentrytitle>
+  <refentrytitle id="APP-PG-DUMPALL-TITLE"><application>pg_dumpall</application></refentrytitle>
+  <manvolnum>1</manvolnum>
   <refmiscinfo>Application</refmiscinfo>
  </refmeta>
+
  <refnamediv>
-  <refname>
-   <application>pg_dumpall</application>
-  </refname>
-  <refpurpose>
-   Extract all <productname>Postgres</productname> databases into a script file
-  </refpurpose>
+  <refname>pg_dumpall</refname>
+  <refpurpose>Extract all databases into a script file</refpurpose>
  </refnamediv>
- <refsynopsisdiv>
-  <refsynopsisdivinfo>
-   <date>1999-07-20</date>
-  </refsynopsisdivinfo>
-  <synopsis>
-pg_dumpall [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ] [ -a ] [ -d ] [ -D ] [ -O ] [ -s ] [ -u ] [ -v ] [ -x ] [ --accounts-only ]
-  </synopsis>
-
-  <refsect2 id="R2-APP-PG-DUMPALL-1">
-   <refsect2info>
-    <date>1998-10-04</date>
-   </refsect2info>
-   <title>
-    Inputs
-   </title>
-   <para>
-    <application>pg_dumpall</application> accepts the following command line arguments:
-
-    <variablelist>
-     <varlistentry>
-      <term>-a</term>
-      <listitem>
-       <para>
-       Dump out only the data, no schema (definitions).
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term>-d</term>
-      <listitem>
-       <para>
-       Dump data as proper insert strings.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term>-D</term>
-      <listitem>
-       <para>
-       Dump data as inserts with attribute names
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term>-n</term>
-      <listitem>
-       <para>
-       Suppress double quotes around identifiers unless absolutely necessary.
-       This may cause trouble loading this dumped data if there are reserved words
-       used for identifiers.
-       </para>
-      </listitem>
-     </varlistentry>
 
-     <varlistentry>
-      <term>-o</term>
-      <listitem>
-       <para>
-       Dump object identifiers (<acronym>OID</acronym>s) for every table.
-       </para>
-      </listitem>
-     </varlistentry>
+ <refsynopsisdiv>
+  <cmdsynopsis>
+   <command>pg_dumpall</command>
+   <group><arg>-c</arg><arg>--clean</arg></group>
+   <arg>-h <replaceable>host</replaceable></arg>
+   <arg>-p <replaceable>port</replaceable></arg>
+   <arg>--globals-only</arg>
+  </cmdsynopsis>
+ </refsynopsisdiv>
 
-     <varlistentry>
-      <term>-s</term>
-      <listitem>
-       <para>
-       Dump out only the schema (definitions), no data.
-       </para>
-      </listitem>
-     </varlistentry>
+ <refsect1 id="app-pg-dumpall-description">
+  <title>Description</title>
 
-     <varlistentry>
-      <term>-u</term>
-      <listitem>
-       <para>
-       Use password authentication. Prompts for username and password.
-       </para>
-      </listitem>
-     </varlistentry>
+  <para>
+   <application>pg_dumpall</application> is a utility for writing out
+   (<quote>dumping</quote>) all Postgres databases of a cluster into
+   one script file.  The script file contains SQL commands that can be
+   used as input to <xref linkend="app-psql" endterm="app-psql-title">
+   to restore the databases.  It does this by calling <xref
+   linkend="app-pgdump" endterm="app-pgdump-title"> for each database
+   in a cluster.  <application>pg_dumpall</application> also dumps
+   global objects that are common to all databases.
+   (<application>pg_dump</application> does not save these objects.)
+   This currently includes the information about database users and
+   groups.
+  </para>
 
-     <varlistentry>
-      <term>-v</term>
-      <listitem>
-       <para>
-       Specifies verbose mode.
-       </para>
-      </listitem>
-     </varlistentry>
+  <para>
+   Thus, <application>pg_dumpall</application> is an integrated
+   solution for backing up your databases.
+  </para>
 
-     <varlistentry>
-      <term>-x</term>
-      <listitem>
-       <para>
-       Prevent dumping ACLs (grant/revoke commands) and table ownership information.
-       </para>
-      </listitem>
-     </varlistentry>
+  <para>
+   Since <application>pg_dumpall</application> reads tables from all
+   databases you will most likely have to connect as a database
+   superuser in order to produce a complete dump.  Also you will need
+   superuser priviledges to execute the saves script in order to be
+   allowed to add users and groups, and to create databases.
+  </para>
 
-     <varlistentry>
-      <term>--accounts-only</term>
-      <listitem>
-       <para>
-       Only dump user and group information, nothing else.
-       </para>
-      </listitem>
-     </varlistentry>
+  <para>
+   The SQL script will be written to the standard ouput.  Shell
+   operators should be used to redirect it into a file.
+  </para>
 
-    </variablelist>
-   </para>
+  <refsect2>
+   <title>Options</title>
 
    <para>
-    <application>pg_dumpall</application> also accepts 
-    the following command line arguments for connection parameters:
+    <application>pg_dumpall</application> accepts the following
+    command line arguments:
 
     <variablelist>
      <varlistentry>
-      <term>-h <replaceable class="parameter">host</replaceable></term>
+      <term>-h <replaceable>host</replaceable></term>
       <listitem>
        <para>
-       Specifies the hostname of the machine on which the 
-       <application>postmaster</application>
-       is running.  If host begins with a slash, it is used 
-       as the directory for the unix domain socket.
+       Specifies the hostname of the machine on which the database
+       server is running.  If host begins with a slash, it is used as
+       the directory for the Unix domain socket.  The default is
+       taken from the <envar>PGHOST</envar> environment variable, if
+       set, else a Unix domain socket connection is attempted.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-p <replaceable class="parameter">port</replaceable></term>
+      <term>-p <replaceable>port</replaceable></term>
       <listitem>
        <para>
-       Specifies the Internet TCP/IP port or local Unix domain socket file 
-       extension on which the <application>postmaster</application>
-       is listening for connections.  The port number defaults to 5432,
-       or the value of the <envar>PGPORT</envar>
-       environment variable (if set).
+        The port number on which the server is listening.  Defaults to
+        the <envar>PGPORT</envar> environment variable, if set, or a
+        compiled-in default.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-u</term>
+      <term>--globals-only</term>
       <listitem>
        <para>
-       Use password authentication. 
-       Prompts for
-       <replaceable class="parameter">username</replaceable>
-       and <replaceable class="parameter">password</replaceable>.
+       Only dump global objects (users and groups), no databases.
        </para>
       </listitem>
      </varlistentry>
+
     </variablelist>
    </para>
-  </refsect2>
 
-  <refsect2 id="R2-APP-PG-DUMPALL-2">
-   <refsect2info>
-    <date>1998-10-04</date>
-   </refsect2info>
-   <title>
-    Outputs
-   </title>
    <para>
-    <application>pg_dumpall</application> will create a file or
-    write to <filename>stdout</filename>.
-
-    <variablelist>
-     <varlistentry>
-      <term><computeroutput>
-Connection to database 'template1' failed.
-connectDBStart() -- connect() failed: No such file or directory
-        Is the postmaster running locally
-        and accepting connections on Unix socket '/tmp/.s.PGSQL.5432'?
-       </computeroutput></term>
-      <listitem>
-       <para>
-       <application>pg_dumpall</application> could not attach to the 
-       <application>postmaster</application> 
-       process on the specified host and port.  If you see this message,
-       ensure that the <application>postmaster</application> 
-       is running on the proper host and that you have specified the proper
-       port.  If your site uses an authentication system, ensure that you
-       have obtained the required authentication credentials.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><computeroutput>
-Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
-FATAL 1:  SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
-       </computeroutput></term>
-      <listitem>
-       <para>
-       You do not have a valid entry in the relation <literal>pg_shadow</literal>
-       and and will not be allowed to access <productname>Postgres</productname>. 
-       Contact your <productname>Postgres</productname> administrator.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term><computeroutput>
-dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
-       </computeroutput></term>
-      <listitem>
-       <para>
-       You do not have permission to read the database.
-       Contact your <productname>Postgres</productname> site administrator.
-       </para>
-      </listitem>
-     </varlistentry>
-    </variablelist>
+    Any other command line parameters are passed to the underlying
+    <xref endterm="app-pgdump-title" linkend="app-pgdump-title">
+    calls.  This is useful to control some aspects of the output
+    format, but some options such as <option>-f</option>,
+    <option>-t</option>, and <replaceable
+    class="parameter">dbname</replaceable> should be avoided.
    </para>
-
-   <note>
-    <para>
-     <application>pg_dumpall</application> internally executes
-     <command>SELECT</command> statements. If you have problems running
-     <application>pg_dumpall</application>,
-     make sure you are able to select information from the database using, for
-     example, <application>psql</application>.
-    </para>
-   </note>
   </refsect2>
- </refsynopsisdiv>
+ </refsect1>
 
- <refsect1 id="R1-APP-PG-DUMPALL-1">
-  <refsect1info>
-   <date>1998-10-04</date>
-  </refsect1info>
-  <title>
-   Description
-  </title>
-  <para>
-   <application>pg_dumpall</application>
-   is a utility for dumping out all Postgres databases into one file.
-   It also dumps the pg_shadow table, which is global to all databases.
-   <application>pg_dumpall</application> includes in this file the proper commands
-   to automatically create each dumped database before loading.
-  </para>
+ <refsect1 id="app-pg-dumpall-usage">
+  <title>Usage</title>
   <para>
-   <application>pg_dumpall</application> takes all <application>pg_dump</application>
-   options, but <option>-f</option>, <option>-t</option> and 
-   <replaceable class="parameter">dbname</replaceable>
-   should be omitted.
+   To dump all databases:
+
+<screen>
+<prompt>$</prompt> <userinput>pg_dumpall &gt; db.out</userinput>
+</screen>
   </para>
+
   <para>
-   Refer to 
-   <xref endterm="app-pgdump-title" linkend="app-pgdump-title">
-   for more information on this capability.
+   To reload this database use, for example:
+<screen>
+<prompt>$</prompt> <userinput>psql -f db.out template1</userinput>
+</screen>
+   (It is not important to which database you connect here since the
+   script file created by <application>pg_dumpall</application> will
+   contain the appropriate commands to create and connect to the saved
+   databases.
   </para>
  </refsect1>
 
- <refsect1 id="R1-APP-PG-DUMPALL-2">
-  <refsect1info>
-   <date>1998-10-04</date>
-  </refsect1info>
-  <title>
-   Usage
-  </title>
-  <para>
-   To dump all databases:
+ <refsect1>
+  <title>See Also</title>
 
-   <programlisting>
-$ pg_dumpall > db.out
-   </programlisting>
-
-   <tip>
-    <para>
-     You can use most <application>pg_dump</application> options
-     for <application>pg_dumpall</application>.
-    </para>
-   </tip>
-  </para>
   <para>
-   To reload this database:
-
-   <programlisting>
-$ psql -e template1 < db.out
-   </programlisting>
+    <xref linkend="app-pgdump" endterm="app-pgdump-title">, <xref
+    linkend="app-psql" endterm="app-psql-title">.  Check there for
+    details on possible error conditions.
   </para>
-  <tip>
-   <para>
-    You can use most <application>psql</application> options
-    when reloading.
-   </para>
-  </tip>
- </refsect1>
+ </refsect1>   
+
 </refentry>
 
 <!-- Keep this comment at the end of the file

diff --git a/src/bin/pg_dump/pg_dumpall.sh b/src/bin/pg_dump/pg_dumpall.sh
index 0429a9c34476e09b18ed05e82f4052e5d5e21e6f..6eae7e2df24488da550f685c02303499884f6af8 100644 (file)
--- a/src/bin/pg_dump/pg_dumpall.sh
+++ b/src/bin/pg_dump/pg_dumpall.sh
@@ -6,7 +6,7 @@
 # and "pg_group" tables, which belong to the whole installation rather
 # than any one individual database.
 #
-# $Header: /cvsroot/pgsql/src/bin/pg_dump/Attic/pg_dumpall.sh,v 1.8 2000/11/14 18:37:46 tgl Exp $
+# $Header: /cvsroot/pgsql/src/bin/pg_dump/Attic/pg_dumpall.sh,v 1.9 2000/12/19 22:12:47 petere Exp $
 
 CMDNAME=`basename $0`
 
@@ -72,7 +72,7 @@ fi
 
 usage=
 cleanschema=
-accounts_only=
+globals_only=
 
 #
 # Scan options. We're interested in the -h (host), -p (port), and -c (clean) options.
@@ -110,8 +110,8 @@ while [ $# -gt 0 ] ; do
                 cleanschema=yes
                 pgdumpextraopts="$pgdumpextraopts -c"
                 ;;
-        --accounts-only)
-                accounts_only=yes
+        --globals-only)
+                globals_only=yes
                 ;;
         *)
                 pgdumpextraopts="$pgdumpextraopts $1"
@@ -122,16 +122,16 @@ done
 
 
 if [ "$usage" ] ; then
-    echo "$CMDNAME dumps a PostgreSQL database cluster."
+    echo "$CMDNAME extracts a PostgreSQL database cluster into an SQL script file."
     echo
     echo "Usage:"
-    echo "  $CMDNAME [ -c ] [ -h host ] [ -p port ] [ --accounts-only ]"
+    echo "  $CMDNAME [ -c ] [ -h HOSTNAME ] [ -p PORT ] [ --globals-only ]"
     echo
     echo "Options:"
-    echo "  -c, --clean              clean (drop) schema prior to create"
-    echo "  -h, --host <hostname>    server host name"
-    echo "  -p, --port <port>        server port number"
-    echo "  --accounts-only          only dump users and groups"
+    echo "  -c, --clean            Clean (drop) schema prior to create"
+    echo "  -h, --host=HOSTNAME    Server host name"
+    echo "  -p, --port=PORT        Server port number"
+    echo "  --globals-only         Only dump global objects, no databases"
     echo "Any extra options will be passed to pg_dump."
     echo
     echo "Report bugs to <pgsql-bugs@postgresql.org>."
@@ -184,7 +184,7 @@ while read GRONAME GROSYSID GROLIST ; do
 done
 
 
-test "$accounts_only" = yes && exit 0
+test "$globals_only" = yes && exit 0
 
 
 # For each database, run pg_dump to dump the contents of that database.