Current File : //proc/thread-self/root/proc/thread-self/root/opt/alt/postgresql11/usr/share/man/man1/pg_dump.1
'\" t
.\" Title: pg_dump
.\" Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\" Date: 2017-11-06
.\" Manual: PostgreSQL 9.2.24 Documentation
.\" Source: PostgreSQL 9.2.24
.\" Language: English
.\"
.TH "PG_DUMP" "1" "2017-11-06" "PostgreSQL 9.2.24" "PostgreSQL 9.2.24 Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pg_dump \- extract a PostgreSQL database into a script file or other archive file
.\" pg_dump
.SH "SYNOPSIS"
.HP \w'\fBpg_dump\fR\ 'u
\fBpg_dump\fR [\fIconnection\-option\fR...] [\fIoption\fR...] [\fIdbname\fR]
.SH "DESCRIPTION"
.PP
pg_dump
is a utility for backing up a
PostgreSQL
database\&. It makes consistent backups even if the database is being used concurrently\&.
pg_dump
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
pg_restore
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
pg_restore,
pg_dump
provides a flexible archival and transfer mechanism\&.
pg_dump
can be used to backup an entire database, then
pg_restore
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
\(lqcustom\(rq
format (\fB\-Fc\fR)\&. It allows for selection and reordering of all archived items, and is compressed by default\&.
.PP
While running
pg_dump, 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\&.
.PP
\fIdbname\fR
.RS 4
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\&.
.RE
.PP
\fB\-a\fR, \fB\-\-data\-only\fR
.RS 4
Dump only the data, not the schema (data definitions)\&. Table data, large objects, and sequence values are dumped\&.
.sp
This option is similar to, but for historical reasons not identical to, specifying
\fB\-\-section=data\fR\&.
.RE
.PP
\fB\-b\fR, \fB\-\-blobs\fR
.RS 4
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\&. The
\fB\-b\fR
switch is therefore only useful to add large objects to dumps where a specific schema or table has been requested\&. Note that blobs are considered data and therefore will be included when \-\-data\-only is used, but not when \-\-schema\-only is\&.
.RE
.PP
\fB\-c\fR, \fB\-\-clean\fR
.RS 4
Output commands to clean (drop) database objects prior to outputting the commands for creating them\&. (Restore might generate some harmless error messages, if any objects were not present in the destination database\&.)
.sp
This option is only meaningful for the plain\-text format\&. For the archive formats, you can specify the option when you call
\fBpg_restore\fR\&.
.RE
.PP
\fB\-C\fR, \fB\-\-create\fR
.RS 4
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\*(Aqt matter which database in the destination installation you connect to before running the script\&.) If
\fB\-\-clean\fR
is also specified, the script drops and recreates the target database before reconnecting to it\&.
.sp
This option is only meaningful for the plain\-text format\&. For the archive formats, you can specify the option when you call
\fBpg_restore\fR\&.
.RE
.PP
\fB\-E \fR\fB\fIencoding\fR\fR, \fB\-\-encoding=\fR\fB\fIencoding\fR\fR
.RS 4
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\&.)
.RE
.PP
\fB\-f \fR\fB\fIfile\fR\fR, \fB\-\-file=\fR\fB\fIfile\fR\fR
.RS 4
Send output to the specified file\&. This parameter can be omitted for file based output formats, in which case the standard output is used\&. It must be given for the directory output format however, where it specifies the target directory instead of a file\&. In this case the directory is created by
\fBpg_dump\fR
and must not exist before\&.
.RE
.PP
\fB\-F \fR\fB\fIformat\fR\fR, \fB\-\-format=\fR\fB\fIformat\fR\fR
.RS 4
Selects the format of the output\&.
\fIformat\fR
can be one of the following:
.PP
p, plain
.RS 4
Output a plain\-text
SQL
script file (the default)\&.
.RE
.PP
c, custom
.RS 4
Output a custom\-format archive suitable for input into
pg_restore\&. Together with the directory output format, this is the most flexible output format in that it allows manual selection and reordering of archived items during restore\&. This format is also compressed by default\&.
.RE
.PP
d, directory
.RS 4
Output a directory\-format archive suitable for input into
pg_restore\&. This will create a directory with one file for each table and blob being dumped, plus a so\-called Table of Contents file describing the dumped objects in a machine\-readable format that
pg_restore
can read\&. A directory format archive can be manipulated with standard Unix tools; for example, files in an uncompressed archive can be compressed with the
gzip
tool\&. This format is compressed by default\&.
.RE
.PP
t, tar
.RS 4
Output a
\fBtar\fR\-format archive suitable for input into
pg_restore\&. The tar format is compatible with the directory format: extracting a tar\-format archive produces a valid directory\-format archive\&. However, the tar format does not support compression\&. Also, when using tar format the relative order of table data items cannot be changed during restore\&.
.RE
.RE
.PP
\fB\-i\fR, \fB\-\-ignore\-version\fR
.RS 4
A deprecated option that is now ignored\&.
.RE
.PP
\fB\-n \fR\fB\fIschema\fR\fR, \fB\-\-schema=\fR\fB\fIschema\fR\fR
.RS 4
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
psql\*(Aqs
\ed
commands (see
Patterns), 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; see
EXAMPLES\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
When
\fB\-n\fR
is specified,
pg_dump
makes no attempt to dump any other database objects that the selected schema(s) might 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\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
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\&.
.sp .5v
.RE
.RE
.PP
\fB\-N \fR\fB\fIschema\fR\fR, \fB\-\-exclude\-schema=\fR\fB\fIschema\fR\fR
.RS 4
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\&.
.sp
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\&.
.RE
.PP
\fB\-o\fR, \fB\-\-oids\fR
.RS 4
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\&.
.RE
.PP
\fB\-O\fR, \fB\-\-no\-owner\fR
.RS 4
Do not output commands to set ownership of objects to match the original database\&. By default,
pg_dump
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\&.
.sp
This option is only meaningful for the plain\-text format\&. For the archive formats, you can specify the option when you call
\fBpg_restore\fR\&.
.RE
.PP
\fB\-R\fR, \fB\-\-no\-reconnect\fR
.RS 4
This option is obsolete but still accepted for backwards compatibility\&.
.RE
.PP
\fB\-s\fR, \fB\-\-schema\-only\fR
.RS 4
Dump only the object definitions (schema), not data\&.
.sp
This option is the inverse of
\fB\-\-data\-only\fR\&. It is similar to, but for historical reasons not identical to, specifying
\fB\-\-section=pre\-data \-\-section=post\-data\fR\&.
.sp
(Do not confuse this with the
\fB\-\-schema\fR
option, which uses the word
\(lqschema\(rq
in a different meaning\&.)
.sp
To exclude table data for only a subset of tables in the database, see
\fB\-\-exclude\-table\-data\fR\&.
.RE
.PP
\fB\-S \fR\fB\fIusername\fR\fR, \fB\-\-superuser=\fR\fB\fIusername\fR\fR
.RS 4
Specify the superuser user name to use when disabling triggers\&. This is only relevant if
\fB\-\-disable\-triggers\fR
is used\&. (Usually, it\*(Aqs better to leave this out, and instead start the resulting script as superuser\&.)
.RE
.PP
\fB\-t \fR\fB\fItable\fR\fR, \fB\-\-table=\fR\fB\fItable\fR\fR
.RS 4
Dump only tables (or views or sequences or foreign tables) matching
\fItable\fR\&. Multiple tables can be selected by writing multiple
\fB\-t\fR
switches\&. Also, the
\fItable\fR
parameter is interpreted as a pattern according to the same rules used by
psql\*(Aqs
\ed
commands (see
Patterns), so multiple tables 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; see
EXAMPLES\&.
.sp
The
\fB\-n\fR
and
\fB\-N\fR
switches have no effect when
\fB\-t\fR
is used, because tables selected by
\fB\-t\fR
will be dumped regardless of those switches, and non\-table objects will not be dumped\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
When
\fB\-t\fR
is specified,
pg_dump
makes no attempt to dump any other database objects that the selected table(s) might depend upon\&. Therefore, there is no guarantee that the results of a specific\-table dump can be successfully restored by themselves into a clean database\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
The behavior of the
\fB\-t\fR
switch is not entirely upward compatible with pre\-8\&.2
PostgreSQL
versions\&. Formerly, writing
\-t tab
would dump all tables named
tab, but now it just dumps whichever one is visible in your default search path\&. To get the old behavior you can write
\-t \*(Aq*\&.tab\*(Aq\&. Also, you must write something like
\-t sch\&.tab
to select a table in a particular schema, rather than the old locution of
\-n sch \-t tab\&.
.sp .5v
.RE
.RE
.PP
\fB\-T \fR\fB\fItable\fR\fR, \fB\-\-exclude\-table=\fR\fB\fItable\fR\fR
.RS 4
Do not dump any tables matching the
\fItable\fR
pattern\&. The pattern is interpreted according to the same rules as for
\fB\-t\fR\&.
\fB\-T\fR
can be given more than once to exclude tables matching any of several patterns\&.
.sp
When both
\fB\-t\fR
and
\fB\-T\fR
are given, the behavior is to dump just the tables that match at least one
\fB\-t\fR
switch but no
\fB\-T\fR
switches\&. If
\fB\-T\fR
appears without
\fB\-t\fR, then tables matching
\fB\-T\fR
are excluded from what is otherwise a normal dump\&.
.RE
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Specifies verbose mode\&. This will cause
pg_dump
to output detailed object comments and start/stop times to the dump file, and progress messages to standard error\&.
.RE
.PP
\fB\-V\fR, \fB\-\-version\fR
.RS 4
Print the
pg_dump
version and exit\&.
.RE
.PP
\fB\-x\fR, \fB\-\-no\-privileges\fR, \fB\-\-no\-acl\fR
.RS 4
Prevent dumping of access privileges (grant/revoke commands)\&.
.RE
.PP
\fB\-Z \fR\fB\fI0\&.\&.9\fR\fR, \fB\-\-compress=\fR\fB\fI0\&.\&.9\fR\fR
.RS 4
Specify the compression level to use\&. Zero means no compression\&. For the custom archive format, this specifies compression of individual table\-data segments, and the default is to compress at a moderate level\&. For plain text output, setting a nonzero compression level causes the entire output file to be compressed, as though it had been fed through
gzip; but the default is not to compress\&. The tar archive format currently does not support compression at all\&.
.RE
.PP
\fB\-\-binary\-upgrade\fR
.RS 4
This option is for use by in\-place upgrade utilities\&. Its use for other purposes is not recommended or supported\&. The behavior of the option may change in future releases without notice\&.
.RE
.PP
\fB\-\-column\-inserts\fR, \fB\-\-attribute\-inserts\fR
.RS 4
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\&. However, 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\&.
.RE
.PP
\fB\-\-disable\-dollar\-quoting\fR
.RS 4
This option disables the use of dollar quoting for function bodies, and forces them to be quoted using SQL standard string syntax\&.
.RE
.PP
\fB\-\-disable\-triggers\fR
.RS 4
This option is only relevant when creating a data\-only dump\&. It instructs
pg_dump
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\&.
.sp
Presently, the commands emitted for
\fB\-\-disable\-triggers\fR
must be done as superuser\&. So, you should also specify a superuser name with
\fB\-S\fR, or preferably be careful to start the resulting script as a superuser\&.
.sp
This option is only meaningful for the plain\-text format\&. For the archive formats, you can specify the option when you call
\fBpg_restore\fR\&.
.RE
.PP
\fB\-\-exclude\-table\-data=\fR\fB\fItable\fR\fR
.RS 4
Do not dump data for any tables matching the
\fItable\fR
pattern\&. The pattern is interpreted according to the same rules as for
\fB\-t\fR\&.
\fB\-\-exclude\-table\-data\fR
can be given more than once to exclude tables matching any of several patterns\&. This option is useful when you need the definition of a particular table even though you do not need the data in it\&.
.sp
To exclude data for all tables in the database, see
\fB\-\-schema\-only\fR\&.
.RE
.PP
\fB\-\-inserts\fR
.RS 4
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\&. However, 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 might fail altogether if you have rearranged column order\&. The
\fB\-\-column\-inserts\fR
option is safe against column order changes, though even slower\&.
.RE
.PP
\fB\-\-lock\-wait\-timeout=\fR\fB\fItimeout\fR\fR
.RS 4
Do not wait forever to acquire shared table locks at the beginning of the dump\&. Instead fail if unable to lock a table within the specified
\fItimeout\fR\&. The timeout may be specified in any of the formats accepted by
\fBSET statement_timeout\fR\&. (Allowed values vary depending on the server version you are dumping from, but an integer number of milliseconds is accepted by all versions since 7\&.3\&. This option is ignored when dumping from a pre\-7\&.3 server\&.)
.RE
.PP
\fB\-\-no\-security\-labels\fR
.RS 4
Do not dump security labels\&.
.RE
.PP
\fB\-\-no\-tablespaces\fR
.RS 4
Do not output commands to select tablespaces\&. With this option, all objects will be created in whichever tablespace is the default during restore\&.
.sp
This option is only meaningful for the plain\-text format\&. For the archive formats, you can specify the option when you call
\fBpg_restore\fR\&.
.RE
.PP
\fB\-\-no\-unlogged\-table\-data\fR
.RS 4
Do not dump the contents of unlogged tables\&. This option has no effect on whether or not the table definitions (schema) are dumped; it only suppresses dumping the table data\&. Data in unlogged tables is always excluded when dumping from a standby server\&.
.RE
.PP
\fB\-\-quote\-all\-identifiers\fR
.RS 4
Force quoting of all identifiers\&. This option is recommended when dumping a database from a server whose
PostgreSQL
major version is different from
pg_dump\*(Aqs, or when the output is intended to be loaded into a server of a different major version\&. By default,
pg_dump
quotes only identifiers that are reserved words in its own major version\&. This sometimes results in compatibility issues when dealing with servers of other versions that may have slightly different sets of reserved words\&. Using
\fB\-\-quote\-all\-identifiers\fR
prevents such issues, at the price of a harder\-to\-read dump script\&.
.RE
.PP
\fB\-\-section=\fR\fB\fIsectionname\fR\fR
.RS 4
Only dump the named section\&. The section name can be
\fBpre\-data\fR,
\fBdata\fR, or
\fBpost\-data\fR\&. This option can be specified more than once to select multiple sections\&. The default is to dump all sections\&.
.sp
The data section contains actual table data, large\-object contents, and sequence values\&. Post\-data items include definitions of indexes, triggers, rules, and constraints other than validated check constraints\&. Pre\-data items include all other data definition items\&.
.RE
.PP
\fB\-\-serializable\-deferrable\fR
.RS 4
Use a
serializable
transaction for the dump, to ensure that the snapshot used is consistent with later database states; but do this by waiting for a point in the transaction stream at which no anomalies can be present, so that there isn\*(Aqt a risk of the dump failing or causing other transactions to roll back with a
serialization_failure\&. See
Chapter 13, Concurrency Control, in the documentation
for more information about transaction isolation and concurrency control\&.
.sp
This option is not beneficial for a dump which is intended only for disaster recovery\&. It could be useful for a dump used to load a copy of the database for reporting or other read\-only load sharing while the original database continues to be updated\&. Without it the dump may reflect a state which is not consistent with any serial execution of the transactions eventually committed\&. For example, if batch processing techniques are used, a batch may show as closed in the dump without all of the items which are in the batch appearing\&.
.sp
This option will make no difference if there are no read\-write transactions active when pg_dump is started\&. If read\-write transactions are active, the start of the dump may be delayed for an indeterminate length of time\&. Once running, performance with or without the switch is the same\&.
.RE
.PP
\fB\-\-use\-set\-session\-authorization\fR
.RS 4
Output SQL\-standard
\fBSET SESSION AUTHORIZATION\fR
commands instead of
\fBALTER OWNER\fR
commands to determine object ownership\&. This makes the dump more standards\-compatible, but depending on the history of the objects in the dump, might not restore properly\&. Also, a dump using
\fBSET SESSION AUTHORIZATION\fR
will certainly require superuser privileges to restore correctly, whereas
\fBALTER OWNER\fR
requires lesser privileges\&.
.RE
.PP
\fB\-?\fR, \fB\-\-help\fR
.RS 4
Show help about
pg_dump
command line arguments, and exit\&.
.RE
.PP
The following command\-line options control the database connection parameters\&.
.PP
\fB\-h \fR\fB\fIhost\fR\fR, \fB\-\-host=\fR\fB\fIhost\fR\fR
.RS 4
Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. The default is taken from the
\fBPGHOST\fR
environment variable, if set, else a Unix domain socket connection is attempted\&.
.RE
.PP
\fB\-p \fR\fB\fIport\fR\fR, \fB\-\-port=\fR\fB\fIport\fR\fR
.RS 4
Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. Defaults to the
\fBPGPORT\fR
environment variable, if set, or a compiled\-in default\&.
.RE
.PP
\fB\-U \fR\fB\fIusername\fR\fR, \fB\-\-username=\fR\fB\fIusername\fR\fR
.RS 4
User name to connect as\&.
.RE
.PP
\fB\-w\fR, \fB\-\-no\-password\fR
.RS 4
Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a
\&.pgpass
file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&.
.RE
.PP
\fB\-W\fR, \fB\-\-password\fR
.RS 4
Force
pg_dump
to prompt for a password before connecting to a database\&.
.sp
This option is never essential, since
pg_dump
will automatically prompt for a password if the server demands password authentication\&. However,
pg_dump
will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing
\fB\-W\fR
to avoid the extra connection attempt\&.
.RE
.PP
\fB\-\-role=\fR\fB\fIrolename\fR\fR
.RS 4
Specifies a role name to be used to create the dump\&. This option causes
pg_dump
to issue a
\fBSET ROLE\fR\fIrolename\fR
command after connecting to the database\&. It is useful when the authenticated user (specified by
\fB\-U\fR) lacks privileges needed by
pg_dump, but can switch to a role with the required rights\&. Some installations have a policy against logging in directly as a superuser, and use of this option allows dumps to be made without violating the policy\&.
.RE
.SH "ENVIRONMENT"
.PP
\fBPGDATABASE\fR, \fBPGHOST\fR, \fBPGOPTIONS\fR, \fBPGPORT\fR, \fBPGUSER\fR
.RS 4
Default connection parameters\&.
.RE
.PP
This utility, like most other
PostgreSQL
utilities, also uses the environment variables supported by
libpq
(see
Section 31.14, \(lqEnvironment Variables\(rq, in the documentation)\&.
.SH "DIAGNOSTICS"
.PP
pg_dump
internally executes
\fBSELECT\fR
statements\&. If you have problems running
pg_dump, make sure you are able to select information from the database using, for example,
\fBpsql\fR(1)\&. Also, any default connection settings and environment variables used by the
libpq
front\-end library will apply\&.
.PP
The database activity of
pg_dump
is normally collected by the statistics collector\&. If this is undesirable, you can set parameter
\fItrack_counts\fR
to false via
\fBPGOPTIONS\fR
or the
ALTER USER
command\&.
.SH "NOTES"
.PP
If your database cluster has any local additions to the
template1
database, be careful to restore the output of
pg_dump
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:
.sp
.if n \{\
.RS 4
.\}
.nf
CREATE DATABASE foo WITH TEMPLATE template0;
.fi
.if n \{\
.RE
.\}
.PP
When a data\-only dump is chosen and the option
\fB\-\-disable\-triggers\fR
is used,
pg_dump
emits commands to disable triggers on user tables before inserting the data, and then commands to re\-enable them after the data has been inserted\&. If the restore is stopped in the middle, the system catalogs might be left in the wrong state\&.
.PP
The dump file produced by
pg_dump
does not contain the statistics used by the optimizer to make query planning decisions\&. Therefore, it is wise to run
\fBANALYZE\fR
after restoring from a dump file to ensure optimal performance; see
Section 23.1.3, \(lqUpdating Planner Statistics\(rq, in the documentation
and
Section 23.1.6, \(lqThe Autovacuum Daemon\(rq, in the documentation
for more information\&. The dump file also does not contain any
\fBALTER DATABASE \&.\&.\&. SET\fR
commands; these settings are dumped by
\fBpg_dumpall\fR(1), along with database users and other installation\-wide settings\&.
.PP
Because
pg_dump
is used to transfer data to newer versions of
PostgreSQL, the output of
pg_dump
can be expected to load into
PostgreSQL
server versions newer than
pg_dump\*(Aqs version\&.
pg_dump
can also dump from
PostgreSQL
servers older than its own version\&. (Currently, servers back to version 7\&.0 are supported\&.) However,
pg_dump
cannot dump from
PostgreSQL
servers newer than its own major version; it will refuse to even try, rather than risk making an invalid dump\&. Also, it is not guaranteed that
pg_dump\*(Aqs output can be loaded into a server of an older major version \(em not even if the dump was taken from a server of that version\&. Loading a dump file into an older server may require manual editing of the dump file to remove syntax not understood by the older server\&. Use of the
\fB\-\-quote\-all\-identifiers\fR
option is recommended in cross\-version cases, as it can prevent problems arising from varying reserved\-word lists in different
PostgreSQL
versions\&.
.SH "EXAMPLES"
.PP
To dump a database called
mydb
into a SQL\-script file:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpg_dump mydb > db\&.sql\fR
.fi
.if n \{\
.RE
.\}
.PP
To reload such a script into a (freshly created) database named
newdb:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpsql \-d newdb \-f db\&.sql\fR
.fi
.if n \{\
.RE
.\}
.PP
To dump a database into a custom\-format archive file:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpg_dump \-Fc mydb > db\&.dump\fR
.fi
.if n \{\
.RE
.\}
.PP
To dump a database into a directory\-format archive:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpg_dump \-Fd mydb \-f dumpdir\fR
.fi
.if n \{\
.RE
.\}
.PP
To reload an archive file into a (freshly created) database named
newdb:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpg_restore \-d newdb db\&.dump\fR
.fi
.if n \{\
.RE
.\}
.PP
To dump a single table named
mytab:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpg_dump \-t mytab mydb > db\&.sql\fR
.fi
.if n \{\
.RE
.\}
.PP
To dump all tables whose names start with
emp
in the
detroit
schema, except for the table named
employee_log:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpg_dump \-t \*(Aqdetroit\&.emp*\*(Aq \-T detroit\&.employee_log mydb > db\&.sql\fR
.fi
.if n \{\
.RE
.\}
.PP
To dump all schemas whose names start with
east
or
west
and end in
gsm, excluding any schemas whose names contain the word
test:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpg_dump \-n \*(Aqeast*gsm\*(Aq \-n \*(Aqwest*gsm\*(Aq \-N \*(Aq*test*\*(Aq mydb > db\&.sql\fR
.fi
.if n \{\
.RE
.\}
.PP
The same, using regular expression notation to consolidate the switches:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpg_dump \-n \*(Aq(east|west)*gsm\*(Aq \-N \*(Aq*test*\*(Aq mydb > db\&.sql\fR
.fi
.if n \{\
.RE
.\}
.PP
To dump all database objects except for tables whose names begin with
ts_:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpg_dump \-T \*(Aqts_*\*(Aq mydb > db\&.sql\fR
.fi
.if n \{\
.RE
.\}
.PP
To specify an upper\-case or mixed\-case name in
\fB\-t\fR
and related switches, you need to double\-quote the name; else it will be folded to lower case (see
Patterns)\&. But double quotes are special to the shell, so in turn they must be quoted\&. Thus, to dump a single table with a mixed\-case name, you need something like
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBpg_dump \-t \*(Aq"MixedCaseName"\*(Aq mydb > mytab\&.sql\fR
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
\fBpg_dumpall\fR(1), \fBpg_restore\fR(1), \fBpsql\fR(1)
Mini Shell