591 lines
16 KiB
Plaintext
591 lines
16 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.29 2001/03/06 05:22:18 pjw Exp $
|
|
Postgres documentation
|
|
-->
|
|
|
|
<refentry id="APP-PGDUMP">
|
|
<docinfo>
|
|
<date>2000-12-25</date>
|
|
</docinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle id="app-pgdump-title">
|
|
<application>pg_dump</application>
|
|
</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
</refmeta>
|
|
<refnamediv>
|
|
<refname>
|
|
<application>pg_dump</application>
|
|
</refname>
|
|
<refpurpose>
|
|
Extract a <productname>Postgres</productname> database into a script file or other archive file
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv>
|
|
<refsynopsisdivinfo>
|
|
<date>2000-11-22</date>
|
|
</refsynopsisdivinfo>
|
|
<synopsis>
|
|
pg_dump [ <replaceable class="parameter">dbname</replaceable> ]
|
|
pg_dump [ -h <replaceable class="parameter">host</replaceable> ]
|
|
[ -p <replaceable class="parameter">port</replaceable> ]
|
|
[ -t <replaceable class="parameter">table</replaceable> ]
|
|
[ -a ] [ -b ] [ -c ] [-C] [ -d ] [ -D ]
|
|
[-f <REPLACEABLE CLASS="PARAMETER">file</REPLACEABLE>]
|
|
[-F <REPLACEABLE CLASS="PARAMETER">format</REPLACEABLE>]
|
|
[ -i ] [ -n ] [ -N ] [ -o ] [ -O ] [-R]
|
|
[ -s ] [ -S ] [ -u ] [ -v ] [ -x ] [ -Z 0..9 ]
|
|
[ <replaceable class="parameter">dbname</replaceable> ]
|
|
</synopsis>
|
|
|
|
<refsect2 id="R2-APP-PG-DUMP-1">
|
|
<refsect2info>
|
|
<date>2000-11-22</date>
|
|
</refsect2info>
|
|
<title>
|
|
Inputs
|
|
</title>
|
|
<para>
|
|
<application>pg_dump</application> accepts the following command
|
|
line arguments:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">dbname</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the name of the database to be extracted.
|
|
<replaceable class="parameter">dbname</replaceable>
|
|
defaults to the value of the
|
|
<envar>USER</envar>
|
|
environment variable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-a</term>
|
|
<listitem>
|
|
<para>
|
|
Dump out only the data, no schema (definitions).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-b</term>
|
|
<listitem>
|
|
<para>
|
|
Dump data and BLOB data.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-c</term>
|
|
<listitem>
|
|
<para>
|
|
Clean (drop) schema prior to create.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-C</term>
|
|
<listitem>
|
|
<para>
|
|
For plain text (script) output, include SQL to create the database itself.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-d</term>
|
|
<listitem>
|
|
<para>
|
|
Dump data as proper insert strings. This is not recommended for large databases
|
|
for performance reasons.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-D</term>
|
|
<listitem>
|
|
<para>
|
|
Dump data as inserts with attribute names. This is not recommended for large databases
|
|
for performance reasons.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-f <replaceable class="parameter">file</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Send output to the specified file.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-F <replaceable class="parameter">format</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Format can be one of the following:
|
|
</para>
|
|
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>p</term>
|
|
<listitem>
|
|
<para>
|
|
output a plain text SQL script file (default)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>t</term>
|
|
<listitem>
|
|
<para>
|
|
output a TAR 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>
|
|
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-i</term>
|
|
<listitem>
|
|
<para>
|
|
Ignore version mismatch between <application>pg_dump</application>
|
|
and the database server. Since <application>pg_dump</application>
|
|
knows a great deal about system catalogs, any given version of
|
|
<application>pg_dump</application> is only intended to work with
|
|
the corresponding release of the database server. 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>-n</term>
|
|
<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.
|
|
This was the default behavior for
|
|
<application>pg_dump</application> prior to v6.4.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-N</term>
|
|
<listitem>
|
|
<para>
|
|
Include double quotes around identifiers.
|
|
This is the default.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-o</term>
|
|
<listitem>
|
|
<para>
|
|
Dump object identifiers (<acronym>OID</acronym>s) for every table.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-O</term>
|
|
<listitem>
|
|
<para>
|
|
In plain text output mode, don't set object ownership to match the
|
|
original database. Typically, <APPLICATION>pg_dump</APPLICATION>
|
|
issues <PROGRAMLISTING>\connect</PROGRAMLISTING> statments to set
|
|
ownership of schema elements.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-R</term>
|
|
<listitem>
|
|
<para>
|
|
In plain text output mode, prohibit <APPLICATION>pg_dump</APPLICATION>
|
|
from issuing any <PROGRAMLISTING>\connect</PROGRAMLISTING> statements.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-s</term>
|
|
<listitem>
|
|
<para>
|
|
Dump out only the schema (definitions), no data.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-S <replaceable class="parameter">username</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specify the superuser username to use when disabling triggers and/or
|
|
setting ownership of schema elements.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-t <replaceable class="parameter">table</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Dump data for <replaceable class="parameter">table</replaceable> only.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-u</term>
|
|
<listitem>
|
|
<para>
|
|
Use password authentication. Prompts for username and password.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-v</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies verbose mode.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-x</term>
|
|
<listitem>
|
|
<para>
|
|
Prevent dumping of ACLs (grant/revoke commands) and table ownership information.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-Z <replaceable class="parameter">0..9</replaceable></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>
|
|
<application>pg_dump</application> also accepts
|
|
the following command line arguments for connection parameters:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>-h <replaceable class="parameter">host</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the hostname of the machine on which the
|
|
<application>postmaster</application>
|
|
is running. If host begins with a slash, it is used
|
|
as the directory for the unix domain socket.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-p <replaceable class="parameter">port</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the Internet TCP/IP port or local Unix domain socket file
|
|
extension on which the <application>postmaster</application>
|
|
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>-u</term>
|
|
<listitem>
|
|
<para>
|
|
Use password authentication.
|
|
Prompts for
|
|
<replaceable class="parameter">username</replaceable>
|
|
and <replaceable class="parameter">password</replaceable>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2 id="R2-APP-PG-DUMP-2">
|
|
<refsect2info>
|
|
<date>1998-11-05</date>
|
|
</refsect2info>
|
|
<title>
|
|
Outputs
|
|
</title>
|
|
<para>
|
|
<application>pg_dump</application> will create a file or
|
|
write to <filename>stdout</filename>.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><computeroutput>
|
|
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'?
|
|
</computeroutput></term>
|
|
<listitem>
|
|
<para>
|
|
<application>pg_dump</application> could not attach to the
|
|
<application>postmaster</application>
|
|
process on the specified host and port. If you see this message,
|
|
ensure that the <application>postmaster</application>
|
|
is running on the proper host and that you have specified the proper
|
|
port. If your site uses an authentication system, ensure that you
|
|
have obtained the required authentication credentials.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><computeroutput>
|
|
Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
|
|
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
|
|
</computeroutput></term>
|
|
<listitem>
|
|
<para>
|
|
You do not have a valid entry in the relation <literal>pg_shadow</literal>
|
|
and and will not be allowed to access <productname>Postgres</productname>.
|
|
Contact your <productname>Postgres</productname> administrator.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><computeroutput>
|
|
dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
|
|
</computeroutput></term>
|
|
<listitem>
|
|
<para>
|
|
You do not have permission to read the database.
|
|
Contact your <productname>Postgres</productname> site administrator.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<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, <application>psql</application>.
|
|
</para>
|
|
</note>
|
|
</refsect2>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="R1-APP-PG-DUMP-1">
|
|
<refsect1info>
|
|
<date>2000-</date>
|
|
</refsect1info>
|
|
<title>
|
|
Description
|
|
</title>
|
|
<para>
|
|
<application>pg_dump</application> is a utility for dumping out a
|
|
<productname>Postgres</productname> database into a script or archive
|
|
file containing query commands. The script files are in text format
|
|
and can be used to reconstruct the database, even on other machines
|
|
and other architectures.
|
|
</para>
|
|
<para>
|
|
The archive files, new with version 7.1, contain enough information for
|
|
<APPLICATION>pg_restore</APPLICATION> to rebuild the database, but also
|
|
allow pg_restore to be selective about what is restored, or even to
|
|
reorder the items prior to being restored. The archive files should
|
|
also be portable across architectures.
|
|
</para>
|
|
<para>
|
|
<application>pg_dump</application>
|
|
will produce the queries necessary to re-generate all
|
|
user-defined types, functions, tables, indices, 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>
|
|
<application>pg_dump</application>
|
|
is useful for dumping out the contents of a database to move from one
|
|
<productname>Postgres</productname> installation to another. After running
|
|
<application>pg_dump</application>,
|
|
one should examine the output for any warnings, especially
|
|
in light of the limitations listed below.
|
|
</para>
|
|
|
|
<para>
|
|
When used with one of the alternate file formats and combined with
|
|
<APPLICATION>pg_restore</APPLICATION>, it provides a flexible archival
|
|
and trasfer 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.
|
|
</para>
|
|
|
|
<para>
|
|
See the <APPLICATION>pg_restore</APPLICATION> documentation for details.
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1 id="R1-APP-PG-DUMP-2">
|
|
<refsect1info>
|
|
<date>2000-11-21</date>
|
|
</refsect1info>
|
|
<title>
|
|
Notes
|
|
</title>
|
|
<para>
|
|
<application>pg_dump</application> has a few limitations.
|
|
The limitations mostly stem from
|
|
difficulty in extracting certain meta-information from the system
|
|
catalogs.
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<application>pg_dump</application>
|
|
does not understand partial indices. The reason is
|
|
the same as above; partial index predicates are stored as plans.
|
|
</para>
|
|
</listitem>
|
|
|
|
<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
|
|
entirity 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>
|
|
</refsect1>
|
|
|
|
<refsect1 id="R1-APP-PG-DUMP-3">
|
|
<refsect1info>
|
|
<date>2000-11-21</date>
|
|
</refsect1info>
|
|
<title>
|
|
Usage
|
|
</title>
|
|
<para>
|
|
To dump a database of the same name as the user:
|
|
|
|
<programlisting>
|
|
$ pg_dump > db.out
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
To reload this database:
|
|
|
|
<programlisting>
|
|
$ psql -e database < db.out
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
To dump a database called mydb that contains BLOBs to a TAR file:
|
|
|
|
<programlisting>
|
|
$ pg_dump -Ft --blobs mydb > db.tar
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
To reload this database (with BLOBs) to an existing db called newdb:
|
|
|
|
<programlisting>
|
|
$ pg_restore db.tar --dbname=newdb
|
|
</programlisting>
|
|
</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:
|
|
-->
|