From 28e9e9a24e7a6c7bcf799620d8c9d06151d349d5 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Tue, 19 Dec 2000 22:12:47 +0000
Subject: [PATCH] Rename --accounts-only to --globals-only, polish
documentation.
---
doc/src/sgml/ref/pg_dumpall.sgml | 354 +++++++++----------------------
src/bin/pg_dump/pg_dumpall.sh | 22 +-
2 files changed, 108 insertions(+), 268 deletions(-)
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index ac61de92b96..3025ad68942 100644
--- 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 > 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 0429a9c3447..6eae7e2df24 100644
--- 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.
--
GitLab