pg_dump.1

PostgreSQL 8.2中增加了很多企业用户所需要的功能和性能上的提高,其开发团队说,该版本将加速更多企业向该数据库移植.核心开发成员之一Bruce Momjian表示,在新版PostgreSQL

.\\" auto-generated by docbook2man-spec $Revision: 1.1.1.1 $
.TH "PG_DUMP" "1" "2008-01-03" "Application" "PostgreSQL Client Applications"
.SH NAME
pg_dump \- extract a PostgreSQL database into a script file or other archive file

.SH SYNOPSIS
.sp
\fBpg_dump\fR [ \fB\fIoption\fB\fR\fI...\fR ]  [ \fB\fIdbname\fB\fR ] 
.SH "DESCRIPTION"
.PP
\fBpg_dump\fR is a utility for backing up a
PostgreSQL database. It makes consistent
backups even if the database is being used concurrently.
\fBpg_dump\fR does not block other users
accessing the database (readers or writers).
.PP
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 \fBpsql\fR(1). 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.
.PP
The alternative archive file formats must be used with
\fBpg_restore\fR(1) to rebuild the database. They
allow \fBpg_restore\fR 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.
.PP
When used with one of the archive file formats and combined with
\fBpg_restore\fR,
\fBpg_dump\fR provides a flexible archival and
transfer mechanism. \fBpg_dump\fR can be used to
backup an entire database, then \fBpg_restore\fR
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 ``custom'' format (\fB-Fc\fR). It allows
for selection and reordering of all archived items, and is compressed
by default. The \fBtar\fR format
(\fB-Ft\fR) 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 standard Unix tools such as
\fBtar\fR.
.PP
While running \fBpg_dump\fR, one should examine the
output for any warnings (printed on standard error), especially in
light of the limitations listed below.
.SH "OPTIONS"
.PP
The following command-line options control the content and
format of the output.
.TP
\fB\fIdbname\fB\fR
Specifies the name of the database to be dumped. If this is
not specified, the environment variable
\fBPGDATABASE\fR is used. If that is not set, the
user name specified for the connection is used.
.TP
\fB-a\fR
.TP
\fB--data-only\fR
Dump only the data, not the schema (data definitions).

This option is only meaningful for the plain-text format. For
the archive formats, you may specify the option when you
call \fBpg_restore\fR.
.TP
\fB-b\fR
.TP
\fB--blobs\fR
Include large objects in the dump. This is the default behavior
except when \fB--schema\fR, \fB--table\fR, or
\fB--schema-only\fR is specified, so the \fB-b\fR
switch is only useful to add large objects to selective dumps.
.TP
\fB-c\fR
.TP
\fB--clean\fR
Output commands to clean (drop)
database objects prior to (the commands for) creating them.

This option is only meaningful for the plain-text format. For
the archive formats, you may specify the option when you
call \fBpg_restore\fR.
.TP
\fB-C\fR
.TP
\fB--create\fR
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.)

This option is only meaningful for the plain-text format. For
the archive formats, you may specify the option when you
call \fBpg_restore\fR.
.TP
\fB-d\fR
.TP
\fB--inserts\fR
Dump data as \fBINSERT\fR commands (rather
than \fBCOPY\fR). This will make restoration very slow;
it is mainly useful for making dumps that can be loaded into
non-PostgreSQL databases.
Also, since this option generates a separate command for each row,
an error in reloading a row causes only that row to be lost rather
than the entire table contents.
Note that
the restore may fail altogether if you have rearranged column order.
The \fB-D\fR option is safe against column order changes,
though even slower.
.TP
\fB-D\fR
.TP
\fB--column-inserts\fR
.TP
\fB--attribute-inserts\fR
Dump data as \fBINSERT\fR commands with explicit
column names (INSERT INTO
\fItable\fR
(\fIcolumn\fR, ...) VALUES
\&...). This will make restoration very slow; it is mainly
useful for making dumps that can be loaded into
non-PostgreSQL databases.
Also, since this option generates a separate command for each row,
an error in reloading a row causes only that row to be lost rather
than the entire table contents.
.TP
\fB-E \fIencoding\fB\fR
.TP
\fB--encoding=\fIencoding\fB\fR
Create the dump in the specified character set encoding. By default,
the dump is created in the database encoding. (Another way to get the
same result is to set the \fBPGCLIENTENCODING\fR environment
variable to the desired dump encoding.)
.TP
\fB-f \fIfile\fB\fR
.TP
\fB--file=\fIfile\fB\fR
Send output to the specified file. If this is omitted, the
standard output is used.
.TP
\fB-F \fIformat\fB\fR
.TP
\fB--format=\fIformat\fB\fR
Selects the format of the output.
\fIformat\fR can be one of the following:
.RS
.TP
\fBp\fR
.TP
\fBplain\fR
Output a plain-text SQL script file (the default).
.TP
\fBc\fR
.TP
\fBcustom\fR
Output a custom archive suitable for input into
\fBpg_restore\fR. This is the most flexible
format in that it allows reordering of loading data as well
as object definitions. This format is also compressed by default.
.TP
\fBt\fR
.TP
\fBtar\fR
Output a \fBtar\fR archive suitable for input into
\fBpg_restore\fR. Using this archive format
allows reordering and/or exclusion of database objects
at the time the database is restored. It is also possible to limit
which data is reloaded at restore time.
.RE
.PP
.TP
\fB-i\fR
.TP
\fB--ignore-version\fR
Ignore version mismatch between
\fBpg_dump\fR and the database server.

\fBpg_dump\fR can dump from servers running
previous releases of PostgreSQL, but very old
versions are not supported anymore (currently, those prior to 7.0).
Dumping from a server newer than \fBpg_dump\fR
is likely not to work at all.
Use this option if you need to override the version check (and
if \fBpg_dump\fR then fails, don't say
you weren't warned).
.TP
\fB-n \fIschema\fB\fR
.TP
\fB--schema=\fIschema\fB\fR
Dump only schemas matching \fIschema\fR; this selects both the
schema itself, and all its contained objects. When this option is
not specified, all non-system schemas in the target database will be
dumped. Multiple schemas can be
selected by writing multiple \fB-n\fR switches. Also, the
\fIschema\fR parameter is
interpreted as a pattern according to the same rules used by
\fBpsql\fR's \\d commands (see Patterns [\fBpsql\fR(1)]),
so multiple schemas can also be selected by writing wildcard characters
in the pattern. When using wildcards, be careful to quote the pattern
if needed to prevent the shell from expanding the wildcards.
.sp
.RS
.B "Note:"
When \fB-n\fR is specified, \fBpg_dump\fR
makes no attempt to dump any other database objects that the selected
schema(s) may depend upon. Therefore, there is no guarantee
that the results of a specific-schema dump can be successfully
restored by themselves into a clean database.
.RE
.sp
.sp
.RS
.B "Note:"
Non-schema objects such as blobs are not dumped when \fB-n\fR is
specified. You can add blobs back to the dump with the
\fB--blobs\fR switch.
.RE
.sp
.TP
\fB-N \fIschema\fB\fR
.TP
\fB--exclude-schema=\fIschema\fB\fR
Do not dump any schemas matching the \fIschema\fR pattern. The pattern is
interpreted according to the same rules as for \fB-n\fR.
\fB-N\fR can be given more than once to exclude schemas
matching any of several patterns.

When both \fB-n\fR and \fB-N\fR are given, the behavior
is to dump just the schemas that match at least one \fB-n\fR
switch but no \fB-N\fR switches. If \fB-N\fR appears
without \fB-n\fR, then schemas matching \fB-N\fR are
excluded from what is otherwise a normal dump.
.TP
\fB-o\fR
.TP
\fB--oids\fR
Dump object identifiers (OIDs) as part of the
data for every table. Use this option if your application references
the OID
columns in some way (e.g., in a foreign key constraint).
Otherwise, this option should not be used.
.TP
\fB-O\fR
.TP
\fB--no-owner\fR
Do not output commands to set
ownership of objects to match the original database.
By default, \fBpg_dump\fR issues
\fBALTER OWNER\fR or
\fBSET SESSION AUTHORIZATION\fR
statements to set ownership of created database objects.
These statements
will fail when the script is run unless it is started by a superuser
(or the same user that owns all of the objects in the script).
To make a script that can be restored by any user, but will give
that user ownership of all the objects, specify \fB-O\fR.

This option is only meaningful for the plain-text format. For
the archive formats, you may specify the option when you
call \fBpg_restore\fR.
.TP
\fB-R\fR
.TP
\fB--no-reconnect\fR
This option is obsolete but still accepted for backwards
compatibility.
.TP
\fB-s\fR
.TP
\fB--schema-only\fR
Dump only the object definitions (schema), not data.
.TP
\fB-S \fIusername\fB\fR
.TP
\fB--superuser=\fIusername\fB\fR
Specify the superuser user name to use when disabling triggers.
This is only relevant if \fB--disable-triggers\fR is used.
(Usually, it's better to leave this out, and instead start the
resulting script as superuser.)
.TP
\fB-t \fItable\fB\fR
.TP
\fB--table=\fItable\fB\fR
Dump only tables (or views or sequences) matching \fItable\fR. Multiple tables can be
selected by writing multiple \fB-t\fR switches. Also, the