postgres/doc/src/sgml/ref/pg_dumpall.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.33 2002/09/05 22:05:50 momjian Exp $
PostgreSQL documentation
-->

<refentry id="APP-PG-DUMPALL">
 <refmeta>
  <refentrytitle id="APP-PG-DUMPALL-TITLE"><application>pg_dumpall</application></refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>pg_dumpall</refname>
  <refpurpose>extract a <productname>PostgreSQL</productname> database cluster into a script file</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pg_dumpall</command>
   <arg rep="repeat"><replaceable>options</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1 id="app-pg-dumpall-description">
  <title>Description</title>

  <para>
   <application>pg_dumpall</application> is a utility for writing out
   (<quote>dumping</quote>) all PostgreSQL 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">
   to restore the databases.  It does this by calling <xref
   linkend="app-pgdump"> 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>

  <para>
   Thus, <application>pg_dumpall</application> is an integrated
   solution for backing up your databases.  But note a limitation:
   it cannot dump <quote>large objects</quote>, since
   <application>pg_dump</application> cannot dump such objects into
   text files.  If you have databases containing large objects,
   they should be dumped using one of <application>pg_dump</application>'s
   non-text output modes.
  </para>

  <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 privileges to execute the saved script in order to be
   allowed to add users and groups, and to create databases.
  </para>

  <para>
   The SQL script will be written to the standard output.  Shell
   operators should be used to redirect it into a file.
  </para>

  <para>
  <application>pg_dumpall</application> might need to connect several
  times to the <productname>PostgreSQL</productname> server, asking for
  a password each time. It is convenient to have a
  <filename>$HOME/.pgpass</> file in such cases.
  </para>

 </refsect1>

 <refsect1>
  <title>Options</title>

   <para>
    The following command-line options are used to control the output format.

    <variablelist>
     <varlistentry>
      <term>-c, --clean</term>
      <listitem>
       <para>
	Include SQL commands to clean (drop) database objects before
	recreating them.  (This option is fairly useless, since the
	output script expects to create the databases themselves;
	they would always be empty upon creation.)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-d</option></term>
      <term><option>--inserts</option></term>
      <listitem>
       <para>
	Dump data as <command>INSERT</command> commands (rather
	than <command>COPY</command>). This will make restoration very
	slow, but it makes the output more portable to other RDBMS
	packages.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-D</option></term>
      <term><option>--column-inserts</option></term>
      <term><option>--attribute-inserts</option></term>
      <listitem>
       <para>
	Dump data as <command>INSERT</command> commands with explicit
	column names (<literal>INSERT INTO
	<replaceable>table</replaceable>
	(<replaceable>column</replaceable>, ...) VALUES
	...</literal>).  This will make restoration very slow,
	but it is necessary if you desire to rearrange column ordering.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-g, --globals-only</term>
      <listitem>
       <para>
	Only dump global objects (users and groups), no databases.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-i</></term>
      <term><option>--ignore-version</></term>
      <listitem>
       <para>
        Ignore version mismatch between
        <application>pg_dumpall</application> and the database server.
        Since <application>pg_dumpall</application> knows a great deal
        about system catalogs, any given version of
        <application>pg_dumpall</application> is only intended to work
        with the corresponding release of the database server.  Use
        this option if you need to override the version check (and if
        <application>pg_dumpall</application> then fails, don't say
        you weren't warned).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-o</></term>
      <term><option>--oids</></term>
      <listitem>
       <para>
	Dump object identifiers (<acronym>OID</acronym>s) for every
	table.  Use this option if your application references the OID
	columns in some way (e.g., in a foreign key constraint).
	Otherwise, this option should not be used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-v</></term>
      <term><option>--verbose</></term>
      <listitem>
       <para>
	Specifies verbose mode.  This will cause
	<application>pg_dumpall</application> to print progress
	messages to standard error.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

  <para>
   The following command-line options control the database connection parameters.

   <variablelist>
     <varlistentry>
      <term>-h <replaceable>host</replaceable></term>
      <listitem>
       <para>
	Specifies the host name 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>port</replaceable></term>
      <listitem>
       <para>
        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 <replaceable>username</replaceable></term>
      <listitem>
       <para>
        Connect as the given user.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-W</term>
      <listitem>
       <para>
        Force a password prompt.  This should happen automatically if
        the server requires password authentication.
       </para>
      </listitem>
     </varlistentry>
   </variablelist>
  </para>

  <para>
   Long options are only available on some platforms.
  </para>
 </refsect1>


 <refsect1>
  <title>Environment</title>

  <variablelist>
   <varlistentry>
    <term><envar>PGHOST</envar></term>
    <term><envar>PGPORT</envar></term>
    <term><envar>PGUSER</envar></term>

    <listitem>
     <para>
      Default connection parameters.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>


 <refsect1>
  <title>Notes</title>

  <para>
   Since <application>pg_dumpall</application> calls
   <application>pg_dump</application> internally, some diagnostic
   messages will refer to <application>pg_dump</application>.
  </para>

  <para>
   <application>pg_dumpall</application> will need to connect several
   times to the <productname>PostgreSQL</productname> server.  If password
   authentication is configured, it will ask for a password each time. In
   that case it would be convenient to set up a password file.
  </para>

  <comment>But where is that password file documented?</comment>
 </refsect1>


 <refsect1 id="app-pg-dumpall-ex">
  <title>Examples</title>
  <para>
   To dump all databases:

<screen>
<prompt>$</prompt> <userinput>pg_dumpall &gt; db.out</userinput>
</screen>
  </para>

  <para>
   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>
  <title>See Also</title>

  <para>
    <xref linkend="app-pgdump">, <xref linkend="app-psql">.  Check
    there for details on possible error conditions.
  </para>
 </refsect1>   

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->