From cb3cffe694b6041c1de47b12b225e05f664c7285 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Thu, 3 Jun 2021 06:55:04 +0200 Subject: [PATCH] doc: Group options in pg_amcheck reference page The previous arrangement was just one big list, and the internal order was not all consistent either. Now arrange the options by group and sort them, the way it's already done in the --help output and one other reference pages. Also fix some ordering in the --help output. --- doc/src/sgml/ref/pg_amcheck.sgml | 631 ++++++++++++++++--------------- src/bin/pg_amcheck/pg_amcheck.c | 4 +- 2 files changed, 329 insertions(+), 306 deletions(-) diff --git a/doc/src/sgml/ref/pg_amcheck.sgml b/doc/src/sgml/ref/pg_amcheck.sgml index d4989c9f231..04667e9002d 100644 --- a/doc/src/sgml/ref/pg_amcheck.sgml +++ b/doc/src/sgml/ref/pg_amcheck.sgml @@ -73,7 +73,7 @@ PostgreSQL documentation Options - pg_amcheck accepts the following command-line arguments: + The following command-line options control what is checked: @@ -112,78 +112,6 @@ PostgreSQL documentation - - - - - - Echo to stdout all SQL sent to the server. - - - - - - - - - End checking at the specified block number. An error will occur if the - table relation being checked has fewer than this number of blocks. - This option does not apply to indexes, and is probably only useful when - checking a single table relation. If both a regular table and a toast - table are checked, this option will apply to both, but higher-numbered - toast blocks may still be accessed while validating toast pointers, - unless that is suppressed using - . - - - - - - - - - By default, whenever a toast pointer is encountered in a table, - a lookup is performed to ensure that it references apparently-valid - entries in the toast table. These checks can be quite slow, and this - option can be used to skip them. - - - - - - - - - For each index checked, verify the presence of all heap tuples as index - tuples in the index using 's - option. - - - - - - - - - - Show help about pg_amcheck command line - arguments, and exit. - - - - - - - - - - Specifies the host name of the machine on which the server is running. - If the value begins with a slash, it is used as the directory for the - Unix domain socket. - - - - @@ -217,161 +145,6 @@ PostgreSQL documentation - - - - - - Install any missing extensions that are required to check the - database(s). If not yet installed, each extension's objects will be - installed into the given - schema, or if not specified - into schema pg_catalog. - - - At present, the only required extension is . - - - - - - - - - - Use num concurrent connections to the server, - or one per object to be checked, whichever is less. - - - The default is to use a single connection. - - - - - - - - - Specifies a database or - connection string to be - used to discover the list of databases to be checked. If neither - nor any option including a database pattern is - used, no such connection is required and this option does nothing. - Otherwise, any connection string parameters other than - the database name which are included in the value for this option - will also be used when connecting to the databases - being checked. If this option is omitted, the default is - postgres or, if that fails, - template1. - - - - - - - - - By default, if a table is checked, any btree indexes of that table - will also be checked, even if they are not explicitly selected by - an option such as --index or - --relation. This option suppresses that behavior. - - - - - - - - - By default, if an argument to --database, - --table, --index, - or --relation matches no objects, it is a fatal - error. This option downgrades that error to a warning. - If this option is used with --quiet, the warning - will be supressed as well. - - - - - - - - - By default, if a table is checked, its toast table, if any, will also - be checked, even if it is not explicitly selected by an option - such as --table or --relation. - This option suppresses that behavior. - - - - - - - - - After reporting all corruptions on the first page of a table where - corruption is found, stop processing that table relation and move on - to the next table or index. - - - Note that index checking always stops after the first corrupt page. - This option only has meaning relative to table relations. - - - - - - - - - For each btree index checked, use 's - bt_index_parent_check function, which performs - additional checks of parent/child relationships during index checking. - - - The default is to use amcheck's - bt_index_check function, but note that use of the - option implicitly selects - bt_index_parent_check. - - - - - - - - - - Specifies the TCP port or local Unix domain socket file extension on - which the server is listening for connections. - - - - - - - - - - Show progress information. Progress information includes the number - of relations for which checking has been completed, and the total - size of those relations. It also includes the total number of relations - that will eventually be checked, and the estimated size of those - relations. - - - - - - - - - - Print fewer messages, and less detail regarding any server errors. - - - - @@ -410,28 +183,6 @@ PostgreSQL documentation - - - - - For each index checked, re-find tuples on the leaf level by performing a - new search from the root page for each tuple using - 's option. - - - Use of this option implicitly also selects the - option. - - - This form of verification was originally written to help in the - development of btree index features. It may be of limited use or even - of no use in helping detect the kinds of corruption that occur in - practice. It may also cause corruption checking to take considerably - longer and consume considerably more resources on the server. - - - - @@ -473,38 +224,6 @@ PostgreSQL documentation - - - - - If all-frozen is given, table corruption checks - will skip over pages in all tables that are marked as all frozen. - - - If all-visible is given, table corruption checks - will skip over pages in all tables that are marked as all visible. - - - By default, no pages are skipped. This can be specified as - none, but since this is the default, it need not be - mentioned. - - - - - - - - - Start checking at the specified block number. An error will occur if - the table relation being checked has fewer than this number of blocks. - This option does not apply to indexes, and is probably only useful - when checking a single table relation. See --endblock - for further caveats. - - - - @@ -538,6 +257,210 @@ PostgreSQL documentation + + + + + By default, if a table is checked, any btree indexes of that table + will also be checked, even if they are not explicitly selected by + an option such as --index or + --relation. This option suppresses that behavior. + + + + + + + + + By default, if a table is checked, its toast table, if any, will also + be checked, even if it is not explicitly selected by an option + such as --table or --relation. + This option suppresses that behavior. + + + + + + + + + By default, if an argument to --database, + --table, --index, + or --relation matches no objects, it is a fatal + error. This option downgrades that error to a warning. + If this option is used with --quiet, the warning + will be supressed as well. + + + + + + + + The following command-line options control checking of tables: + + + + + + + By default, whenever a toast pointer is encountered in a table, + a lookup is performed to ensure that it references apparently-valid + entries in the toast table. These checks can be quite slow, and this + option can be used to skip them. + + + + + + + + + After reporting all corruptions on the first page of a table where + corruption is found, stop processing that table relation and move on + to the next table or index. + + + Note that index checking always stops after the first corrupt page. + This option only has meaning relative to table relations. + + + + + + + + + If all-frozen is given, table corruption checks + will skip over pages in all tables that are marked as all frozen. + + + If all-visible is given, table corruption checks + will skip over pages in all tables that are marked as all visible. + + + By default, no pages are skipped. This can be specified as + none, but since this is the default, it need not be + mentioned. + + + + + + + + + Start checking at the specified block number. An error will occur if + the table relation being checked has fewer than this number of blocks. + This option does not apply to indexes, and is probably only useful + when checking a single table relation. See --endblock + for further caveats. + + + + + + + + + End checking at the specified block number. An error will occur if the + table relation being checked has fewer than this number of blocks. + This option does not apply to indexes, and is probably only useful when + checking a single table relation. If both a regular table and a toast + table are checked, this option will apply to both, but higher-numbered + toast blocks may still be accessed while validating toast pointers, + unless that is suppressed using + . + + + + + + + + The following command-line options control checking of B-tree indexes: + + + + + + + For each index checked, verify the presence of all heap tuples as index + tuples in the index using 's + option. + + + + + + + + + For each btree index checked, use 's + bt_index_parent_check function, which performs + additional checks of parent/child relationships during index checking. + + + The default is to use amcheck's + bt_index_check function, but note that use of the + option implicitly selects + bt_index_parent_check. + + + + + + + + + For each index checked, re-find tuples on the leaf level by performing a + new search from the root page for each tuple using + 's option. + + + Use of this option implicitly also selects the + option. + + + This form of verification was originally written to help in the + development of btree index features. It may be of limited use or even + of no use in helping detect the kinds of corruption that occur in + practice. It may also cause corruption checking to take considerably + longer and consume considerably more resources on the server. + + + + + + + + The following command-line options control the connection to the server: + + + + + + + + Specifies the host name of the machine on which the server is running. + If the value begins with a slash, it is used as the directory for the + Unix domain socket. + + + + + + + + + + Specifies the TCP port or local Unix domain socket file extension on + which the server is listening for connections. + + + + @@ -548,28 +471,6 @@ PostgreSQL documentation - - - - - - Print more messages. In particular, this will print a message for - each relation being checked, and will increase the level of detail - shown for server errors. - - - - - - - - - - Print the pg_amcheck version and exit. - - - - @@ -603,6 +504,128 @@ PostgreSQL documentation + + + + + Specifies a database or + connection string to be + used to discover the list of databases to be checked. If neither + nor any option including a database pattern is + used, no such connection is required and this option does nothing. + Otherwise, any connection string parameters other than + the database name which are included in the value for this option + will also be used when connecting to the databases + being checked. If this option is omitted, the default is + postgres or, if that fails, + template1. + + + + + + + + Other options are also available: + + + + + + + + Echo to stdout all SQL sent to the server. + + + + + + + + + + Use num concurrent connections to the server, + or one per object to be checked, whichever is less. + + + The default is to use a single connection. + + + + + + + + + + Print fewer messages, and less detail regarding any server errors. + + + + + + + + + + Show progress information. Progress information includes the number + of relations for which checking has been completed, and the total + size of those relations. It also includes the total number of relations + that will eventually be checked, and the estimated size of those + relations. + + + + + + + + + + Print more messages. In particular, this will print a message for + each relation being checked, and will increase the level of detail + shown for server errors. + + + + + + + + + + Print the pg_amcheck version and exit. + + + + + + + + + + Install any missing extensions that are required to check the + database(s). If not yet installed, each extension's objects will be + installed into the given + schema, or if not specified + into schema pg_catalog. + + + At present, the only required extension is . + + + + + + + + + + Show help about pg_amcheck command line + arguments, and exit. + + + diff --git a/src/bin/pg_amcheck/pg_amcheck.c b/src/bin/pg_amcheck/pg_amcheck.c index 6b97d635c32..4bde16fb4bd 100644 --- a/src/bin/pg_amcheck/pg_amcheck.c +++ b/src/bin/pg_amcheck/pg_amcheck.c @@ -1187,11 +1187,11 @@ help(const char *progname) printf(_(" -e, --echo show the commands being sent to the server\n")); printf(_(" -j, --jobs=NUM use this many concurrent connections to the server\n")); printf(_(" -q, --quiet don't write any messages\n")); + printf(_(" -P, --progress show progress information\n")); printf(_(" -v, --verbose write a lot of output\n")); printf(_(" -V, --version output version information, then exit\n")); - printf(_(" -P, --progress show progress information\n")); - printf(_(" -?, --help show this help, then exit\n")); printf(_(" --install-missing install missing extensions\n")); + printf(_(" -?, --help show this help, then exit\n")); printf(_("\nReport bugs to <%s>.\n"), PACKAGE_BUGREPORT); printf(_("%s home page: <%s>\n"), PACKAGE_NAME, PACKAGE_URL);