<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.29 2002/07/28 15:22:20 petere 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 all <productname>PostgreSQL</productname> databases into a script file</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pg_dumpall</command>
   <group><arg>-c</arg><arg>--clean</arg></group>
   <group><arg>-g</arg><arg>--globals-only</arg></group>
   <arg>-h <replaceable>host</replaceable></arg>
   <arg>-p <replaceable>port</replaceable></arg>
   <arg>-U <replaceable>username</replaceable></arg>
   <arg>-W</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>

  <refsect2>
   <title>Options</title>

   <para>
    <application>pg_dumpall</application> accepts the following
    command line arguments:

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

     <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>
    Any other command line parameters are passed to the underlying
    <xref linkend="app-pgdump">
    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>
  </refsect2>
 </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 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:
-->
