1999-07-22 17:09:15 +02:00
|
|
|
<!--
|
2002-07-28 17:22:21 +02:00
|
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.46 2002/07/28 15:22:20 petere Exp $
|
2001-12-08 04:24:40 +01:00
|
|
|
PostgreSQL documentation
|
1999-07-22 17:09:15 +02:00
|
|
|
-->
|
|
|
|
|
|
|
|
<refentry id="APP-PGDUMP">
|
1999-07-06 19:16:42 +02:00
|
|
|
<refmeta>
|
2002-04-21 21:02:39 +02:00
|
|
|
<refentrytitle>pg_dump</refentrytitle>
|
2000-12-26 00:15:27 +01:00
|
|
|
<manvolnum>1</manvolnum>
|
1999-07-06 19:16:42 +02:00
|
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
|
|
</refmeta>
|
2001-03-06 19:55:57 +01:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refnamediv>
|
2001-03-06 19:55:57 +01:00
|
|
|
<refname>pg_dump</refname>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refpurpose>
|
2001-09-03 14:57:50 +02:00
|
|
|
extract a <productname>PostgreSQL</productname> database into a script file or other archive file
|
1999-07-06 19:16:42 +02:00
|
|
|
</refpurpose>
|
|
|
|
</refnamediv>
|
2001-03-06 19:55:57 +01:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refsynopsisdiv>
|
2001-03-06 19:55:57 +01:00
|
|
|
<cmdsynopsis>
|
|
|
|
<command>pg_dump</command>
|
|
|
|
<group> <arg>-a</arg> <arg>-s</arg> </group>
|
|
|
|
<arg>-b</arg>
|
|
|
|
<arg>-c</arg>
|
|
|
|
<arg>-C</arg>
|
|
|
|
<group> <arg>-d</arg> <arg>-D</arg> </group>
|
|
|
|
<arg>-f <replaceable>file</replaceable></arg>
|
|
|
|
<arg>-F <replaceable>format</replaceable></arg>
|
|
|
|
<arg>-i</arg>
|
|
|
|
<group> <arg>-n</arg> <arg>-N</arg> </group>
|
|
|
|
<arg>-o</arg>
|
|
|
|
<arg>-O</arg>
|
|
|
|
<arg>-R</arg>
|
|
|
|
<arg>-S</arg>
|
|
|
|
<arg>-t <replaceable>table</replaceable></arg>
|
|
|
|
<arg>-v</arg>
|
|
|
|
<arg>-x</arg>
|
2001-08-22 22:23:24 +02:00
|
|
|
<arg>-X <replaceable>keyword</replaceable></arg>
|
2001-03-06 19:55:57 +01:00
|
|
|
<arg>-Z <replaceable>0...9</replaceable></arg>
|
|
|
|
<arg>-h <replaceable>host</replaceable></arg>
|
|
|
|
<arg>-p <replaceable>port</replaceable></arg>
|
2001-05-17 23:12:49 +02:00
|
|
|
<arg>-U <replaceable>username</replaceable></arg>
|
|
|
|
<arg>-W</arg>
|
2001-03-06 19:55:57 +01:00
|
|
|
<arg choice="plain"><replaceable>dbname</replaceable></arg>
|
|
|
|
</cmdsynopsis>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
|
|
|
|
<refsect1 id="pg-dump-description">
|
|
|
|
<title>
|
|
|
|
Description
|
|
|
|
</title>
|
|
|
|
|
|
|
|
<para>
|
2001-08-22 22:23:24 +02:00
|
|
|
<command>pg_dump</command> is a utility for saving a
|
|
|
|
<productname>PostgreSQL</productname> database into a script or an
|
2001-11-28 21:49:10 +01:00
|
|
|
archive file. The script files are in plain-text format and
|
2001-08-22 22:23:24 +02:00
|
|
|
contain the SQL commands required to reconstruct the database to
|
2001-10-24 00:11:22 +02:00
|
|
|
the state it was in at the time it was saved. They can be used to
|
2001-08-22 22:23:24 +02:00
|
|
|
reconstruct the database even on other machines and other
|
|
|
|
architectures, with some modifications even on other RDBMS
|
2001-11-28 21:49:10 +01:00
|
|
|
products. Furthermore, there are alternative archive file formats that
|
|
|
|
are meant to be
|
2001-08-22 22:23:24 +02:00
|
|
|
used with <xref linkend="app-pgrestore"> to rebuild the database,
|
|
|
|
and they also allow <command>pg_restore</command> 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.
|
2001-03-06 19:55:57 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2001-08-22 22:23:24 +02:00
|
|
|
<command>pg_dump</command> 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.
|
2001-03-06 19:55:57 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<command>pg_dump</command>
|
|
|
|
is useful for dumping out the contents of a database to move from one
|
2001-11-28 21:49:10 +01:00
|
|
|
<productname>PostgreSQL</productname> installation to another.
|
2001-03-06 19:55:57 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2001-08-22 22:23:24 +02:00
|
|
|
When used with one of the archive file formats and combined with
|
2001-10-24 00:11:22 +02:00
|
|
|
<xref linkend="app-pgrestore">, <command>pg_dump</command> provides a
|
|
|
|
flexible archival and
|
2001-08-22 22:23:24 +02:00
|
|
|
transfer mechanism. <command>pg_dump</command> can be used to
|
|
|
|
backup an entire database, then <command>pg_restore</command> can
|
|
|
|
be used to examine the archive and/or select which parts of the
|
2001-10-24 00:11:22 +02:00
|
|
|
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>.
|
2001-08-22 22:23:24 +02:00
|
|
|
</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>
|
|
|
|
<command>pg_dump</command> makes consistent backups even if the
|
|
|
|
database is being used concurrently. <command>pg_dump</command>
|
|
|
|
does not block other users accessing the database (readers or
|
|
|
|
writers).
|
2001-03-06 19:55:57 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<refsect2 id="pg-dump-options">
|
|
|
|
<title>Options</title>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<para>
|
2001-03-06 19:55:57 +01:00
|
|
|
<command>pg_dump</command> accepts the following command
|
|
|
|
line arguments. (Long option forms are only available on some platforms.)
|
1999-07-06 19:16:42 +02:00
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">dbname</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-10-24 00:11:22 +02:00
|
|
|
Specifies the name of the database to be dumped.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-a</></term>
|
|
|
|
<term><option>--data-only</></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-08-12 21:02:39 +02:00
|
|
|
Dump only the data, not the schema (data definitions).
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
2001-10-24 00:11:22 +02:00
|
|
|
|
|
|
|
<para>
|
2001-11-28 21:49:10 +01:00
|
|
|
This option is only meaningful for the plain-text format. For
|
2001-10-24 00:11:22 +02:00
|
|
|
the other formats, you may specify the option when you
|
|
|
|
call <command>pg_restore</command>.
|
|
|
|
</para>
|
1999-07-06 19:16:42 +02:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2001-03-05 19:42:57 +01:00
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-b</></term>
|
|
|
|
<term><option>--blobs</></term>
|
2001-03-05 19:42:57 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-09-21 23:58:30 +02:00
|
|
|
Include large objects in dump.
|
2001-03-05 19:42:57 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-c</option></term>
|
|
|
|
<term><option>--clean</option></term>
|
2001-03-05 19:42:57 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-10-24 00:11:22 +02:00
|
|
|
Output commands to clean (drop)
|
|
|
|
database objects prior to (the commands for) creating them.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2001-11-28 21:49:10 +01:00
|
|
|
This option is only meaningful for the plain-text format. For
|
2001-10-24 00:11:22 +02:00
|
|
|
the other formats, you may specify the option when you
|
|
|
|
call <command>pg_restore</command>.
|
2001-03-05 19:42:57 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-C</></term>
|
|
|
|
<term><option>--create</></term>
|
2001-03-05 19:42:57 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-10-24 00:11:22 +02:00
|
|
|
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>
|
2001-11-28 21:49:10 +01:00
|
|
|
This option is only meaningful for the plain-text format. For
|
2001-10-24 00:11:22 +02:00
|
|
|
the other formats, you may specify the option when you
|
|
|
|
call <command>pg_restore</command>.
|
2001-03-05 19:42:57 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-d</option></term>
|
|
|
|
<term><option>--inserts</option></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-10-24 00:11:22 +02:00
|
|
|
Dump data as <command>INSERT</command> commands (rather
|
2001-08-22 22:23:24 +02:00
|
|
|
than <command>COPY</command>). This will make restoration very
|
|
|
|
slow, but it makes the archives more portable to other RDBMS
|
|
|
|
packages.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-D</option></term>
|
|
|
|
<term><option>--column-inserts</option></term>
|
|
|
|
<term><option>--attribute-inserts</option></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-03-06 19:55:57 +01:00
|
|
|
Dump data as <command>INSERT</command> commands with explicit
|
2001-08-12 21:02:39 +02:00
|
|
|
column names (<literal>INSERT INTO
|
|
|
|
<replaceable>table</replaceable>
|
|
|
|
(<replaceable>column</replaceable>, ...) VALUES
|
2001-10-24 00:11:22 +02:00
|
|
|
...</literal>). This will make restoration very slow,
|
|
|
|
but it is necessary if you desire to rearrange column ordering.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2001-03-05 19:42:57 +01:00
|
|
|
|
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-f <replaceable class="parameter">file</replaceable></option></term>
|
|
|
|
<term><option>--file=<replaceable class="parameter">file</replaceable></option></term>
|
2001-03-05 19:42:57 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-08-22 22:23:24 +02:00
|
|
|
Send output to the specified file. If this is omitted, the
|
|
|
|
standard output is used.
|
2001-03-05 19:42:57 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-F <replaceable class="parameter">format</replaceable></option></term>
|
|
|
|
<term><option>--format=<replaceable class="parameter">format</replaceable></option></term>
|
2001-03-05 19:42:57 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-08-22 22:23:24 +02:00
|
|
|
Selects the format of the output.
|
|
|
|
<replaceable>format</replaceable> can be one of the following:
|
2001-03-05 19:42:57 +01:00
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term>p</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-11-28 21:49:10 +01:00
|
|
|
Output a plain-text <acronym>SQL</acronym> script file (default)
|
2001-03-05 19:42:57 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>t</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-11-28 21:49:10 +01:00
|
|
|
Output a <filename>tar</filename> archive suitable for input into
|
2001-03-06 19:55:57 +01:00
|
|
|
<command>pg_restore</command>. Using this archive format
|
2001-03-05 19:42:57 +01:00
|
|
|
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>
|
2001-11-28 21:49:10 +01:00
|
|
|
Output a custom archive suitable for input into
|
2001-03-06 19:55:57 +01:00
|
|
|
<command>pg_restore</command>. This is the most flexible
|
2001-03-05 19:42:57 +01:00
|
|
|
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>
|
2001-03-06 19:55:57 +01:00
|
|
|
</para>
|
2001-03-05 19:42:57 +01:00
|
|
|
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
2000-04-04 07:22:46 +02:00
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-i</></term>
|
|
|
|
<term><option>--ignore-version</></term>
|
2000-04-04 07:22:46 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-03-06 19:55:57 +01:00
|
|
|
Ignore version mismatch between <command>pg_dump</command>
|
|
|
|
and the database server. Since <command>pg_dump</command>
|
2000-04-04 07:22:46 +02:00
|
|
|
knows a great deal about system catalogs, any given version of
|
2001-03-06 19:55:57 +01:00
|
|
|
<command>pg_dump</command> is only intended to work with
|
2000-04-04 07:22:46 +02:00
|
|
|
the corresponding release of the database server. Use this option
|
|
|
|
if you need to override the version check (and if
|
2001-03-06 19:55:57 +01:00
|
|
|
<command>pg_dump</command> then fails, don't
|
2000-04-04 07:22:46 +02:00
|
|
|
say you weren't warned).
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-n</></term>
|
|
|
|
<term><option>--no-quotes</></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Suppress double quotes around identifiers unless absolutely necessary.
|
|
|
|
This may cause trouble loading this dumped data if there are reserved words
|
|
|
|
used for identifiers.
|
2000-03-27 19:14:43 +02:00
|
|
|
This was the default behavior for
|
2001-03-06 19:55:57 +01:00
|
|
|
<command>pg_dump</command> prior to version 6.4.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-N</></term>
|
|
|
|
<term><option>--quotes</></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Include double quotes around identifiers.
|
|
|
|
This is the default.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2001-03-05 19:42:57 +01:00
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-o</></term>
|
|
|
|
<term><option>--oids</></term>
|
2001-03-05 19:42:57 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-08-22 22:23:24 +02:00
|
|
|
Dump object identifiers (<acronym>OID</acronym>s) for every
|
2001-10-24 00:11:22 +02:00
|
|
|
table. Use this option if your application references the OID
|
2001-08-22 22:23:24 +02:00
|
|
|
columns in some way (e.g., in a foreign key constraint).
|
|
|
|
Otherwise, this option should not be used.
|
2001-03-05 19:42:57 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-O</></term>
|
|
|
|
<term><option>--no-owner</option></term>
|
2001-03-05 19:42:57 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-10-24 00:11:22 +02:00
|
|
|
Do not output commands to set the
|
2001-08-22 22:23:24 +02:00
|
|
|
object ownership to match the original database. Typically,
|
|
|
|
<command>pg_dump</command> issues
|
|
|
|
(<command>psql</command>-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>
|
2001-11-28 21:49:10 +01:00
|
|
|
This option is only meaningful for the plain-text format. For
|
2001-10-24 00:11:22 +02:00
|
|
|
the other formats, you may specify the option when you
|
2001-08-22 22:23:24 +02:00
|
|
|
call <command>pg_restore</command>.
|
2001-03-05 19:42:57 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-R</option></term>
|
|
|
|
<term><option>--no-reconnect</option></term>
|
2001-03-05 19:42:57 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-10-24 00:11:22 +02:00
|
|
|
Prohibit <command>pg_dump</command>
|
2001-08-22 22:23:24 +02:00
|
|
|
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
|
|
|
|
<command>pg_dump</command> 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>
|
2001-11-28 21:49:10 +01:00
|
|
|
This option is only meaningful for the plain-text format. For
|
2001-10-24 00:11:22 +02:00
|
|
|
the other formats, you may specify the option when you
|
2001-08-22 22:23:24 +02:00
|
|
|
call <command>pg_restore</command>.
|
2001-03-05 19:42:57 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-s</option></term>
|
|
|
|
<term><option>--schema-only</option></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-08-12 21:02:39 +02:00
|
|
|
Dump only the schema (data definitions), no data.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2001-03-05 19:42:57 +01:00
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-S <replaceable class="parameter">username</replaceable></option></term>
|
|
|
|
<term><option>--superuser=<replaceable class="parameter">username</replaceable></option></term>
|
2001-03-05 19:42:57 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2002-05-11 00:36:27 +02:00
|
|
|
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.)
|
2001-03-05 19:42:57 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-t <replaceable class="parameter">table</replaceable></option></term>
|
|
|
|
<term><option>--table=<replaceable class="parameter">table</replaceable></option></term>
|
2001-03-05 19:42:57 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Dump data for <replaceable class="parameter">table</replaceable> only.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-v</></term>
|
|
|
|
<term><option>--verbose</></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2000-10-05 21:48:34 +02:00
|
|
|
Specifies verbose mode.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-x</></term>
|
|
|
|
<term><option>--no-privileges</></term>
|
|
|
|
<term><option>--no-acl</></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-08-22 22:23:24 +02:00
|
|
|
Prevent dumping of access privileges (grant/revoke commands).
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-X use-set-session-authorization</></term>
|
|
|
|
<term><option>--use-set-session-authorization</></term>
|
2001-08-22 22:23:24 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-11-28 21:49:10 +01:00
|
|
|
Normally, if a (plain-text mode) script generated by
|
2001-08-22 22:23:24 +02:00
|
|
|
<command>pg_dump</command> must alter the current database
|
|
|
|
user (e.g., to set correct object ownerships), it uses the
|
|
|
|
<xref linkend="app-psql"> <command>\connect</command> command.
|
|
|
|
This command actually opens a new connection, which might
|
|
|
|
require manual interaction (e.g., passwords). If you use the
|
2001-11-18 21:35:02 +01:00
|
|
|
<option>-X use-set-session-authorization</option> option, then
|
2001-08-22 22:23:24 +02:00
|
|
|
<command>pg_dump</command> will instead output <xref
|
2001-11-18 21:35:02 +01:00
|
|
|
linkend="sql-set-session-authorization" endterm="sql-set-session-authorization-title"> commands. This has
|
2001-08-22 22:23:24 +02:00
|
|
|
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>
|
2001-11-18 21:35:02 +01:00
|
|
|
Since <xref linkend="sql-set-session-authorization" endterm="sql-set-session-authorization-title"> is a
|
2001-08-22 22:23:24 +02:00
|
|
|
standard SQL command, whereas <command>\connect</command> only
|
|
|
|
works in <xref linkend="app-psql">, this option also enhances
|
|
|
|
the theoretical portability of the output script.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2001-11-28 21:49:10 +01:00
|
|
|
This option is only meaningful for the plain-text format. For
|
2001-10-24 00:11:22 +02:00
|
|
|
the other formats, you may specify the option when you
|
2001-08-22 22:23:24 +02:00
|
|
|
call <command>pg_restore</command>.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2001-03-05 19:42:57 +01:00
|
|
|
|
2002-05-11 00:36:27 +02:00
|
|
|
<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 <command>pg_dump</command> 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>
|
|
|
|
|
2001-03-05 19:42:57 +01:00
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-Z <replaceable class="parameter">0..9</replaceable></option></term>
|
|
|
|
<term><option>--compress=<replaceable class="parameter">0..9</replaceable></option></term>
|
2001-03-05 19:42:57 +01:00
|
|
|
<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>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
|
|
|
|
</variablelist>
|
|
|
|
</para>
|
|
|
|
<para>
|
2001-03-06 19:55:57 +01:00
|
|
|
<command>pg_dump</command> also accepts
|
1999-07-06 19:16:42 +02:00
|
|
|
the following command line arguments for connection parameters:
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-h <replaceable class="parameter">host</replaceable></option></term>
|
|
|
|
<term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-03-06 19:55:57 +01:00
|
|
|
Specifies the host name of the machine on which the
|
2001-11-28 21:49:10 +01:00
|
|
|
server
|
2000-11-14 00:57:20 +01:00
|
|
|
is running. If host begins with a slash, it is used
|
2001-03-06 19:55:57 +01:00
|
|
|
as the directory for the Unix domain socket.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-p <replaceable class="parameter">port</replaceable></option></term>
|
|
|
|
<term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Specifies the Internet TCP/IP port or local Unix domain socket file
|
2001-11-28 21:49:10 +01:00
|
|
|
extension on which the server
|
1999-07-06 19:16:42 +02:00
|
|
|
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>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-U <replaceable>username</replaceable></option></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-05-17 23:12:49 +02:00
|
|
|
Connect as the given user.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2002-03-22 20:20:45 +01:00
|
|
|
<term><option>-W</option></term>
|
2001-05-17 23:12:49 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Force a password prompt. This should happen automatically if
|
|
|
|
the server requires password authentication.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</para>
|
|
|
|
</refsect2>
|
|
|
|
|
2001-03-06 19:55:57 +01:00
|
|
|
</refsect1>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
2002-07-28 17:22:21 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Environment</title>
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term><envar>PGDATABASE</envar></term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Database to dump, unless overridden on the command line.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
2001-03-06 19:55:57 +01:00
|
|
|
<refsect1 id="app-pgdump-diagnostics">
|
|
|
|
<title>Diagnostics</title>
|
|
|
|
|
|
|
|
<msgset>
|
|
|
|
<msgentry>
|
|
|
|
<msg>
|
|
|
|
<msgmain>
|
|
|
|
<msgtext>
|
|
|
|
<screen><computeroutput>
|
1999-07-06 19:16:42 +02:00
|
|
|
Connection to database 'template1' failed.
|
2000-12-01 00:20:51 +01:00
|
|
|
connectDBStart() -- connect() failed: No such file or directory
|
|
|
|
Is the postmaster running locally
|
|
|
|
and accepting connections on Unix socket '/tmp/.s.PGSQL.5432'?
|
2001-03-06 19:55:57 +01:00
|
|
|
</computeroutput></screen>
|
|
|
|
</msgtext>
|
|
|
|
</msgmain>
|
|
|
|
</msg>
|
|
|
|
|
|
|
|
<msgexplan>
|
1999-07-06 19:16:42 +02:00
|
|
|
<para>
|
2001-03-06 19:55:57 +01:00
|
|
|
<command>pg_dump</command> could not attach to the
|
|
|
|
<command>postmaster</command>
|
1999-07-06 19:16:42 +02:00
|
|
|
process on the specified host and port. If you see this message,
|
2001-03-06 19:55:57 +01:00
|
|
|
ensure that the <command>postmaster</command>
|
1999-07-06 19:16:42 +02:00
|
|
|
is running on the proper host and that you have specified the proper
|
2001-03-06 19:55:57 +01:00
|
|
|
port.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
2001-03-06 19:55:57 +01:00
|
|
|
</msgexplan>
|
|
|
|
</msgentry>
|
|
|
|
|
|
|
|
</msgset>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
|
|
|
<note>
|
1998-12-29 03:24:47 +01:00
|
|
|
<para>
|
2001-03-06 19:55:57 +01:00
|
|
|
<command>pg_dump</command> internally executes
|
1999-07-06 19:16:42 +02:00
|
|
|
<command>SELECT</command> statements. If you have problems running
|
2001-03-06 19:55:57 +01:00
|
|
|
<command>pg_dump</command>,
|
1999-07-06 19:16:42 +02:00
|
|
|
make sure you are able to select information from the database using, for
|
2001-03-06 19:55:57 +01:00
|
|
|
example, <xref linkend="app-psql">.
|
1998-12-29 03:24:47 +01:00
|
|
|
</para>
|
1999-07-06 19:16:42 +02:00
|
|
|
</note>
|
|
|
|
</refsect1>
|
|
|
|
|
2001-03-06 19:55:57 +01:00
|
|
|
|
|
|
|
<refsect1 id="pg-dump-notes">
|
|
|
|
<title>Notes</title>
|
2002-02-11 01:14:10 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
If your installation has any local additions to the template1 database,
|
|
|
|
be careful to restore the output of <command>pg_dump</command> 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>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<para>
|
2002-02-11 01:14:10 +01:00
|
|
|
<command>pg_dump</command> has a few limitations:
|
1999-07-06 19:16:42 +02:00
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-03-06 19:55:57 +01:00
|
|
|
When dumping a single table or as plain text, <command>pg_dump</command>
|
2001-03-05 19:42:57 +01:00
|
|
|
does not handle large objects. Large objects must be dumped in their
|
2001-03-06 19:55:57 +01:00
|
|
|
entirety using one of the binary archive formats.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2000-04-11 16:43:54 +02:00
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-03-06 19:55:57 +01:00
|
|
|
When doing a data only dump, <command>pg_dump</command> emits queries
|
2000-04-11 16:43:54 +02:00
|
|
|
to disable triggers on user tables before inserting the data and queries to
|
2000-07-22 06:45:10 +02:00
|
|
|
re-enable them after the data has been inserted. If the restore is stopped
|
2000-04-11 16:43:54 +02:00
|
|
|
in the middle, the system catalogs may be left in the wrong state.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
2001-03-06 19:55:57 +01:00
|
|
|
<refsect1 id="pg-dump-examples">
|
|
|
|
<title>Examples</title>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
2001-03-06 19:55:57 +01:00
|
|
|
<para>
|
|
|
|
To dump a database:
|
|
|
|
<screen>
|
|
|
|
<prompt>$</prompt> <userinput>pg_dump mydb > db.out</userinput>
|
|
|
|
</screen>
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To reload this database:
|
2001-03-06 19:55:57 +01:00
|
|
|
<screen>
|
|
|
|
<prompt>$</prompt> <userinput>psql -d database -f db.out</userinput>
|
|
|
|
</screen>
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
2001-03-05 19:42:57 +01:00
|
|
|
|
|
|
|
<para>
|
2001-09-21 23:58:30 +02:00
|
|
|
To dump a database called <literal>mydb</> that contains
|
|
|
|
large objects to a <filename>tar</filename> file:
|
2001-03-05 19:42:57 +01:00
|
|
|
|
2001-03-06 19:55:57 +01:00
|
|
|
<screen>
|
|
|
|
<prompt>$</prompt> <userinput>pg_dump -Ft -b mydb > db.tar</userinput>
|
|
|
|
</screen>
|
2001-03-05 19:42:57 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2001-09-21 23:58:30 +02:00
|
|
|
To reload this database (with large objects) to an
|
|
|
|
existing database called <literal>newdb</>:
|
2001-03-05 19:42:57 +01:00
|
|
|
|
2001-03-06 19:55:57 +01:00
|
|
|
<screen>
|
|
|
|
<prompt>$</prompt> <userinput>pg_restore -d newdb db.tar</userinput>
|
|
|
|
</screen>
|
2001-03-05 19:42:57 +01:00
|
|
|
</para>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
</refsect1>
|
2001-03-06 19:55:57 +01:00
|
|
|
|
2001-08-22 22:23:24 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>History</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The <command>pg_dump</command> utility first appeared in
|
2001-12-08 04:24:40 +01:00
|
|
|
<application>Postgres95</application> release <literal>0.02</literal>. The
|
2001-08-22 22:23:24 +02:00
|
|
|
non-plain-text output formats were introduced in
|
2001-12-08 04:24:40 +01:00
|
|
|
<application>PostgreSQL</application> release <literal>7.1</literal>.
|
2001-08-22 22:23:24 +02:00
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
2001-03-06 19:55:57 +01:00
|
|
|
<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><citetitle>PostgreSQL Administrator's Guide</citetitle></member>
|
|
|
|
</simplelist>
|
|
|
|
</refsect1>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
</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:
|
|
|
|
-->
|