pg_dump.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.55 2003/01/19 00:13:30 momjian Exp $
PostgreSQL documentation
-->

<refentry id="APP-PGDUMP">
 <refmeta>
  <refentrytitle>pg_dump</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>pg_dump</refname>

  <refpurpose>
   extract a <productname>PostgreSQL</productname> database into a script file or other archive file 
  </refpurpose>
 </refnamediv>

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


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

  <para>
   <application>pg_dump</application> is a utility for saving a
   <productname>PostgreSQL</productname> database into a script or an
   archive file.  The script files are in plain-text format and
   contain the SQL commands required to reconstruct the database to
   the state it was in at the time it was saved.  To restore these
   scripts, use <xref linkend="app-psql">.  They can be used to
   reconstruct the database even on other machines and other
   architectures, with some modifications even on other SQL database
   products.
  </para>

  <para>
   Furthermore, there are alternative archive file formats
   that are meant to be used with <xref linkend="app-pgrestore"> to
   rebuild the database, and they also allow
   <application>pg_restore</application> to be selective about what is
   restored, or even to reorder the items prior to being restored. The
   archive files are also designed to be portable across
   architectures.
  </para>

  <para>
   <application>pg_dump</application> will save the information necessary to
   re-generate all user-defined types, functions, tables, indexes,
   aggregates, and operators.  In addition, all the data is copied out
   in text format so that it can be readily copied in again, as well
   as imported into tools for editing.
  </para>

  <para>
   When used with one of the archive file formats and combined with
   <application>pg_restore</application>, <application>pg_dump</application> provides a
   flexible archival and 
   transfer mechanism. <application>pg_dump</application> can be used to
   backup an entire database, then <application>pg_restore</application> can
   be used to examine the archive and/or select which parts of the
   database are to be restored.
   The most flexible output file format is the <quote>custom</quote>
   format (<option>-Fc</option>). It allows for selection and
   reordering of all archived items, and is compressed by default. The
   <filename>tar</filename> format (<option>-Ft</option>) is not
   compressed and it is not possible to reorder data when loading, but
   it is otherwise quite flexible; moreover, it can be manipulated with
   other tools such as <filename>tar</filename>.
  </para>

  <para>
   While running <command>pg_dump</command>, one should examine the
   output for any warnings (printed on standard error), especially in
   light of the limitations listed below.
  </para>

  <para>
   <application>pg_dump</application> makes consistent backups even if the
   database is being used concurrently.  <application>pg_dump</application>
   does not block other users accessing the database (readers or
   writers).
  </para>
 </refsect1>

 <refsect1 id="pg-dump-options">
  <title>Options</title>

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

    <variablelist>
     <varlistentry>
      <term><replaceable class="parameter">dbname</replaceable></term>
      <listitem>
       <para>
	Specifies the name of the database to be dumped.  If this is
	not specified, the environment variable
	<envar>PGDATABASE</envar> is used.  If that is not set, the
	user name specified for the connection is used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-a</></term>
      <term><option>--data-only</></term>
      <listitem>
       <para>
	Dump only the data, not the schema (data definitions).
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the other formats, you may specify the option when you
        call <command>pg_restore</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-b</></term>
      <term><option>--blobs</></term>
      <listitem>
       <para>
 	Include large objects in dump.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-c</option></term>
      <term><option>--clean</option></term>
      <listitem>
       <para>
        Output commands to clean (drop)
	database objects prior to (the commands for) creating them.
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the other formats, you may specify the option when you
        call <command>pg_restore</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-C</></term>
      <term><option>--create</></term>
      <listitem>
       <para>
	Begin the output with a command to create the
	database itself and reconnect to the created database.  (With a
	script of this form, it doesn't matter which database you connect
	to before running the script.)
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the other formats, you may specify the option when you
        call <command>pg_restore</command>.
       </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 archives more portable to other SQL database
	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><option>-f <replaceable class="parameter">file</replaceable></option></term>
      <term><option>--file=<replaceable class="parameter">file</replaceable></option></term>
      <listitem>
       <para>
	Send output to the specified file.  If this is omitted, the
	standard output is used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-F <replaceable class="parameter">format</replaceable></option></term>
      <term><option>--format=<replaceable class="parameter">format</replaceable></option></term>
      <listitem>
       <para>
        Selects the format of the output.
	<replaceable>format</replaceable> can be one of the following:

       <variablelist>
        <varlistentry>
         <term>p</term>
         <listitem>
          <para>
           Output a plain-text <acronym>SQL</acronym> script file (default)
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term>t</term>
         <listitem>
          <para>
         Output a <filename>tar</filename> archive suitable for input into 
         <application>pg_restore</application>. Using this archive format 
         allows reordering and/or exclusion of schema elements 
         at the time the database is restored. It is also possible to limit 
         which data is reloaded at restore time.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term>c</term>
         <listitem>
          <para>
         Output a custom archive suitable for input into 
         <application>pg_restore</application>. This is the most flexible 
         format in that it allows reordering of data load as well 
         as schema elements. This format is also compressed by default.
          </para>
         </listitem>
        </varlistentry>

       </variablelist>
       </para>

      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-i</></term>
      <term><option>--ignore-version</></term>
      <listitem>
       <para>
        Ignore version mismatch between
        <application>pg_dump</application> and the database server.
       </para>

       <para>
        <application>pg_dump</application> can handle databases from
        previous releases of <productname>PostgreSQL</>, but very old
        versions are not supported anymore (currently prior to 7.0).
        Use this option if you need to override the version check (and
        if <application>pg_dump</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 <acronym>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>-O</></term>
      <term><option>--no-owner</option></term>
      <listitem>
       <para>
        Do not output commands to set the
	object ownership to match the original database.  Typically,
	<application>pg_dump</application> issues
	(<application>psql</application>-specific) <command>\connect</command>
	statements to set ownership of schema elements.  See also
	under <option>-R</option> and <option>-X
	use-set-session-authorization</option>.  Note that
	<option>-O</option> does not prevent all reconnections to the
	database, only the ones that are exclusively used for
	ownership adjustments.
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the other formats, you may specify the option when you
        call <command>pg_restore</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-R</option></term>
      <term><option>--no-reconnect</option></term>
      <listitem>
       <para>
	Prohibit <application>pg_dump</application>
        from outputting a script that would require reconnections to
        the database while being restored.  An average restoration
        script usually has to reconnect several times as different
        users to set the original ownerships of the objects.  This
        option is a rather blunt instrument because it makes
        <application>pg_dump</application> lose this ownership information,
        <emphasis>unless</emphasis> you use the <option>-X
        use-set-session-authorization</option> option.
       </para>

       <para>
        One possible reason why reconnections during restore might not
        be desired is if the access to the database requires manual
        interaction (e.g., passwords).
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the other formats, you may specify the option when you
        call <command>pg_restore</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-s</option></term>
      <term><option>--schema-only</option></term>
      <listitem>
       <para>
	Dump only the schema (data definitions), no data.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-S <replaceable class="parameter">username</replaceable></option></term>
      <term><option>--superuser=<replaceable class="parameter">username</replaceable></option></term>
      <listitem>
       <para>
        Specify the superuser user name to use when disabling triggers.
	This is only relevant if <option>--disable-triggers</> is used.
	(Usually, it's better to specify
	<option>--use-set-session-authorization</>, and then start the
	resulting script as superuser.)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-t <replaceable class="parameter">table</replaceable></option></term>
      <term><option>--table=<replaceable class="parameter">table</replaceable></option></term>
      <listitem>
       <para>
	Dump data for <replaceable class="parameter">table</replaceable> only.
       </para>
      </listitem>
     </varlistentry>

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

     <varlistentry>
      <term><option>-x</></term>
      <term><option>--no-privileges</></term>
      <term><option>--no-acl</></term>
      <listitem>
       <para>
	Prevent dumping of access privileges (grant/revoke commands).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-X use-set-session-authorization</></term>
      <term><option>--use-set-session-authorization</></term>
      <listitem>
       <para>
        Normally, if a (plain-text mode) script generated by
        <application>pg_dump</application> must alter the current database
        user (e.g., to set correct object ownerships), it uses the
        <application>psql</application> <command>\connect</command> command.
        This command actually opens a new connection, which might
        require manual interaction (e.g., passwords).  If you use the
        <option>-X use-set-session-authorization</option> option, then
        <application>pg_dump</application> will instead output <xref
        linkend="sql-set-session-authorization" endterm="sql-set-session-authorization-title"> commands.  This has
        the same effect, but it requires that the user restoring the
        database from the generated script be a database superuser.
        This option effectively overrides the <option>-R</option>
        option.
       </para>

       <para>
        Since <xref linkend="sql-set-session-authorization" endterm="sql-set-session-authorization-title"> is a
        standard SQL command, whereas <command>\connect</command> only
        works in <application>psql</application>, this option also enhances
        the theoretical portability of the output script.
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the other formats, you may specify the option when you
        call <command>pg_restore</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-X disable-triggers</></term>
      <term><option>--disable-triggers</></term>
      <listitem>
       <para>
        This option is only relevant when creating a data-only dump.
	It instructs <application>pg_dump</application> to include commands
	to temporarily disable triggers on the target tables while
	the data is reloaded.  Use this if you have referential
	integrity checks or other triggers on the tables that you
	do not want to invoke during data reload.
       </para>

       <para>
        Presently, the commands emitted for <option>--disable-triggers</>
	must be done as superuser.  So, you should also specify
	a superuser name with <option>-S</>, or preferably specify
	<option>--use-set-session-authorization</> and then be careful to
	start the resulting script as a superuser.  If you give neither
	option, the entire script must be run as superuser.
       </para>

       <para>
        This option is only meaningful for the plain-text format.  For
        the other formats, you may specify the option when you
        call <command>pg_restore</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-Z <replaceable class="parameter">0..9</replaceable></option></term>
      <term><option>--compress=<replaceable class="parameter">0..9</replaceable></option></term>
      <listitem>
       <para>
	Specify the compression level to use in archive formats that support 
      compression (currently only the custom archive format supports compression).
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

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

    <variablelist>
     <varlistentry>
      <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
      <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
      <listitem>
       <para>
	Specifies the host name of the machine on which the 
	server
	is running.  If host begins with a slash, it is used 
	as the directory for the Unix domain socket.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
      <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
      <listitem>
       <para>
	Specifies the Internet TCP/IP port or local Unix domain socket file 
	extension on which the server
	is listening for connections.  The port number defaults to 5432,
	or the value of the <envar>PGPORT</envar>
	environment variable (if set).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-U <replaceable>username</replaceable></option></term>
      <listitem>
       <para>
        Connect as the given user
       </para>
      </listitem>
     </varlistentry>

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

 <refsect1>
  <title>Environment</title>

  <variablelist>
   <varlistentry>
    <term><envar>PGDATABASE</envar></term>
    <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-pgdump-diagnostics">
  <title>Diagnostics</title>

  <msgset>
   <msgentry>
    <msg>
     <msgmain>
      <msgtext>
<screen>
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'?
</screen>
      </msgtext>
     </msgmain> 
    </msg>

    <msgexplan>
       <para>
	<application>pg_dump</application> could not attach to the 
	PostgreSQL server on the specified host and port.  If you see this message,
	ensure that the server
	is running on the proper host and that you have specified the proper
	port.
       </para>
    </msgexplan>
   </msgentry>

  </msgset>

   <note>
    <para>
     <application>pg_dump</application> internally executes
     <command>SELECT</command> statements. If you have problems running
     <application>pg_dump</application>,
     make sure you are able to select information from the database using, for
     example, <xref linkend="app-psql">.
    </para>
   </note>
 </refsect1>


 <refsect1 id="pg-dump-notes">
  <title>Notes</title>

  <para>
   If your installation has any local additions to the template1 database,
   be careful to restore the output of <application>pg_dump</application> into a
   truly empty database; otherwise you are likely to get errors due to
   duplicate definitions of the added objects.  To make an empty database
   without any local additions, copy from template0 not template1,
   for example:
<programlisting>
CREATE DATABASE foo WITH TEMPLATE template0;
</programlisting>
  </para>

  <para>
   <application>pg_dump</application> has a few limitations:

   <itemizedlist>
    <listitem>
     <para>
      When dumping a single table or as plain text, <application>pg_dump</application> 
      does not handle large objects. Large objects must be dumped in their
      entirety using one of the binary archive formats.
     </para>
    </listitem>

    <listitem>
     <para>
      When doing a data only dump, <application>pg_dump</application> emits queries
      to disable triggers on user tables before inserting the data and queries to
      re-enable them after the data has been inserted.  If the restore is stopped
      in the middle, the system catalogs may be left in the wrong state.
     </para>
    </listitem>

   </itemizedlist>
  </para>

  <para>
   Members of tar archives are limited to a size less than 8 GB.
   (This is an inherent limitation of the tar file format.)  Therefore
   this format cannot be used if the textual representation of a table
   exceeds that size.  The total size of a tar archive and any of the
   other output formats is not limited, except possibly by the
   operating system.
  </para>
 </refsect1>

 <refsect1 id="pg-dump-examples">
  <title>Examples</title>

  <para>
   To dump a database:
<screen>
<prompt>$</prompt> <userinput>pg_dump mydb &gt; db.out</userinput>
</screen>
  </para>

  <para>
   To reload this database:
<screen>
<prompt>$</prompt> <userinput>psql -d database -f db.out</userinput>
</screen>
  </para>

  <para>
   To dump a database called <literal>mydb</> that contains
   large objects to a <filename>tar</filename> file:

<screen>
<prompt>$</prompt> <userinput>pg_dump -Ft -b mydb &gt; db.tar</userinput>
</screen>
  </para>

  <para>
   To reload this database (with large objects) to an
   existing database called <literal>newdb</>:

<screen>
<prompt>$</prompt> <userinput>pg_restore -d newdb db.tar</userinput>
</screen>
  </para>

 </refsect1>

 <refsect1>
  <title>History</title>

  <para>
   The <application>pg_dump</application> utility first appeared in
   <application>Postgres95</application> release <literal>0.02</literal>.  The
   non-plain-text output formats were introduced in
   <application>PostgreSQL</application> release <literal>7.1</literal>.
  </para>
 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="app-pg-dumpall"></member>
   <member><xref linkend="app-pgrestore"></member>
   <member><xref linkend="app-psql"></member>
   <member>&cite-admin;</member>
  </simplelist>
 </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:
-->