<!--
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