Skip to content

P
Postgres FD Implementation
Commit 3439e40f authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

Put options in some sensible order 

For the --help output and reference pages of pg_dump, pg_dumpall,
pg_restore, put the options in some consistent, mostly alphabetical,
and consistent order, rather than newest option last or something like
that.
parent 8c3604ae
Hide whitespace changes
Inline Side-by-side
Showing with 197 additions and 197 deletions
doc/src/sgml/ref/pg_dump.sgml
View file @ 3439e40f
......@@ -558,25 +558,6 @@ PostgreSQL documentation
</listitem>
</varlistentry>
<varlistentry>
<term><option>--inserts</option></term>
<listitem>
<para>
Dump data as <command>INSERT</command> commands (rather
than <command>COPY</command>). This will make restoration very slow;
it is mainly useful for making dumps that can be loaded into
non-<productname>PostgreSQL</productname> 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 <option>--column-inserts</option> option is safe against column
order changes, though even slower.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--column-inserts</option></term>
<term><option>--attribute-inserts</option></term>
......@@ -633,6 +614,25 @@ PostgreSQL documentation
</listitem>
</varlistentry>
<varlistentry>
<term><option>--inserts</option></term>
<listitem>
<para>
Dump data as <command>INSERT</command> commands (rather
than <command>COPY</command>). This will make restoration very slow;
it is mainly useful for making dumps that can be loaded into
non-<productname>PostgreSQL</productname> 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 <option>--column-inserts</option> option is safe against column
order changes, though even slower.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--lock-wait-timeout=<replaceable class="parameter">timeout</replaceable></option></term>
<listitem>
......@@ -650,36 +650,10 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term><option>--serializable-deferrable</option></term>
<term><option>--no-security-labels</option></term>
<listitem>
<para>
Use a <literal>serializable</literal> 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't a risk of
the dump failing or causing other transactions to roll back with a
<literal>serialization_failure</literal>. See <xref linkend="mvcc">
for more information about transaction isolation and concurrency
control.
</para>
<para>
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.
</para>
<para>
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.
Do not dump security labels.
</para>
</listitem>
</varlistentry>
......@@ -702,47 +676,73 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term><option>--no-security-labels</option></term>
<term><option>--no-unlogged-table-data</option></term>
<listitem>
<para>
Do not dump security labels.
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--use-set-session-authorization</></term>
<term><option>--quote-all-identifiers</></term>
<listitem>
<para>
Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands
instead of <command>ALTER OWNER</> 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 <command>SET SESSION AUTHORIZATION</>
will certainly require superuser privileges to restore correctly,
whereas <command>ALTER OWNER</> requires lesser privileges.
Force quoting of all identifiers. This may be useful when dumping a
database for migration to a future version that may have introduced
additional keywords.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-unlogged-table-data</option></term>
<term><option>--serializable-deferrable</option></term>
<listitem>
<para>
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.
Use a <literal>serializable</literal> 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't a risk of
the dump failing or causing other transactions to roll back with a
<literal>serialization_failure</literal>. See <xref linkend="mvcc">
for more information about transaction isolation and concurrency
control.
</para>
<para>
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.
</para>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--quote-all-identifiers</></term>
<term><option>--use-set-session-authorization</></term>
<listitem>
<para>
Force quoting of all identifiers. This may be useful when dumping a
database for migration to a future version that may have introduced
additional keywords.
Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands
instead of <command>ALTER OWNER</> 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 <command>SET SESSION AUTHORIZATION</>
will certainly require superuser privileges to restore correctly,
whereas <command>ALTER OWNER</> requires lesser privileges.
</para>
</listitem>
</varlistentry>
......
doc/src/sgml/ref/pg_dumpall.sgml
View file @ 3439e40f
......@@ -164,54 +164,6 @@ PostgreSQL documentation
</listitem>
</varlistentry>
<varlistentry>
<term><option>--lock-wait-timeout=<replaceable class="parameter">timeout</replaceable></option></term>
<listitem>
<para>
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
<replaceable class="parameter">timeout</>. The timeout may be
specified in any of the formats accepted by <command>SET
statement_timeout</>. 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-tablespaces</option></term>
<listitem>
<para>
Do not output commands to create tablespaces nor select tablespaces
for objects.
With this option, all objects will be created in whichever
tablespace is the default during restore.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-security-labels</option></term>
<listitem>
<para>
Do not dump security labels.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-unlogged-table-data</option></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-r</option></term>
<term><option>--roles-only</option></term>
......@@ -301,21 +253,6 @@ PostgreSQL documentation
</listitem>
</varlistentry>
<varlistentry>
<term><option>--inserts</option></term>
<listitem>
<para>
Dump data as <command>INSERT</command> commands (rather
than <command>COPY</command>). This will make restoration very slow;
it is mainly useful for making dumps that can be loaded into
non-<productname>PostgreSQL</productname> databases. Note that
the restore might fail altogether if you have rearranged column order.
The <option>--column-inserts</option> option is safer, though even
slower.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--column-inserts</option></term>
<term><option>--attribute-inserts</option></term>
......@@ -364,14 +301,64 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term><option>--use-set-session-authorization</></term>
<term><option>--inserts</option></term>
<listitem>
<para>
Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands
instead of <command>ALTER OWNER</> 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.
Dump data as <command>INSERT</command> commands (rather
than <command>COPY</command>). This will make restoration very slow;
it is mainly useful for making dumps that can be loaded into
non-<productname>PostgreSQL</productname> databases. Note that
the restore might fail altogether if you have rearranged column order.
The <option>--column-inserts</option> option is safer, though even
slower.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--lock-wait-timeout=<replaceable class="parameter">timeout</replaceable></option></term>
<listitem>
<para>
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
<replaceable class="parameter">timeout</>. The timeout may be
specified in any of the formats accepted by <command>SET
statement_timeout</>. 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-security-labels</option></term>
<listitem>
<para>
Do not dump security labels.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-tablespaces</option></term>
<listitem>
<para>
Do not output commands to create tablespaces nor select tablespaces
for objects.
With this option, all objects will be created in whichever
tablespace is the default during restore.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-unlogged-table-data</option></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
......@@ -387,6 +374,19 @@ PostgreSQL documentation
</listitem>
</varlistentry>
<varlistentry>
<term><option>--use-set-session-authorization</></term>
<listitem>
<para>
Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands
instead of <command>ALTER OWNER</> 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-?</></term>
<term><option>--help</></term>
......
doc/src/sgml/ref/pg_restore.sgml
View file @ 3439e40f
......@@ -168,32 +168,32 @@
<variablelist>
<varlistentry>
<term><literal>d</></term>
<term><literal>directory</></term>
<term><literal>c</></term>
<term><literal>custom</></term>
<listitem>
<para>
The archive is a <command>directory</command> archive.
The archive is in the custom format of
<application>pg_dump</application>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>t</></term>
<term><literal>tar</></term>
<term><literal>d</></term>
<term><literal>directory</></term>
<listitem>
<para>
The archive is a <command>tar</command> archive.
The archive is a directory archive.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>c</></term>
<term><literal>custom</></term>
<term><literal>t</></term>
<term><literal>tar</></term>
<listitem>
<para>
The archive is in the custom format of
<application>pg_dump</application>.
The archive is a <command>tar</command> archive.
</para>
</listitem>
</varlistentry>
......@@ -328,27 +328,6 @@
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-tablespaces</option></term>
<listitem>
<para>
Do not output commands to select tablespaces.
With this option, all objects will be created in whichever
tablespace is the default during restore.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-security-labels</option></term>
<listitem>
<para>
Do not output commands to restore security labels,
even if the archive contains them.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-P <replaceable class="parameter">function-name(argtype [, ...])</replaceable></option></term>
<term><option>--function=<replaceable class="parameter">function-name(argtype [, ...])</replaceable></option></term>
......@@ -448,6 +427,20 @@
</listitem>
</varlistentry>
<varlistentry>
<term><option>-1</option></term>
<term><option>--single-transaction</option></term>
<listitem>
<para>
Execute the restore as a single transaction (that is, wrap the
emitted commands in <command>BEGIN</>/<command>COMMIT</>). This
ensures that either all the commands complete successfully, or no
changes are applied. This option implies
<option>--exit-on-error</>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--disable-triggers</></term>
<listitem>
......@@ -470,19 +463,6 @@
</listitem>
</varlistentry>
<varlistentry>
<term><option>--use-set-session-authorization</option></term>
<listitem>
<para>
Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands
instead of <command>ALTER OWNER</> 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-data-for-failed-tables</option></term>
<listitem>
......@@ -506,15 +486,35 @@
</varlistentry>
<varlistentry>
<term><option>-1</option></term>
<term><option>--single-transaction</option></term>
<term><option>--no-security-labels</option></term>
<listitem>
<para>
Execute the restore as a single transaction (that is, wrap the
emitted commands in <command>BEGIN</>/<command>COMMIT</>). This
ensures that either all the commands complete successfully, or no
changes are applied. This option implies
<option>--exit-on-error</>.
Do not output commands to restore security labels,
even if the archive contains them.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-tablespaces</option></term>
<listitem>
<para>
Do not output commands to select tablespaces.
With this option, all objects will be created in whichever
tablespace is the default during restore.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--use-set-session-authorization</option></term>
<listitem>
<para>
Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands
instead of <command>ALTER OWNER</> 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.
</para>
</listitem>
</varlistentry>
......
src/bin/pg_dump/pg_dump.c
View file @ 3439e40f
......@@ -854,16 +854,15 @@ help(const char *progname)
printf(_(" -T, --exclude-table=TABLE do NOT dump the named table(s)\n"));
printf(_(" -x, --no-privileges do not dump privileges (grant/revoke)\n"));
printf(_(" --binary-upgrade for use by upgrade utilities only\n"));
printf(_(" --inserts dump data as INSERT commands, rather than COPY\n"));
printf(_(" --column-inserts dump data as INSERT commands with column names\n"));
printf(_(" --disable-dollar-quoting disable dollar quoting, use SQL standard quoting\n"));
printf(_(" --disable-triggers disable triggers during data-only restore\n"));
printf(_(" --inserts dump data as INSERT commands, rather than COPY\n"));
printf(_(" --no-security-labels do not dump security label assignments\n"));
printf(_(" --no-tablespaces do not dump tablespace assignments\n"));
printf(_(" --no-unlogged-table-data do not dump unlogged table data\n"));
printf(_(" --quote-all-identifiers quote all identifiers, even if not key words\n"));
printf(_(" --serializable-deferrable wait until the dump can run without anomalies\n"));
printf(_(" --role=ROLENAME do SET ROLE before dump\n"));
printf(_(" --no-security-labels do not dump security label assignments\n"));
printf(_(" --no-unlogged-table-data do not dump unlogged table data\n"));
printf(_(" --use-set-session-authorization\n"
" use SET SESSION AUTHORIZATION commands instead of\n"
" ALTER OWNER commands to set ownership\n"));
......@@ -874,6 +873,7 @@ help(const char *progname)
printf(_(" -U, --username=NAME connect as specified database user\n"));
printf(_(" -w, --no-password never prompt for password\n"));
printf(_(" -W, --password force password prompt (should happen automatically)\n"));
printf(_(" --role=ROLENAME do SET ROLE before dump\n"));
printf(_("\nIf no database name is supplied, then the PGDATABASE environment\n"
"variable value is used.\n\n"));
......
src/bin/pg_dump/pg_dumpall.c
View file @ 3439e40f
......@@ -546,15 +546,14 @@ help(void)
printf(_(" -t, --tablespaces-only dump only tablespaces, no databases or roles\n"));
printf(_(" -x, --no-privileges do not dump privileges (grant/revoke)\n"));
printf(_(" --binary-upgrade for use by upgrade utilities only\n"));
printf(_(" --inserts dump data as INSERT commands, rather than COPY\n"));
printf(_(" --column-inserts dump data as INSERT commands with column names\n"));
printf(_(" --disable-dollar-quoting disable dollar quoting, use SQL standard quoting\n"));
printf(_(" --disable-triggers disable triggers during data-only restore\n"));
printf(_(" --no-tablespaces do not dump tablespace assignments\n"));
printf(_(" --quote-all-identifiers quote all identifiers, even if not key words\n"));
printf(_(" --role=ROLENAME do SET ROLE before dump\n"));
printf(_(" --inserts dump data as INSERT commands, rather than COPY\n"));
printf(_(" --no-security-labels do not dump security label assignments\n"));
printf(_(" --no-tablespaces do not dump tablespace assignments\n"));
printf(_(" --no-unlogged-table-data do not dump unlogged table data\n"));
printf(_(" --quote-all-identifiers quote all identifiers, even if not key words\n"));
printf(_(" --use-set-session-authorization\n"
" use SET SESSION AUTHORIZATION commands instead of\n"
" ALTER OWNER commands to set ownership\n"));
......@@ -566,6 +565,7 @@ help(void)
printf(_(" -U, --username=NAME connect as specified database user\n"));
printf(_(" -w, --no-password never prompt for password\n"));
printf(_(" -W, --password force password prompt (should happen automatically)\n"));
printf(_(" --role=ROLENAME do SET ROLE before dump\n"));
printf(_("\nIf -f/--file is not used, then the SQL script will be written to the standard\n"
"output.\n\n"));
......
src/bin/pg_dump/pg_restore.c
View file @ 3439e40f
......@@ -424,18 +424,17 @@ usage(const char *progname)
printf(_(" -t, --table=NAME restore named table\n"));
printf(_(" -T, --trigger=NAME restore named trigger\n"));
printf(_(" -x, --no-privileges skip restoration of access privileges (grant/revoke)\n"));
printf(_(" -1, --single-transaction\n"
" restore as a single transaction\n"));
printf(_(" --disable-triggers disable triggers during data-only restore\n"));
printf(_(" --no-data-for-failed-tables\n"
" do not restore data of tables that could not be\n"
" created\n"));
printf(_(" --no-tablespaces do not restore tablespace assignments\n"));
printf(_(" --no-security-labels do not restore security labels\n"));
printf(_(" --role=ROLENAME do SET ROLE before restore\n"));
printf(_(" --no-tablespaces do not restore tablespace assignments\n"));
printf(_(" --use-set-session-authorization\n"
" use SET SESSION AUTHORIZATION commands instead of\n"
" ALTER OWNER commands to set ownership\n"));
printf(_(" -1, --single-transaction\n"
" restore as a single transaction\n"));
printf(_("\nConnection options:\n"));
printf(_(" -h, --host=HOSTNAME database server host or socket directory\n"));
......@@ -443,6 +442,7 @@ usage(const char *progname)
printf(_(" -U, --username=NAME connect as specified database user\n"));
printf(_(" -w, --no-password never prompt for password\n"));
printf(_(" -W, --password force password prompt (should happen automatically)\n"));
printf(_(" --role=ROLENAME do SET ROLE before restore\n"));
printf(_("\nIf no input file name is supplied, then standard input is used.\n\n"));
printf(_("Report bugs to <pgsql-bugs@postgresql.org>.\n"));
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment