From 3439e40f9afa5e8702c8e3e7d0b09a0cb4b07e73 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Wed, 25 May 2011 21:53:26 +0300 Subject: [PATCH] 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. --- doc/src/sgml/ref/pg_dump.sgml | 130 ++++++++++++++--------------- doc/src/sgml/ref/pg_dumpall.sgml | 138 +++++++++++++++---------------- doc/src/sgml/ref/pg_restore.sgml | 102 +++++++++++------------ src/bin/pg_dump/pg_dump.c | 8 +- src/bin/pg_dump/pg_dumpall.c | 8 +- src/bin/pg_dump/pg_restore.c | 8 +- 6 files changed, 197 insertions(+), 197 deletions(-) diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index cca2ed4e4f..c24cc394d6 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -558,25 +558,6 @@ PostgreSQL documentation - - - - - Dump data as INSERT commands (rather - than COPY). This will make restoration very slow; - it is mainly useful for making dumps that can be loaded into - non-PostgreSQL databases. - However, since this option generates a separate command for each row, - an error in reloading a row causes only that row to be lost rather - than the entire table contents. - Note that - the restore might fail altogether if you have rearranged column order. - The option is safe against column - order changes, though even slower. - - - - @@ -633,6 +614,25 @@ PostgreSQL documentation + + + + + Dump data as INSERT commands (rather + than COPY). This will make restoration very slow; + it is mainly useful for making dumps that can be loaded into + non-PostgreSQL databases. + However, since this option generates a separate command for each row, + an error in reloading a row causes only that row to be lost rather + than the entire table contents. + Note that + the restore might fail altogether if you have rearranged column order. + The option is safe against column + order changes, though even slower. + + + + @@ -650,36 +650,10 @@ PostgreSQL documentation - + - Use a serializable transaction for the dump, to - ensure that the snapshot used is consistent with later database - states; but do this by waiting for a point in the transaction stream - at which no anomalies can be present, so that there isn't a risk of - the dump failing or causing other transactions to roll back with a - serialization_failure. See - for more information about transaction isolation and concurrency - control. - - - - 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. - - - - 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. @@ -702,47 +676,73 @@ PostgreSQL documentation - + - 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. - + - Output SQL-standard SET SESSION AUTHORIZATION commands - instead of 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 SET SESSION AUTHORIZATION - will certainly require superuser privileges to restore correctly, - whereas 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. - + - 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 serializable transaction for the dump, to + ensure that the snapshot used is consistent with later database + states; but do this by waiting for a point in the transaction stream + at which no anomalies can be present, so that there isn't a risk of + the dump failing or causing other transactions to roll back with a + serialization_failure. See + for more information about transaction isolation and concurrency + control. + + + + 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. + + + + 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. - + - 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 SET SESSION AUTHORIZATION commands + instead of 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 SET SESSION AUTHORIZATION + will certainly require superuser privileges to restore correctly, + whereas ALTER OWNER requires lesser privileges. diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml index 039e86ec90..7c49c0364f 100644 --- a/doc/src/sgml/ref/pg_dumpall.sgml +++ b/doc/src/sgml/ref/pg_dumpall.sgml @@ -164,54 +164,6 @@ PostgreSQL documentation - - - - - 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 - timeout. The timeout may be - specified in any of the formats accepted by 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. - - - - - - - - - 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. - - - - - - - - - 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. - - - - @@ -301,21 +253,6 @@ PostgreSQL documentation - - - - - Dump data as INSERT commands (rather - than COPY). This will make restoration very slow; - it is mainly useful for making dumps that can be loaded into - non-PostgreSQL databases. Note that - the restore might fail altogether if you have rearranged column order. - The option is safer, though even - slower. - - - - @@ -364,14 +301,64 @@ PostgreSQL documentation - + - Output SQL-standard SET SESSION AUTHORIZATION commands - instead of 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 INSERT commands (rather + than COPY). This will make restoration very slow; + it is mainly useful for making dumps that can be loaded into + non-PostgreSQL databases. Note that + the restore might fail altogether if you have rearranged column order. + The option is safer, though even + slower. + + + + + + + + + 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 + timeout. The timeout may be + specified in any of the formats accepted by 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. + + + + + + + + + Do not dump security labels. + + + + + + + + + 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. + + + + + + + + + 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. @@ -387,6 +374,19 @@ PostgreSQL documentation + + + + + Output SQL-standard SET SESSION AUTHORIZATION commands + instead of 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. + + + + diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index a7202e2422..be4851b657 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -168,32 +168,32 @@ - d - directory + c + custom - The archive is a directory archive. + The archive is in the custom format of + pg_dump. - t - tar + d + directory - The archive is a tar archive. + The archive is a directory archive. - c - custom + t + tar - The archive is in the custom format of - pg_dump. + The archive is a tar archive. @@ -328,27 +328,6 @@ - - - - - Do not output commands to select tablespaces. - With this option, all objects will be created in whichever - tablespace is the default during restore. - - - - - - - - - Do not output commands to restore security labels, - even if the archive contains them. - - - - @@ -448,6 +427,20 @@ + + + + + + Execute the restore as a single transaction (that is, wrap the + emitted commands in BEGIN/COMMIT). This + ensures that either all the commands complete successfully, or no + changes are applied. This option implies + + + + @@ -470,19 +463,6 @@ - - - - - Output SQL-standard SET SESSION AUTHORIZATION commands - instead of 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. - - - - @@ -506,15 +486,35 @@ - - + - Execute the restore as a single transaction (that is, wrap the - emitted commands in BEGIN/COMMIT). This - ensures that either all the commands complete successfully, or no - changes are applied. This option implies - + + + + + + + + Do not output commands to select tablespaces. + With this option, all objects will be created in whichever + tablespace is the default during restore. + + + + + + + + + Output SQL-standard SET SESSION AUTHORIZATION commands + instead of 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. diff --git a/src/bin/pg_dump/pg_dump.c b/src/bin/pg_dump/pg_dump.c index 4f39734870..80bc9a96ca 100644 --- a/src/bin/pg_dump/pg_dump.c +++ b/src/bin/pg_dump/pg_dump.c @@ -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")); diff --git a/src/bin/pg_dump/pg_dumpall.c b/src/bin/pg_dump/pg_dumpall.c index e01a13006b..b3ad2eac29 100644 --- a/src/bin/pg_dump/pg_dumpall.c +++ b/src/bin/pg_dump/pg_dumpall.c @@ -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")); diff --git a/src/bin/pg_dump/pg_restore.c b/src/bin/pg_dump/pg_restore.c index 184199e73a..7731d2540c 100644 --- a/src/bin/pg_dump/pg_restore.c +++ b/src/bin/pg_dump/pg_restore.c @@ -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 .\n")); -- 2.40.0