<!--
doc/src/sgml/ref/pg_dump.sgml
PostgreSQL documentation
-->

<refentry id="app-pgdump">
 <indexterm zone="app-pgdump">
  <primary>pg_dump</primary>
 </indexterm>

 <refmeta>
  <refentrytitle><application>pg_dump</application></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>connection-option</replaceable></arg>
   <arg rep="repeat"><replaceable>option</replaceable></arg>
   <arg choice="opt"><replaceable>dbname</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>


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

  <para>
   <application>pg_dump</application> is a utility for exporting a
   <productname>PostgreSQL</productname> database. It makes consistent
   exports even if the database is being used concurrently.
   <application>pg_dump</application> does not block other users
   accessing the database (readers or writers).
   Note, however, that except in simple cases,
   <application>pg_dump</application> is generally not the right choice for
   taking regular backups of production databases.  See <xref
   linkend="backup"/> for further discussion.
  </para>

  <para>
   <application>pg_dump</application> only dumps a single database.
   To export an entire cluster, or to export global objects that are
   common to all databases in a cluster (such as roles and tablespaces),
   use <xref linkend="app-pg-dumpall"/>.
  </para>

  <para>
   Dumps can be output in script or archive file formats. Script
   dumps are plain-text files containing the SQL commands required
   to reconstruct the database to the state it was in at the time it was
   saved. To restore from such a script, feed it to <xref
   linkend="app-psql"/>. Script files
   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>
   The alternative archive file formats must be used with
   <xref linkend="app-pgrestore"/> to rebuild the database.  They
   allow <application>pg_restore</application> to be selective about
   what is restored, or even to reorder the items prior to being
   restored.
   The archive file formats are designed to be portable across
   architectures.
  </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
   export 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 formats are
   the <quote>custom</quote> format (<option>-Fc</option>) and the
   <quote>directory</quote> format (<option>-Fd</option>). They allow
   for selection and reordering of all archived items, support parallel
   restoration, and are compressed by default. The <quote>directory</quote>
   format is the only format that supports parallel dumps.
  </para>

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

 </refsect1>

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

  <para>
    The following command-line options control the content and
    format of the output.

    <variablelist>
     <varlistentry>
      <term><replaceable class="parameter">dbname</replaceable></term>
      <listitem>
       <para>
        Specifies the name of the database to be dumped.  If this is