begriffs open source - ai-pg/blob - full-docs/html/app-pgdump.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_dump</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pgconfig.html" title="pg_config" /><link rel="next" href="app-pg-dumpall.html" title="pg_dumpall" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_dump</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgconfig.html" title="pg_config">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pg-dumpall.html" title="pg_dumpall">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGDUMP"><div class="titlepage"></div><a id="id-1.9.4.14.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_dump</span></span></h2><p>pg_dump —
   3    export a <span class="productname">PostgreSQL</span> database as an SQL script or to other formats
   4   </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.14.4.1"><code class="command">pg_dump</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>dbname</code></em>]</p></div></div><div class="refsect1" id="PG-DUMP-DESCRIPTION"><h2>Description</h2><p>
   5    <span class="application">pg_dump</span> is a utility for exporting a
   6    <span class="productname">PostgreSQL</span> database. It makes consistent
   7    exports even if the database is being used concurrently.
   8    <span class="application">pg_dump</span> does not block other users
   9    accessing the database (readers or writers).
  10    Note, however, that except in simple cases,
  11    <span class="application">pg_dump</span> is generally not the right choice for
  12    taking regular backups of production databases.  See <a class="xref" href="backup.html" title="Chapter 25. Backup and Restore">Chapter 25</a> for further discussion.
  13   </p><p>
  14    <span class="application">pg_dump</span> only dumps a single database.
  15    To export an entire cluster, or to export global objects that are
  16    common to all databases in a cluster (such as roles and tablespaces),
  17    use <a class="xref" href="app-pg-dumpall.html" title="pg_dumpall"><span class="refentrytitle"><span class="application">pg_dumpall</span></span></a>.
  18   </p><p>
  19    Dumps can be output in script or archive file formats. Script
  20    dumps are plain-text files containing the SQL commands required
  21    to reconstruct the database to the state it was in at the time it was
  22    saved. To restore from such a script, feed it to <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a>. Script files
  23    can be used to reconstruct the database even on other machines and
  24    other architectures; with some modifications, even on other SQL
  25    database products.
  26   </p><p>
  27    The alternative archive file formats must be used with
  28    <a class="xref" href="app-pgrestore.html" title="pg_restore"><span class="refentrytitle"><span class="application">pg_restore</span></span></a> to rebuild the database.  They
  29    allow <span class="application">pg_restore</span> to be selective about
  30    what is restored, or even to reorder the items prior to being
  31    restored.
  32    The archive file formats are designed to be portable across
  33    architectures.
  34   </p><p>
  35    When used with one of the archive file formats and combined with
  36    <span class="application">pg_restore</span>,
  37    <span class="application">pg_dump</span> provides a flexible archival and
  38    transfer mechanism. <span class="application">pg_dump</span> can be used to
  39    export an entire database, then <span class="application">pg_restore</span>
  40    can be used to examine the archive and/or select which parts of the
  41    database are to be restored. The most flexible output file formats are
  42    the <span class="quote">“<span class="quote">custom</span>”</span> format (<code class="option">-Fc</code>) and the
  43    <span class="quote">“<span class="quote">directory</span>”</span> format (<code class="option">-Fd</code>). They allow
  44    for selection and reordering of all archived items, support parallel
  45    restoration, and are compressed by default. The <span class="quote">“<span class="quote">directory</span>”</span>
  46    format is the only format that supports parallel dumps.
  47   </p><p>
  48    While running <span class="application">pg_dump</span>, one should examine the
  49    output for any warnings (printed on standard error), especially in
  50    light of the limitations listed below.
  51   </p><div class="warning"><h3 class="title">Warning</h3><p>
  52     Restoring a dump causes the destination to execute arbitrary code of the
  53     source superusers' choice.  Partial dumps and partial restores do not limit
  54     that.  If the source superusers are not trusted, the dumped SQL statements
  55     must be inspected before restoring.  Non-plain-text dumps can be inspected
  56     by using <span class="application">pg_restore</span>'s <code class="option">--file</code>
  57     option.  Note that the client running the dump and restore need not trust
  58     the source or destination superusers.
  59    </p></div></div><div class="refsect1" id="PG-DUMP-OPTIONS"><h2>Options</h2><p>
  60     The following command-line options control the content and
  61     format of the output.
  62
  63     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>dbname</code></em></span></dt><dd><p>
  64         Specifies the name of the database to be dumped.  If this is
  65         not specified, the environment variable
  66         <code class="envar">PGDATABASE</code> is used.  If that is not set, the
  67         user name specified for the connection is used.
  68        </p></dd><dt><span class="term"><code class="option">-a</code><br /></span><span class="term"><code class="option">--data-only</code></span></dt><dd><p>
  69         Dump only the data, not the schema (data definitions) or statistics.
  70         Table data, large objects, and sequence values are dumped.
  71        </p><p>
  72         This option is similar to, but for historical reasons not identical
  73         to, specifying <code class="option">--section=data</code>.
  74        </p></dd><dt><span class="term"><code class="option">-b</code><br /></span><span class="term"><code class="option">--large-objects</code><br /></span><span class="term"><code class="option">--blobs</code> (deprecated)</span></dt><dd><p>
  75         Include large objects in the dump.  This is the default behavior
  76         except when <code class="option">--schema</code>, <code class="option">--table</code>,
  77         <code class="option">--schema-only</code>, <code class="option">--statistics-only</code>, or
  78         <code class="option">--no-data</code> is specified.  The <code class="option">-b</code>
  79         switch is therefore only useful to add large objects to dumps where a
  80         specific schema or table has been requested.  Note that large objects
  81         are considered data and therefore will be included when
  82         <code class="option">--data-only</code> is used, but not when
  83         <code class="option">--schema-only</code> or <code class="option">--statistics-only</code>
  84         is.
  85        </p></dd><dt><span class="term"><code class="option">-B</code><br /></span><span class="term"><code class="option">--no-large-objects</code><br /></span><span class="term"><code class="option">--no-blobs</code> (deprecated)</span></dt><dd><p>
  86         Exclude large objects in the dump.
  87        </p><p>
  88         When both <code class="option">-b</code> and <code class="option">-B</code> are given, the behavior
  89         is to output large objects, when data is being dumped, see the
  90         <code class="option">-b</code> documentation.
  91        </p></dd><dt><span class="term"><code class="option">-c</code><br /></span><span class="term"><code class="option">--clean</code></span></dt><dd><p>
  92         Output commands to <code class="command">DROP</code> all the dumped
  93         database objects prior to outputting the commands for creating them.
  94         This option is useful when the restore is to overwrite an existing
  95         database.  If any of the objects do not exist in the destination
  96         database, ignorable error messages will be reported during
  97         restore, unless <code class="option">--if-exists</code> is also specified.
  98        </p><p>
  99         This option is ignored when emitting an archive (non-text) output
 100         file.  For the archive formats, you can specify the option when you
 101         call <code class="command">pg_restore</code>.
 102        </p></dd><dt><span class="term"><code class="option">-C</code><br /></span><span class="term"><code class="option">--create</code></span></dt><dd><p>
 103         Begin the output with a command to create the
 104         database itself and reconnect to the created database.  (With a
 105         script of this form, it doesn't matter which database in the
 106         destination installation you connect to before running the script.)
 107         If <code class="option">--clean</code> is also specified, the script drops and
 108         recreates the target database before reconnecting to it.
 109        </p><p>
 110         With <code class="option">--create</code>, the output also includes the
 111         database's comment if any, and any configuration variable settings
 112         that are specific to this database, that is,
 113         any <code class="command">ALTER DATABASE ... SET ...</code>
 114         and <code class="command">ALTER ROLE ... IN DATABASE ... SET ...</code>
 115         commands that mention this database.
 116         Access privileges for the database itself are also dumped,
 117         unless <code class="option">--no-acl</code> is specified.
 118        </p><p>
 119         This option is ignored when emitting an archive (non-text) output
 120         file.  For the archive formats, you can specify the option when you
 121         call <code class="command">pg_restore</code>.
 122        </p></dd><dt><span class="term"><code class="option">-e <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--extension=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
 123         Dump only extensions matching <em class="replaceable"><code>pattern</code></em>.  When this option is not
 124         specified, all non-system extensions in the target database will be
 125         dumped.  Multiple extensions can be selected by writing multiple
 126         <code class="option">-e</code> switches.  The <em class="replaceable"><code>pattern</code></em> parameter is interpreted as a
 127         pattern according to the same rules used by
 128         <span class="application">psql</span>'s <code class="literal">\d</code> commands (see
 129         <a class="xref" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns">Patterns</a>), so multiple extensions can also
 130         be selected by writing wildcard characters in the pattern.  When using
 131         wildcards, be careful to quote the pattern if needed to prevent the
 132         shell from expanding the wildcards.
 133        </p><p>
 134         Any configuration relation registered by
 135         <code class="function">pg_extension_config_dump</code> is included in the
 136         dump if its extension is specified by <code class="option">--extension</code>.
 137        </p><div class="note"><h3 class="title">Note</h3><p>
 138          When <code class="option">-e</code> is specified,
 139          <span class="application">pg_dump</span> makes no attempt to dump any other
 140          database objects that the selected extension(s) might depend upon.
 141          Therefore, there is no guarantee that the results of a
 142          specific-extension dump can be successfully restored by themselves
 143          into a clean database.
 144         </p></div></dd><dt><span class="term"><code class="option">-E <em class="replaceable"><code>encoding</code></em></code><br /></span><span class="term"><code class="option">--encoding=<em class="replaceable"><code>encoding</code></em></code></span></dt><dd><p>
 145         Create the dump in the specified character set encoding. By default,
 146         the dump is created in the database encoding.  (Another way to get the
 147         same result is to set the <code class="envar">PGCLIENTENCODING</code> environment
 148         variable to the desired dump encoding.)  The supported encodings are
 149         described in <a class="xref" href="multibyte.html#MULTIBYTE-CHARSET-SUPPORTED" title="23.3.1. Supported Character Sets">Section 23.3.1</a>.
 150        </p></dd><dt><span class="term"><code class="option">-f <em class="replaceable"><code>file</code></em></code><br /></span><span class="term"><code class="option">--file=<em class="replaceable"><code>file</code></em></code></span></dt><dd><p>
 151         Send output to the specified file. This parameter can be omitted for
 152         file based output formats, in which case the standard output is used.
 153         It must be given for the directory output format however, where it
 154         specifies the target directory instead of a file. In this case the
 155         directory is created by <code class="command">pg_dump</code> and must not exist
 156         before.
 157        </p></dd><dt><span class="term"><code class="option">-F <em class="replaceable"><code>format</code></em></code><br /></span><span class="term"><code class="option">--format=<em class="replaceable"><code>format</code></em></code></span></dt><dd><p>
 158         Selects the format of the output.
 159         <em class="replaceable"><code>format</code></em> can be one of the following:
 160
 161        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">p</code><br /></span><span class="term"><code class="literal">plain</code></span></dt><dd><p>
 162            Output a plain-text <acronym class="acronym">SQL</acronym> script file (the default).
 163           </p></dd><dt><span class="term"><code class="literal">c</code><br /></span><span class="term"><code class="literal">custom</code></span></dt><dd><p>
 164            Output a custom-format archive suitable for input into
 165            <span class="application">pg_restore</span>.
 166            Together with the directory output format, this is the most flexible
 167            output format in that it allows manual selection and reordering of
 168            archived items during restore. This format is also compressed by
 169            default.
 170           </p></dd><dt><span class="term"><code class="literal">d</code><br /></span><span class="term"><code class="literal">directory</code></span></dt><dd><p>
 171            Output a directory-format archive suitable for input into
 172            <span class="application">pg_restore</span>. This will create a directory
 173            with one file for each table and large object being dumped, plus a
 174            so-called Table of Contents file describing the dumped objects in a
 175            machine-readable format that <span class="application">pg_restore</span>
 176            can read. A directory format archive can be manipulated with
 177            standard Unix tools; for example, files in an uncompressed archive
 178            can be compressed with the <span class="application">gzip</span>,
 179            <span class="application">lz4</span>, or
 180            <span class="application">zstd</span> tools.
 181            This format is compressed by default using <code class="literal">gzip</code>
 182            and also supports parallel dumps.
 183           </p></dd><dt><span class="term"><code class="literal">t</code><br /></span><span class="term"><code class="literal">tar</code></span></dt><dd><p>
 184            Output a <code class="command">tar</code>-format archive suitable for input
 185            into <span class="application">pg_restore</span>. The tar format is
 186            compatible with the directory format: extracting a tar-format
 187            archive produces a valid directory-format archive.
 188            However, the tar format does not support compression. Also, when
 189            using tar format the relative order of table data items cannot be
 190            changed during restore.
 191           </p></dd></dl></div></dd><dt><span class="term"><code class="option">-j <em class="replaceable"><code>njobs</code></em></code><br /></span><span class="term"><code class="option">--jobs=<em class="replaceable"><code>njobs</code></em></code></span></dt><dd><p>
 192         Run the dump in parallel by dumping <em class="replaceable"><code>njobs</code></em>
 193         tables simultaneously. This option may reduce the time needed to perform the dump but it also
 194         increases the load on the database server. You can only use this option with the
 195         directory output format because this is the only output format where multiple processes
 196         can write their data at the same time.
 197        </p><p><span class="application">pg_dump</span> will open <em class="replaceable"><code>njobs</code></em>
 198         + 1 connections to the database, so make sure your <a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a>
 199         setting is high enough to accommodate all connections.
 200        </p><p>
 201         Requesting exclusive locks on database objects while running a parallel dump could
 202         cause the dump to fail. The reason is that the <span class="application">pg_dump</span> leader process
 203         requests shared locks (<a class="link" href="explicit-locking.html#LOCKING-TABLES" title="13.3.1. Table-Level Locks">ACCESS SHARE</a>) on the
 204         objects that the worker processes are going to dump later in order to
 205         make sure that nobody deletes them and makes them go away while the dump is running.
 206         If another client then requests an exclusive lock on a table, that lock will not be
 207         granted but will be queued waiting for the shared lock of the leader process to be
 208         released. Consequently any other access to the table will not be granted either and
 209         will queue after the exclusive lock request. This includes the worker process trying
 210         to dump the table. Without any precautions this would be a classic deadlock situation.
 211         To detect this conflict, the <span class="application">pg_dump</span> worker process requests another
 212         shared lock using the <code class="literal">NOWAIT</code> option. If the worker process is not granted
 213         this shared lock, somebody else must have requested an exclusive lock in the meantime
 214         and there is no way to continue with the dump, so <span class="application">pg_dump</span> has no choice
 215         but to abort the dump.
 216        </p><p>
 217         To perform a parallel dump, the database server needs to support
 218         synchronized snapshots, a feature that was introduced in
 219         <span class="productname">PostgreSQL</span> 9.2 for primary servers and 10
 220         for standbys. With this feature, database clients can ensure they see
 221         the same data set even though they use different connections.
 222         <code class="command">pg_dump -j</code> uses multiple database connections; it
 223         connects to the database once with the leader process and once again
 224         for each worker job. Without the synchronized snapshot feature, the
 225         different worker jobs wouldn't be guaranteed to see the same data in
 226         each connection, which could lead to an inconsistent backup.
 227        </p></dd><dt><span class="term"><code class="option">-n <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--schema=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
 228         Dump only schemas matching <em class="replaceable"><code>pattern</code></em>; this selects both the
 229         schema itself, and all its contained objects.  When this option is
 230         not specified, all non-system schemas in the target database will be
 231         dumped.  Multiple schemas can be
 232         selected by writing multiple <code class="option">-n</code> switches.  The
 233         <em class="replaceable"><code>pattern</code></em> parameter is
 234         interpreted as a pattern according to the same rules used by
 235         <span class="application">psql</span>'s <code class="literal">\d</code> commands
 236         (see <a class="xref" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns">Patterns</a>),
 237         so multiple schemas can also be selected by writing wildcard characters
 238         in the pattern.  When using wildcards, be careful to quote the pattern
 239         if needed to prevent the shell from expanding the wildcards;  see
 240         <a class="xref" href="app-pgdump.html#PG-DUMP-EXAMPLES" title="Examples">Examples</a> below.
 241        </p><div class="note"><h3 class="title">Note</h3><p>
 242          When <code class="option">-n</code> is specified, <span class="application">pg_dump</span>
 243          makes no attempt to dump any other database objects that the selected
 244          schema(s) might depend upon. Therefore, there is no guarantee
 245          that the results of a specific-schema dump can be successfully
 246          restored by themselves into a clean database.
 247         </p></div><div class="note"><h3 class="title">Note</h3><p>
 248          Non-schema objects such as large objects are not dumped when <code class="option">-n</code> is
 249          specified.  You can add large objects back to the dump with the
 250          <code class="option">--large-objects</code> switch.
 251         </p></div></dd><dt><span class="term"><code class="option">-N <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--exclude-schema=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
 252         Do not dump any schemas matching <em class="replaceable"><code>pattern</code></em>.  The pattern is
 253         interpreted according to the same rules as for <code class="option">-n</code>.
 254         <code class="option">-N</code> can be given more than once to exclude schemas
 255         matching any of several patterns.
 256        </p><p>
 257         When both <code class="option">-n</code> and <code class="option">-N</code> are given, the behavior
 258         is to dump just the schemas that match at least one <code class="option">-n</code>
 259         switch but no <code class="option">-N</code> switches.  If <code class="option">-N</code> appears
 260         without <code class="option">-n</code>, then schemas matching <code class="option">-N</code> are
 261         excluded from what is otherwise a normal dump.
 262        </p></dd><dt><span class="term"><code class="option">-O</code><br /></span><span class="term"><code class="option">--no-owner</code></span></dt><dd><p>
 263         Do not output commands to set
 264         ownership of objects to match the original database.
 265         By default, <span class="application">pg_dump</span> issues
 266         <code class="command">ALTER OWNER</code> or
 267         <code class="command">SET SESSION AUTHORIZATION</code>
 268         statements to set ownership of created database objects.
 269         These statements
 270         will fail when the script is run unless it is started by a superuser
 271         (or the same user that owns all of the objects in the script).
 272         To make a script that can be restored by any user, but will give
 273         that user ownership of all the objects, specify <code class="option">-O</code>.
 274        </p><p>
 275         This option is ignored when emitting an archive (non-text) output
 276         file.  For the archive formats, you can specify the option when you
 277         call <code class="command">pg_restore</code>.
 278        </p></dd><dt><span class="term"><code class="option">-R</code><br /></span><span class="term"><code class="option">--no-reconnect</code></span></dt><dd><p>
 279         This option is obsolete but still accepted for backwards
 280         compatibility.
 281        </p></dd><dt><span class="term"><code class="option">-s</code><br /></span><span class="term"><code class="option">--schema-only</code></span></dt><dd><p>
 282         Dump only the object definitions (schema), not data or statistics.
 283        </p><p>
 284         This option cannot be used with <code class="option">--data-only</code>
 285         or <code class="option">--statistics-only</code>.
 286         It is similar to, but for historical reasons not identical to,
 287         specifying
 288         <code class="option">--section=pre-data --section=post-data</code>.
 289        </p><p>
 290         (Do not confuse this with the <code class="option">--schema</code> option, which
 291         uses the word <span class="quote">“<span class="quote">schema</span>”</span> in a different meaning.)
 292        </p><p>
 293         To exclude table data for only a subset of tables in the database,
 294         see <code class="option">--exclude-table-data</code>.
 295        </p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--superuser=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
 296         Specify the superuser user name to use when disabling triggers.
 297         This is relevant only if <code class="option">--disable-triggers</code> is used.
 298         (Usually, it's better to leave this out, and instead start the
 299         resulting script as superuser.)
 300        </p></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--table=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
 301         Dump only tables with names matching
 302         <em class="replaceable"><code>pattern</code></em>. Multiple tables
 303         can be selected by writing multiple <code class="option">-t</code> switches.  The
 304         <em class="replaceable"><code>pattern</code></em> parameter is
 305         interpreted as a pattern according to the same rules used by
 306         <span class="application">psql</span>'s <code class="literal">\d</code> commands
 307         (see <a class="xref" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns">Patterns</a>),
 308         so multiple tables can also be selected by writing wildcard characters
 309         in the pattern.  When using wildcards, be careful to quote the pattern
 310         if needed to prevent the shell from expanding the wildcards;  see
 311         <a class="xref" href="app-pgdump.html#PG-DUMP-EXAMPLES" title="Examples">Examples</a> below.
 312        </p><p>
 313         As well as tables, this option can be used to dump the definition of matching
 314         views, materialized views, foreign tables, and sequences.  It will not dump the
 315         contents of views or materialized views, and the contents of foreign tables will
 316         only be dumped if the corresponding foreign server is specified with
 317         <code class="option">--include-foreign-data</code>.
 318        </p><p>
 319         The <code class="option">-n</code> and <code class="option">-N</code> switches have no effect when
 320         <code class="option">-t</code> is used, because tables selected by <code class="option">-t</code> will
 321         be dumped regardless of those switches, and non-table objects will not
 322         be dumped.
 323        </p><div class="note"><h3 class="title">Note</h3><p>
 324          When <code class="option">-t</code> is specified, <span class="application">pg_dump</span>
 325          makes no attempt to dump any other database objects that the selected
 326          table(s) might depend upon. Therefore, there is no guarantee
 327          that the results of a specific-table dump can be successfully
 328          restored by themselves into a clean database.
 329         </p></div></dd><dt><span class="term"><code class="option">-T <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--exclude-table=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
 330         Do not dump any tables matching <em class="replaceable"><code>pattern</code></em>.  The pattern is
 331         interpreted according to the same rules as for <code class="option">-t</code>.
 332         <code class="option">-T</code> can be given more than once to exclude tables
 333         matching any of several patterns.
 334        </p><p>
 335         When both <code class="option">-t</code> and <code class="option">-T</code> are given, the behavior
 336         is to dump just the tables that match at least one <code class="option">-t</code>
 337         switch but no <code class="option">-T</code> switches.  If <code class="option">-T</code> appears
 338         without <code class="option">-t</code>, then tables matching <code class="option">-T</code> are
 339         excluded from what is otherwise a normal dump.
 340        </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
 341         Specifies verbose mode.  This will cause
 342         <span class="application">pg_dump</span> to output detailed object
 343         comments and start/stop times to the dump file, and progress
 344         messages to standard error.
 345         Repeating the option causes additional debug-level messages
 346         to appear on standard error.
 347        </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
 348        Print the <span class="application">pg_dump</span> version and exit.
 349        </p></dd><dt><span class="term"><code class="option">-x</code><br /></span><span class="term"><code class="option">--no-privileges</code><br /></span><span class="term"><code class="option">--no-acl</code></span></dt><dd><p>
 350         Prevent dumping of access privileges (grant/revoke commands).
 351        </p></dd><dt><span class="term"><code class="option">-Z <em class="replaceable"><code>level</code></em></code><br /></span><span class="term"><code class="option">-Z <em class="replaceable"><code>method</code></em></code>[:<em class="replaceable"><code>detail</code></em>]<br /></span><span class="term"><code class="option">--compress=<em class="replaceable"><code>level</code></em></code><br /></span><span class="term"><code class="option">--compress=<em class="replaceable"><code>method</code></em></code>[:<em class="replaceable"><code>detail</code></em>]</span></dt><dd><p>
 352         Specify the compression method and/or the compression level to use.
 353         The compression method can be set to <code class="literal">gzip</code>,
 354         <code class="literal">lz4</code>, <code class="literal">zstd</code>,
 355         or <code class="literal">none</code> for no compression.
 356         A compression detail string can optionally be specified.  If the
 357         detail string is an integer, it specifies the compression level.
 358         Otherwise, it should be a comma-separated list of items, each of the
 359         form <code class="literal">keyword</code> or <code class="literal">keyword=value</code>.
 360         Currently, the supported keywords are <code class="literal">level</code> and
 361         <code class="literal">long</code>.
 362        </p><p>
 363         If no compression level is specified, the default compression
 364         level will be used. If only a level is specified without mentioning
 365         an algorithm, <code class="literal">gzip</code> compression will be used if
 366         the level is greater than <code class="literal">0</code>, and no compression
 367         will be used if the level is <code class="literal">0</code>.
 368        </p><p>
 369         For the custom and directory archive formats, this specifies compression of
 370         individual table-data segments, and the default is to compress using
 371         <code class="literal">gzip</code> at a moderate level. For plain text output,
 372         setting a nonzero compression level causes the entire output file to be compressed,
 373         as though it had been fed through <span class="application">gzip</span>,
 374         <span class="application">lz4</span>, or <span class="application">zstd</span>;
 375         but the default is not to compress.
 376         With zstd compression, <code class="literal">long</code> mode may improve the
 377         compression ratio, at the cost of increased memory use.
 378        </p><p>
 379         The tar archive format currently does not support compression at all.
 380        </p></dd><dt><span class="term"><code class="option">--binary-upgrade</code></span></dt><dd><p>
 381         This option is for use by in-place upgrade utilities.  Its use
 382         for other purposes is not recommended or supported.  The
 383         behavior of the option may change in future releases without
 384         notice.
 385        </p></dd><dt><span class="term"><code class="option">--column-inserts</code><br /></span><span class="term"><code class="option">--attribute-inserts</code></span></dt><dd><p>
 386         Dump data as <code class="command">INSERT</code> commands with explicit
 387         column names (<code class="literal">INSERT INTO
 388         <em class="replaceable"><code>table</code></em>
 389         (<em class="replaceable"><code>column</code></em>, ...) VALUES
 390         ...</code>).  This will make restoration very slow; it is mainly
 391         useful for making dumps that can be loaded into
 392         non-<span class="productname">PostgreSQL</span> databases.
 393         Any error during restoring will cause only rows that are part of the
 394         problematic <code class="command">INSERT</code> to be lost, rather than the
 395         entire table contents.
 396        </p></dd><dt><span class="term"><code class="option">--disable-dollar-quoting</code></span></dt><dd><p>
 397         This option disables the use of dollar quoting for function bodies,
 398         and forces them to be quoted using SQL standard string syntax.
 399        </p></dd><dt><span class="term"><code class="option">--disable-triggers</code></span></dt><dd><p>
 400         This option is relevant only when creating a dump that includes data
 401         but does not include schema.
 402         It instructs <span class="application">pg_dump</span> to include commands
 403         to temporarily disable triggers on the target tables while
 404         the data is restored.  Use this if you have referential
 405         integrity checks or other triggers on the tables that you
 406         do not want to invoke during data restore.
 407        </p><p>
 408         Presently, the commands emitted for <code class="option">--disable-triggers</code>
 409         must be done as superuser.  So, you should also specify
 410         a superuser name with <code class="option">-S</code>, or preferably be careful to
 411         start the resulting script as a superuser.
 412        </p><p>
 413         This option is ignored when emitting an archive (non-text) output
 414         file.  For the archive formats, you can specify the option when you
 415         call <code class="command">pg_restore</code>.
 416        </p></dd><dt><span class="term"><code class="option">--enable-row-security</code></span></dt><dd><p>
 417         This option is relevant only when dumping the contents of a table
 418         which has row security.  By default, <span class="application">pg_dump</span> will set
 419         <a class="xref" href="runtime-config-client.html#GUC-ROW-SECURITY">row_security</a> to off, to ensure
 420         that all data is dumped from the table.  If the user does not have
 421         sufficient privileges to bypass row security, then an error is thrown.
 422         This parameter instructs <span class="application">pg_dump</span> to set
 423         <a class="xref" href="runtime-config-client.html#GUC-ROW-SECURITY">row_security</a> to on instead, allowing the user
 424         to dump the parts of the contents of the table that they have access to.
 425        </p><p>
 426         Note that if you use this option currently, you probably also want
 427         the dump be in <code class="command">INSERT</code> format, as the
 428         <code class="command">COPY FROM</code> during restore does not support row security.
 429        </p></dd><dt><span class="term"><code class="option">--exclude-extension=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
 430         Do not dump any extensions matching <em class="replaceable"><code>pattern</code></em>.  The pattern is
 431         interpreted according to the same rules as for <code class="option">-e</code>.
 432         <code class="option">--exclude-extension</code> can be given more than once to exclude extensions
 433         matching any of several patterns.
 434        </p><p>
 435         When both <code class="option">-e</code> and <code class="option">--exclude-extension</code> are given, the behavior
 436         is to dump just the extensions that match at least one <code class="option">-e</code>
 437         switch but no <code class="option">--exclude-extension</code> switches.  If <code class="option">--exclude-extension</code>
 438         appears without <code class="option">-e</code>, then extensions matching <code class="option">--exclude-extension</code> are
 439         excluded from what is otherwise a normal dump.
 440        </p></dd><dt><span class="term"><code class="option">--exclude-table-and-children=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
 441         This is the same as
 442         the <code class="option">-T</code>/<code class="option">--exclude-table</code> option,
 443         except that it also excludes any partitions or inheritance child
 444         tables of the table(s) matching the
 445         <em class="replaceable"><code>pattern</code></em>.
 446        </p></dd><dt><span class="term"><code class="option">--exclude-table-data=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
 447         Do not dump data for any tables matching <em class="replaceable"><code>pattern</code></em>. The pattern is
 448         interpreted according to the same rules as for <code class="option">-t</code>.
 449         <code class="option">--exclude-table-data</code> can be given more than once to
 450         exclude tables matching any of several patterns. This option is
 451         useful when you need the definition of a particular table even
 452         though you do not need the data in it.
 453        </p><p>
 454         To exclude data for all tables in the database, see <code class="option">--schema-only</code>
 455         or <code class="option">--statistics-only</code>.
 456        </p></dd><dt><span class="term"><code class="option">--exclude-table-data-and-children=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
 457         This is the same as the <code class="option">--exclude-table-data</code> option,
 458         except that it also excludes data of any partitions or inheritance
 459         child tables of the table(s) matching the
 460         <em class="replaceable"><code>pattern</code></em>.
 461        </p></dd><dt><span class="term"><code class="option">--extra-float-digits=<em class="replaceable"><code>ndigits</code></em></code></span></dt><dd><p>
 462         Use the specified value of <code class="option">extra_float_digits</code> when dumping
 463         floating-point data, instead of the maximum available precision.
 464         Routine dumps made for backup purposes should not use this option.
 465        </p></dd><dt><span class="term"><code class="option">--filter=<em class="replaceable"><code>filename</code></em></code></span></dt><dd><p>
 466         Specify a filename from which to read patterns for objects to include
 467         or exclude from the dump. The patterns are interpreted according to the
 468         same rules as the corresponding options:
 469         <code class="option">-t</code>/<code class="option">--table</code>,
 470         <code class="option">--table-and-children</code>,
 471         <code class="option">-T</code>/<code class="option">--exclude-table</code>, and
 472         <code class="option">--exclude-table-and-children</code> for tables,
 473         <code class="option">-n</code>/<code class="option">--schema</code> and
 474         <code class="option">-N</code>/<code class="option">--exclude-schema</code> for schemas,
 475         <code class="option">--include-foreign-data</code> for data on foreign servers,
 476         <code class="option">--exclude-table-data</code> and
 477         <code class="option">--exclude-table-data-and-children</code> for table data, and
 478         <code class="option">-e</code>/<code class="option">--extension</code> and
 479         <code class="option">--exclude-extension</code> for extensions.
 480         To read from <code class="literal">STDIN</code>, use <code class="filename">-</code> as the
 481         filename.  The <code class="option">--filter</code> option can be specified in
 482         conjunction with the above listed options for including or excluding
 483         objects, and can also be specified more than once for multiple filter
 484         files.
 485        </p><p>
 486         The file lists one object pattern per row, with the following format:
 487 </p><pre class="synopsis">
 488 { include | exclude } { extension | foreign_data | table | table_and_children | table_data | table_data_and_children | schema } <em class="replaceable"><code>PATTERN</code></em>
 489 </pre><p>
 490        </p><p>
 491         The first keyword specifies whether the objects matched by the pattern
 492         are to be included or excluded. The second keyword specifies the type
 493         of object to be filtered using the pattern:
 494         </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 495            <code class="literal">extension</code>: extensions. This works like the
 496            <code class="option">-e</code>/<code class="option">--extension</code> or
 497            <code class="option">--exclude-extension</code> option.
 498           </p></li><li class="listitem"><p>
 499            <code class="literal">foreign_data</code>: data on foreign servers. This works like
 500            the <code class="option">--include-foreign-data</code> option. This keyword can
 501            only be used with the <code class="literal">include</code> keyword.
 502           </p></li><li class="listitem"><p>
 503            <code class="literal">table</code>: tables. This works like the
 504            <code class="option">-t</code>/<code class="option">--table</code> or
 505            <code class="option">-T</code>/<code class="option">--exclude-table</code> option.
 506           </p></li><li class="listitem"><p>
 507            <code class="literal">table_and_children</code>: tables including any partitions
 508            or inheritance child tables. This works like the
 509            <code class="option">--table-and-children</code> or
 510            <code class="option">--exclude-table-and-children</code> option.
 511           </p></li><li class="listitem"><p>
 512            <code class="literal">table_data</code>: table data of any tables matching
 513            <em class="replaceable"><code>pattern</code></em>. This works like the
 514            <code class="option">--exclude-table-data</code> option. This keyword can only
 515            be used with the <code class="literal">exclude</code> keyword.
 516           </p></li><li class="listitem"><p>
 517            <code class="literal">table_data_and_children</code>: table data of any tables
 518            matching <em class="replaceable"><code>pattern</code></em> as well as any partitions
 519            or inheritance children of the table(s). This works like the
 520            <code class="option">--exclude-table-data-and-children</code> option. This
 521            keyword can only be used with the <code class="literal">exclude</code> keyword.
 522           </p></li><li class="listitem"><p>
 523            <code class="literal">schema</code>: schemas. This works like the
 524            <code class="option">-n</code>/<code class="option">--schema</code> or
 525            <code class="option">-N</code>/<code class="option">--exclude-schema</code> option.
 526           </p></li></ul></div><p>
 527        </p><p>
 528         Lines starting with <code class="literal">#</code> are considered comments and
 529         ignored. Comments can be placed after an object pattern row as well.
 530         Blank lines are also ignored. See <a class="xref" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns">Patterns</a>
 531         for how to perform quoting in patterns.
 532        </p><p>
 533         Example files are listed below in the <a class="xref" href="app-pgdump.html#PG-DUMP-EXAMPLES" title="Examples">Examples</a>
 534         section.
 535        </p></dd><dt><span class="term"><code class="option">--if-exists</code></span></dt><dd><p>
 536         Use <code class="literal">DROP ... IF EXISTS</code> commands to drop objects
 537         in <code class="option">--clean</code> mode.  This suppresses <span class="quote">“<span class="quote">does not
 538         exist</span>”</span> errors that might otherwise be reported.  This
 539         option is not valid unless <code class="option">--clean</code> is also
 540         specified.
 541        </p></dd><dt><span class="term"><code class="option">--include-foreign-data=<em class="replaceable"><code>foreignserver</code></em></code></span></dt><dd><p>
 542         Dump the data for any foreign table with a foreign server
 543         matching <em class="replaceable"><code>foreignserver</code></em>
 544         pattern. Multiple foreign servers can be selected by writing multiple
 545         <code class="option">--include-foreign-data</code> switches.
 546         Also, the <em class="replaceable"><code>foreignserver</code></em> parameter is
 547         interpreted as a pattern according to the same rules used by
 548         <span class="application">psql</span>'s <code class="literal">\d</code> commands
 549         (see <a class="xref" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns">Patterns</a>),
 550         so multiple foreign servers can also be selected by writing wildcard characters
 551         in the pattern.  When using wildcards, be careful to quote the pattern
 552         if needed to prevent the shell from expanding the wildcards; see
 553         <a class="xref" href="app-pgdump.html#PG-DUMP-EXAMPLES" title="Examples">Examples</a> below.
 554         The only exception is that an empty pattern is disallowed.
 555        </p><div class="note"><h3 class="title">Note</h3><p>
 556          Using wildcards in <code class="option">--include-foreign-data</code> may result
 557          in access to unexpected foreign servers. Also, to use this option securely,
 558          make sure that the named server must have a trusted owner.
 559         </p></div><div class="note"><h3 class="title">Note</h3><p>
 560          When <code class="option">--include-foreign-data</code> is specified,
 561          <span class="application">pg_dump</span> does not check that the foreign
 562          table is writable.  Therefore, there is no guarantee that the
 563          results of a foreign table dump can be successfully restored.
 564         </p></div></dd><dt><span class="term"><code class="option">--inserts</code></span></dt><dd><p>
 565         Dump data as <code class="command">INSERT</code> commands (rather
 566         than <code class="command">COPY</code>).  This will make restoration very slow;
 567         it is mainly useful for making dumps that can be loaded into
 568         non-<span class="productname">PostgreSQL</span> databases.
 569         Any error during restoring will cause only rows that are part of the
 570         problematic <code class="command">INSERT</code> to be lost, rather than the
 571         entire table contents.  Note that the restore might fail altogether if
 572         you have rearranged column order.  The
 573         <code class="option">--column-inserts</code> option is safe against column order
 574         changes, though even slower.
 575        </p></dd><dt><span class="term"><code class="option">--load-via-partition-root</code></span></dt><dd><p>
 576         When dumping data for a table partition, make
 577         the <code class="command">COPY</code> or <code class="command">INSERT</code> statements
 578         target the root of the partitioning hierarchy that contains it, rather
 579         than the partition itself.  This causes the appropriate partition to
 580         be re-determined for each row when the data is loaded.  This may be
 581         useful when restoring data on a server where rows do not always fall
 582         into the same partitions as they did on the original server.  That
 583         could happen, for example, if the partitioning column is of type text
 584         and the two systems have different definitions of the collation used
 585         to sort the partitioning column.
 586        </p></dd><dt><span class="term"><code class="option">--lock-wait-timeout=<em class="replaceable"><code>timeout</code></em></code></span></dt><dd><p>
 587         Do not wait forever to acquire shared table locks at the beginning of
 588         the dump. Instead fail if unable to lock a table within the specified
 589         <em class="replaceable"><code>timeout</code></em>. The timeout may be
 590         specified in any of the formats accepted by <code class="command">SET
 591         statement_timeout</code>.  (Allowed formats vary depending on the server
 592         version you are dumping from, but an integer number of milliseconds
 593         is accepted by all versions.)
 594        </p></dd><dt><span class="term"><code class="option">--no-comments</code></span></dt><dd><p>
 595         Do not dump <code class="command">COMMENT</code> commands.
 596        </p></dd><dt><span class="term"><code class="option">--no-data</code></span></dt><dd><p>
 597         Do not dump data.
 598        </p></dd><dt><span class="term"><code class="option">--no-policies</code></span></dt><dd><p>
 599         Do not dump row security policies.
 600        </p></dd><dt><span class="term"><code class="option">--no-publications</code></span></dt><dd><p>
 601         Do not dump publications.
 602        </p></dd><dt><span class="term"><code class="option">--no-schema</code></span></dt><dd><p>
 603         Do not dump schema (data definitions).
 604        </p></dd><dt><span class="term"><code class="option">--no-security-labels</code></span></dt><dd><p>
 605         Do not dump security labels.
 606        </p></dd><dt><span class="term"><code class="option">--no-statistics</code></span></dt><dd><p>
 607         Do not dump statistics. This is the default.
 608        </p></dd><dt><span class="term"><code class="option">--no-subscriptions</code></span></dt><dd><p>
 609         Do not dump subscriptions.
 610        </p></dd><dt><span class="term"><code class="option">--no-sync</code></span></dt><dd><p>
 611         By default, <code class="command">pg_dump</code> will wait for all files
 612         to be written safely to disk.  This option causes
 613         <code class="command">pg_dump</code> to return without waiting, which is
 614         faster, but means that a subsequent operating system crash can leave
 615         the dump corrupt.  Generally, this option is useful for testing
 616         but should not be used when dumping data from production installation.
 617        </p></dd><dt><span class="term"><code class="option">--no-table-access-method</code></span></dt><dd><p>
 618         Do not output commands to select table access methods.
 619         With this option, all objects will be created with whichever
 620         table access method is the default during restore.
 621        </p><p>
 622         This option is ignored when emitting an archive (non-text) output
 623         file.  For the archive formats, you can specify the option when you
 624         call <code class="command">pg_restore</code>.
 625        </p></dd><dt><span class="term"><code class="option">--no-tablespaces</code></span></dt><dd><p>
 626         Do not output commands to select tablespaces.
 627         With this option, all objects will be created in whichever
 628         tablespace is the default during restore.
 629        </p><p>
 630         This option is ignored when emitting an archive (non-text) output
 631         file.  For the archive formats, you can specify the option when you
 632         call <code class="command">pg_restore</code>.
 633        </p></dd><dt><span class="term"><code class="option">--no-toast-compression</code></span></dt><dd><p>
 634         Do not output commands to set <acronym class="acronym">TOAST</acronym> compression
 635         methods.
 636         With this option, all columns will be restored with the default
 637         compression setting.
 638        </p></dd><dt><span class="term"><code class="option">--no-unlogged-table-data</code></span></dt><dd><p>
 639         Do not dump the contents of unlogged tables and sequences.  This
 640         option has no effect on whether or not the table and sequence
 641         definitions (schema) are dumped; it only suppresses dumping the table
 642         and sequence data. Data in unlogged tables and sequences
 643         is always excluded when dumping from a standby server.
 644        </p></dd><dt><span class="term"><code class="option">--on-conflict-do-nothing</code></span></dt><dd><p>
 645         Add <code class="literal">ON CONFLICT DO NOTHING</code> to
 646         <code class="command">INSERT</code> commands.
 647         This option is not valid unless <code class="option">--inserts</code>,
 648         <code class="option">--column-inserts</code> or
 649         <code class="option">--rows-per-insert</code> is also specified.
 650        </p></dd><dt><span class="term"><code class="option">--quote-all-identifiers</code></span></dt><dd><p>
 651         Force quoting of all identifiers.  This option is recommended when
 652         dumping a database from a server whose <span class="productname">PostgreSQL</span>
 653         major version is different from <span class="application">pg_dump</span>'s, or when
 654         the output is intended to be loaded into a server of a different
 655         major version.  By default, <span class="application">pg_dump</span> quotes only
 656         identifiers that are reserved words in its own major version.
 657         This sometimes results in compatibility issues when dealing with
 658         servers of other versions that may have slightly different sets
 659         of reserved words.  Using <code class="option">--quote-all-identifiers</code> prevents
 660         such issues, at the price of a harder-to-read dump script.
 661        </p></dd><dt><span class="term"><code class="option">--restrict-key=<em class="replaceable"><code>restrict_key</code></em></code></span></dt><dd><p>
 662         Use the provided string as the <span class="application">psql</span>
 663         <code class="command">\restrict</code> key in the dump output.  This can only be
 664         specified for plain-text dumps, i.e., when <code class="option">--format</code> is
 665         set to <code class="literal">plain</code> or the <code class="option">--format</code> option
 666         is omitted.  If no restrict key is specified,
 667         <span class="application">pg_dump</span> will generate a random one as
 668         needed.  Keys may contain only alphanumeric characters.
 669        </p><p>
 670         This option is primarily intended for testing purposes and other
 671         scenarios that require repeatable output (e.g., comparing dump files).
 672         It is not recommended for general use, as a malicious server with
 673         advance knowledge of the key may be able to inject arbitrary code that
 674         will be executed on the machine that runs
 675         <span class="application">psql</span> with the dump output.
 676        </p></dd><dt><span class="term"><code class="option">--rows-per-insert=<em class="replaceable"><code>nrows</code></em></code></span></dt><dd><p>
 677         Dump data as <code class="command">INSERT</code> commands (rather than
 678         <code class="command">COPY</code>).  Controls the maximum number of rows per
 679         <code class="command">INSERT</code> command. The value specified must be a
 680         number greater than zero.  Any error during restoring will cause only
 681         rows that are part of the problematic <code class="command">INSERT</code> to be
 682         lost, rather than the entire table contents.
 683        </p></dd><dt><span class="term"><code class="option">--section=<em class="replaceable"><code>sectionname</code></em></code></span></dt><dd><p>
 684           Only dump the named section. The section name can be
 685           <code class="option">pre-data</code>, <code class="option">data</code>, or <code class="option">post-data</code>.
 686           This option can be specified more than once to select multiple
 687           sections. The default is to dump all sections.
 688          </p><p>
 689           The data section contains actual table data, large-object
 690           contents, sequence values, and statistics for tables,
 691           materialized views, and foreign tables.
 692           Post-data items include definitions of indexes, triggers, rules,
 693           statistics for indexes, and constraints other than validated check
 694           and not-null constraints.
 695           Pre-data items include all other data definition items.
 696          </p></dd><dt><span class="term"><code class="option">--sequence-data</code></span></dt><dd><p>
 697         Include sequence data in the dump.  This is the default behavior except
 698         when <code class="option">--no-data</code>, <code class="option">--schema-only</code>, or
 699         <code class="option">--statistics-only</code> is specified.
 700        </p></dd><dt><span class="term"><code class="option">--serializable-deferrable</code></span></dt><dd><p>
 701         Use a <code class="literal">serializable</code> transaction for the dump, to
 702         ensure that the snapshot used is consistent with later database
 703         states; but do this by waiting for a point in the transaction stream
 704         at which no anomalies can be present, so that there isn't a risk of
 705         the dump failing or causing other transactions to roll back with a
 706         <code class="literal">serialization_failure</code>.  See <a class="xref" href="mvcc.html" title="Chapter 13. Concurrency Control">Chapter 13</a>
 707         for more information about transaction isolation and concurrency
 708         control.
 709        </p><p>
 710         This option is not beneficial for a dump which is intended only for
 711         disaster recovery.  It could be useful for a dump used to load a
 712         copy of the database for reporting or other read-only load sharing
 713         while the original database continues to be updated.  Without it the
 714         dump may reflect a state which is not consistent with any serial
 715         execution of the transactions eventually committed.  For example, if
 716         batch processing techniques are used, a batch may show as closed in
 717         the dump without all of the items which are in the batch appearing.
 718        </p><p>
 719         This option will make no difference if there are no read-write
 720         transactions active when pg_dump is started.  If read-write
 721         transactions are active, the start of the dump may be delayed for an
 722         indeterminate length of time.  Once running, performance with or
 723         without the switch is the same.
 724        </p></dd><dt><span class="term"><code class="option">--snapshot=<em class="replaceable"><code>snapshotname</code></em></code></span></dt><dd><p>
 725           Use the specified synchronized snapshot when making a dump of the
 726           database (see
 727           <a class="xref" href="functions-admin.html#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION-TABLE" title="Table 9.100. Snapshot Synchronization Functions">Table 9.100</a> for more
 728           details).
 729          </p><p>
 730           This option is useful when needing to synchronize the dump with
 731           a logical replication slot (see <a class="xref" href="logicaldecoding.html" title="Chapter 47. Logical Decoding">Chapter 47</a>)
 732           or with a concurrent session.
 733          </p><p>
 734           In the case of a parallel dump, the snapshot name defined by this
 735           option is used rather than taking a new snapshot.
 736          </p></dd><dt><span class="term"><code class="option">--statistics</code></span></dt><dd><p>
 737         Dump statistics.
 738        </p></dd><dt><span class="term"><code class="option">--statistics-only</code></span></dt><dd><p>
 739         Dump only the statistics, not the schema (data definitions) or data.
 740         Statistics for tables, materialized views, foreign tables,
 741         and indexes are dumped.
 742        </p></dd><dt><span class="term"><code class="option">--strict-names</code></span></dt><dd><p>
 743         Require that each
 744         extension (<code class="option">-e</code>/<code class="option">--extension</code>),
 745         schema (<code class="option">-n</code>/<code class="option">--schema</code>) and
 746         table (<code class="option">-t</code>/<code class="option">--table</code>) pattern
 747         match at least one extension/schema/table in the database to be dumped.
 748         This also applies to filters used with <code class="option">--filter</code>.
 749         Note that if none of the extension/schema/table patterns find
 750         matches, <span class="application">pg_dump</span> will generate an error
 751         even without <code class="option">--strict-names</code>.
 752        </p><p>
 753         This option has no effect
 754         on <code class="option">--exclude-extension</code>,
 755         <code class="option">-N</code>/<code class="option">--exclude-schema</code>,
 756         <code class="option">-T</code>/<code class="option">--exclude-table</code>,
 757         or <code class="option">--exclude-table-data</code>.  An exclude pattern failing
 758         to match any objects is not considered an error.
 759        </p></dd><dt><span class="term"><code class="option">--sync-method=<em class="replaceable"><code>method</code></em></code></span></dt><dd><p>
 760         When set to <code class="literal">fsync</code>, which is the default,
 761         <code class="command">pg_dump --format=directory</code> will recursively open and
 762         synchronize all files in the archive directory.
 763        </p><p>
 764         On Linux, <code class="literal">syncfs</code> may be used instead to ask the
 765         operating system to synchronize the whole file system that contains the
 766         archive directory.  See <a class="xref" href="runtime-config-error-handling.html#GUC-RECOVERY-INIT-SYNC-METHOD">recovery_init_sync_method</a>
 767         for information about the caveats to be aware of when using
 768         <code class="literal">syncfs</code>.
 769        </p><p>
 770         This option has no effect when <code class="option">--no-sync</code> is used or
 771         <code class="option">--format</code> is not set to <code class="literal">directory</code>.
 772        </p></dd><dt><span class="term"><code class="option">--table-and-children=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
 773         This is the same as
 774         the <code class="option">-t</code>/<code class="option">--table</code> option,
 775         except that it also includes any partitions or inheritance child
 776         tables of the table(s) matching the
 777         <em class="replaceable"><code>pattern</code></em>.
 778        </p></dd><dt><span class="term"><code class="option">--use-set-session-authorization</code></span></dt><dd><p>
 779         Output SQL-standard <code class="command">SET SESSION AUTHORIZATION</code> commands
 780         instead of <code class="command">ALTER OWNER</code> commands to determine object
 781         ownership.  This makes the dump more standards-compatible, but
 782         depending on the history of the objects in the dump, might not restore
 783         properly.  Also, a dump using <code class="command">SET SESSION AUTHORIZATION</code>
 784         will certainly require superuser privileges to restore correctly,
 785         whereas <code class="command">ALTER OWNER</code> requires lesser privileges.
 786        </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
 787        Show help about <span class="application">pg_dump</span> command line
 788        arguments, and exit.
 789        </p></dd></dl></div><p>
 790    </p><p>
 791     The following command-line options control the database connection parameters.
 792
 793     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-d <em class="replaceable"><code>dbname</code></em></code><br /></span><span class="term"><code class="option">--dbname=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
 794        Specifies the name of the database to connect to. This is
 795        equivalent to specifying <em class="replaceable"><code>dbname</code></em> as the first non-option
 796        argument on the command line.  The <em class="replaceable"><code>dbname</code></em>
 797        can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="32.1.1. Connection Strings">connection string</a>.
 798        If so, connection string parameters will override any conflicting
 799        command line options.
 800       </p></dd><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
 801         Specifies the host name of the machine on which the server is
 802         running.  If the value begins with a slash, it is used as the
 803         directory for the Unix domain socket. The default is taken
 804         from the <code class="envar">PGHOST</code> environment variable, if set,
 805         else a Unix domain socket connection is attempted.
 806        </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
 807         Specifies the TCP port or local Unix domain socket file
 808         extension on which the server is listening for connections.
 809         Defaults to the <code class="envar">PGPORT</code> environment variable, if
 810         set, or a compiled-in default.
 811        </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
 812         User name to connect as.
 813        </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
 814         Never issue a password prompt.  If the server requires
 815         password authentication and a password is not available by
 816         other means such as a <code class="filename">.pgpass</code> file, the
 817         connection attempt will fail.  This option can be useful in
 818         batch jobs and scripts where no user is present to enter a
 819         password.
 820        </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
 821         Force <span class="application">pg_dump</span> to prompt for a
 822         password before connecting to a database.
 823        </p><p>
 824         This option is never essential, since
 825         <span class="application">pg_dump</span> will automatically prompt
 826         for a password if the server demands password authentication.
 827         However, <span class="application">pg_dump</span> will waste a
 828         connection attempt finding out that the server wants a password.
 829         In some cases it is worth typing <code class="option">-W</code> to avoid the extra
 830         connection attempt.
 831        </p></dd><dt><span class="term"><code class="option">--role=<em class="replaceable"><code>rolename</code></em></code></span></dt><dd><p>
 832         Specifies a role name to be used to create the dump.
 833         This option causes <span class="application">pg_dump</span> to issue a
 834         <code class="command">SET ROLE</code> <em class="replaceable"><code>rolename</code></em>
 835         command after connecting to the database. It is useful when the
 836         authenticated user (specified by <code class="option">-U</code>) lacks privileges
 837         needed by <span class="application">pg_dump</span>, but can switch to a role with
 838         the required rights.  Some installations have a policy against
 839         logging in directly as a superuser, and use of this option allows
 840         dumps to be made without violating the policy.
 841        </p></dd></dl></div><p>
 842    </p></div><div class="refsect1" id="id-1.9.4.14.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGDATABASE</code><br /></span><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGOPTIONS</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
 843       Default connection parameters.
 844      </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
 845       Specifies whether to use color in diagnostic messages. Possible values
 846       are <code class="literal">always</code>, <code class="literal">auto</code> and
 847       <code class="literal">never</code>.
 848      </p></dd></dl></div><p>
 849    This utility, like most other <span class="productname">PostgreSQL</span> utilities,
 850    also uses the environment variables supported by <span class="application">libpq</span>
 851    (see <a class="xref" href="libpq-envars.html" title="32.15. Environment Variables">Section 32.15</a>).
 852   </p></div><div class="refsect1" id="APP-PGDUMP-DIAGNOSTICS"><h2>Diagnostics</h2><p>
 853    <span class="application">pg_dump</span> internally executes
 854    <code class="command">SELECT</code> statements. If you have problems running
 855    <span class="application">pg_dump</span>, make sure you are able to
 856    select information from the database using, for example, <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a>.  Also, any default connection settings and environment
 857    variables used by the <span class="application">libpq</span> front-end
 858    library will apply.
 859   </p><p>
 860    The database activity of <span class="application">pg_dump</span> is
 861    normally collected by the cumulative statistics system.  If this is
 862    undesirable, you can set parameter <code class="varname">track_counts</code>
 863    to false via <code class="envar">PGOPTIONS</code> or the <code class="literal">ALTER
 864    USER</code> command.
 865   </p></div><div class="refsect1" id="PG-DUMP-NOTES"><h2>Notes</h2><p>
 866    If your database cluster has any local additions to the <code class="literal">template1</code> database,
 867    be careful to restore the output of <span class="application">pg_dump</span> into a
 868    truly empty database; otherwise you are likely to get errors due to
 869    duplicate definitions of the added objects.  To make an empty database
 870    without any local additions, copy from <code class="literal">template0</code> not <code class="literal">template1</code>,
 871    for example:
 872 </p><pre class="programlisting">
 873 CREATE DATABASE foo WITH TEMPLATE template0;
 874 </pre><p>
 875   </p><p>
 876    When a dump without schema is chosen and the option <code class="option">--disable-triggers</code>
 877    is used, <span class="application">pg_dump</span> emits commands
 878    to disable triggers on user tables before inserting the data,
 879    and then commands to re-enable them after the data has been
 880    inserted.  If the restore is stopped in the middle, the system
 881    catalogs might be left in the wrong state.
 882   </p><p>
 883    If <code class="option">--statistics</code> is specified,
 884    <code class="command">pg_dump</code> will include most optimizer statistics in the
 885    resulting dump file.  However, some statistics may not be included, such as
 886    those created explicitly with <a class="xref" href="sql-createstatistics.html" title="CREATE STATISTICS"><span class="refentrytitle">CREATE STATISTICS</span></a> or
 887    custom statistics added by an extension.  Therefore, it may be useful to
 888    run <code class="command">ANALYZE</code> after restoring from a dump file to ensure
 889    optimal performance; see <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-STATISTICS" title="24.1.3. Updating Planner Statistics">Section 24.1.3</a> and <a class="xref" href="routine-vacuuming.html#AUTOVACUUM" title="24.1.6. The Autovacuum Daemon">Section 24.1.6</a> for more information.
 890   </p><p>
 891    Because <span class="application">pg_dump</span> is used to transfer data
 892    to newer versions of <span class="productname">PostgreSQL</span>, the output of
 893    <span class="application">pg_dump</span> can be expected to load into
 894    <span class="productname">PostgreSQL</span> server versions newer than
 895    <span class="application">pg_dump</span>'s version.  <span class="application">pg_dump</span> can also
 896    dump from <span class="productname">PostgreSQL</span> servers older than its own version.
 897    (Currently, servers back to version 9.2 are supported.)
 898    However, <span class="application">pg_dump</span> cannot dump from
 899    <span class="productname">PostgreSQL</span> servers newer than its own major version;
 900    it will refuse to even try, rather than risk making an invalid dump.
 901    Also, it is not guaranteed that <span class="application">pg_dump</span>'s output can
 902    be loaded into a server of an older major version — not even if the
 903    dump was taken from a server of that version.  Loading a dump file
 904    into an older server may require manual editing of the dump file
 905    to remove syntax not understood by the older server.
 906    Use of the <code class="option">--quote-all-identifiers</code> option is recommended
 907    in cross-version cases, as it can prevent problems arising from varying
 908    reserved-word lists in different <span class="productname">PostgreSQL</span> versions.
 909   </p><p>
 910    When dumping logical replication subscriptions,
 911    <span class="application">pg_dump</span> will generate <code class="command">CREATE
 912    SUBSCRIPTION</code> commands that use the <code class="literal">connect = false</code>
 913    option, so that restoring the subscription does not make remote connections
 914    for creating a replication slot or for initial table copy.  That way, the
 915    dump can be restored without requiring network access to the remote
 916    servers.  It is then up to the user to reactivate the subscriptions in a
 917    suitable way.  If the involved hosts have changed, the connection
 918    information might have to be changed.  It might also be appropriate to
 919    truncate the target tables before initiating a new full table copy.  If users
 920    intend to copy initial data during refresh they must create the slot with
 921    <code class="literal">two_phase = false</code>.  After the initial sync, the
 922    <a class="link" href="sql-createsubscription.html#SQL-CREATESUBSCRIPTION-PARAMS-WITH-TWO-PHASE"><code class="literal">two_phase</code></a>
 923    option will be automatically enabled by the subscriber if the subscription
 924    had been originally created with <code class="literal">two_phase = true</code> option.
 925   </p><p>
 926    It is generally recommended to use the <code class="option">-X</code>
 927    (<code class="option">--no-psqlrc</code>) option when restoring a database from a
 928    plain-text <span class="application">pg_dump</span> script to ensure a clean
 929    restore process and prevent potential conflicts with
 930    non-default <span class="application">psql</span> configurations.
 931   </p></div><div class="refsect1" id="PG-DUMP-EXAMPLES"><h2>Examples</h2><p>
 932    To dump a database called <code class="literal">mydb</code> into an SQL-script file:
 933 </p><pre class="screen">
 934 <code class="prompt">$</code> <strong class="userinput"><code>pg_dump mydb &gt; db.sql</code></strong>
 935 </pre><p>
 936   </p><p>
 937    To reload such a script into a (freshly created) database named
 938    <code class="literal">newdb</code>:
 939
 940 </p><pre class="screen">
 941 <code class="prompt">$</code> <strong class="userinput"><code>psql -X -d newdb -f db.sql</code></strong>
 942 </pre><p>
 943   </p><p>
 944    To dump a database into a custom-format archive file:
 945
 946 </p><pre class="screen">
 947 <code class="prompt">$</code> <strong class="userinput"><code>pg_dump -Fc mydb &gt; db.dump</code></strong>
 948 </pre><p>
 949   </p><p>
 950    To dump a database into a directory-format archive:
 951
 952 </p><pre class="screen">
 953 <code class="prompt">$</code> <strong class="userinput"><code>pg_dump -Fd mydb -f dumpdir</code></strong>
 954 </pre><p>
 955   </p><p>
 956    To dump a database into a directory-format archive in parallel with
 957    5 worker jobs:
 958
 959 </p><pre class="screen">
 960 <code class="prompt">$</code> <strong class="userinput"><code>pg_dump -Fd mydb -j 5 -f dumpdir</code></strong>
 961 </pre><p>
 962   </p><p>
 963    To reload an archive file into a (freshly created) database named
 964    <code class="literal">newdb</code>:
 965
 966 </p><pre class="screen">
 967 <code class="prompt">$</code> <strong class="userinput"><code>pg_restore -d newdb db.dump</code></strong>
 968 </pre><p>
 969   </p><p>
 970    To reload an archive file into the same database it was dumped from,
 971    discarding the current contents of that database:
 972
 973 </p><pre class="screen">
 974 <code class="prompt">$</code> <strong class="userinput"><code>pg_restore -d postgres --clean --create db.dump</code></strong>
 975 </pre><p>
 976   </p><p>
 977    To dump a single table named <code class="literal">mytab</code>:
 978
 979 </p><pre class="screen">
 980 <code class="prompt">$</code> <strong class="userinput"><code>pg_dump -t mytab mydb &gt; db.sql</code></strong>
 981 </pre><p>
 982   </p><p>
 983    To dump all tables whose names start with <code class="literal">emp</code> in the
 984    <code class="literal">detroit</code> schema, except for the table named
 985    <code class="literal">employee_log</code>:
 986
 987 </p><pre class="screen">
 988 <code class="prompt">$</code> <strong class="userinput"><code>pg_dump -t 'detroit.emp*' -T detroit.employee_log mydb &gt; db.sql</code></strong>
 989 </pre><p>
 990   </p><p>
 991    To dump all schemas whose names start with <code class="literal">east</code> or
 992    <code class="literal">west</code> and end in <code class="literal">gsm</code>, excluding any schemas whose
 993    names contain the word <code class="literal">test</code>:
 994
 995 </p><pre class="screen">
 996 <code class="prompt">$</code> <strong class="userinput"><code>pg_dump -n 'east*gsm' -n 'west*gsm' -N '*test*' mydb &gt; db.sql</code></strong>
 997 </pre><p>
 998   </p><p>
 999    The same, using regular expression notation to consolidate the switches:
1000
1001 </p><pre class="screen">
1002 <code class="prompt">$</code> <strong class="userinput"><code>pg_dump -n '(east|west)*gsm' -N '*test*' mydb &gt; db.sql</code></strong>
1003 </pre><p>
1004   </p><p>
1005    To dump all database objects except for tables whose names begin with
1006    <code class="literal">ts_</code>:
1007
1008 </p><pre class="screen">
1009 <code class="prompt">$</code> <strong class="userinput"><code>pg_dump -T 'ts_*' mydb &gt; db.sql</code></strong>
1010 </pre><p>
1011   </p><p>
1012    To specify an upper-case or mixed-case name in <code class="option">-t</code> and related
1013    switches, you need to double-quote the name; else it will be folded to
1014    lower case (see <a class="xref" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns">Patterns</a>).  But
1015    double quotes are special to the shell, so in turn they must be quoted.
1016    Thus, to dump a single table with a mixed-case name, you need something
1017    like
1018
1019 </p><pre class="screen">
1020 <code class="prompt">$</code> <strong class="userinput"><code>pg_dump -t "\"MixedCaseName\"" mydb &gt; mytab.sql</code></strong>
1021 </pre><p>
1022    To dump all tables whose names start with <code class="literal">mytable</code>, except
1023    for table <code class="literal">mytable2</code>, specify a filter file
1024    <code class="filename">filter.txt</code> like:
1025 </p><pre class="programlisting">
1026 include table mytable*
1027 exclude table mytable2
1028 </pre><p>
1029
1030 </p><pre class="screen">
1031 <code class="prompt">$</code> <strong class="userinput"><code>pg_dump --filter=filter.txt mydb &gt; db.sql</code></strong>
1032 </pre></div><div class="refsect1" id="id-1.9.4.14.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-pg-dumpall.html" title="pg_dumpall"><span class="refentrytitle"><span class="application">pg_dumpall</span></span></a>, <a class="xref" href="app-pgrestore.html" title="pg_restore"><span class="refentrytitle"><span class="application">pg_restore</span></span></a>, <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pgconfig.html" title="pg_config">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pg-dumpall.html" title="pg_dumpall">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_config</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_dumpall</span></td></tr></table></div></body></html>