diff options
| -rw-r--r-- | doc/src/sgml/ref/pg_amcheck.sgml | 451 | ||||
| -rw-r--r-- | src/bin/pg_amcheck/pg_amcheck.c | 4 |
2 files changed, 239 insertions, 216 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 <title>Options</title> <para> - pg_amcheck accepts the following command-line arguments: + The following command-line options control what is checked: <variablelist> <varlistentry> @@ -113,168 +113,170 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-e</option></term> - <term><option>--echo</option></term> + <term><option>-i <replaceable class="parameter">pattern</replaceable></option></term> + <term><option>--index=<replaceable class="parameter">pattern</replaceable></option></term> <listitem> <para> - Echo to stdout all SQL sent to the server. + Check indexes matching the specified + <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>, + unless they are otherwise excluded. + This option can be specified more than once. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--endblock=<replaceable class="parameter">block</replaceable></option></term> - <listitem> <para> - 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 - <option>--exclude-toast-pointers</option>. + This is similar to the <option>--relation</option> option, except that + it applies only to indexes, not tables. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--exclude-toast-pointers</option></term> + <term><option>-I <replaceable class="parameter">pattern</replaceable></option></term> + <term><option>--exclude-index=<replaceable class="parameter">pattern</replaceable></option></term> <listitem> <para> - 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. + Exclude indexes matching the specified + <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>. + This option can be specified more than once. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--heapallindexed</option></term> - <listitem> <para> - For each index checked, verify the presence of all heap tuples as index - tuples in the index using <xref linkend="amcheck"/>'s - <option>heapallindexed</option> option. + This is similar to the <option>--exclude-relation</option> option, + except that it applies only to indexes, not tables. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-?</option></term> - <term><option>--help</option></term> + <term><option>-r <replaceable class="parameter">pattern</replaceable></option></term> + <term><option>--relation=<replaceable class="parameter">pattern</replaceable></option></term> <listitem> <para> - Show help about <application>pg_amcheck</application> command line - arguments, and exit. + Check relations matching the specified + <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>, + unless they are otherwise excluded. + This option can be specified more than once. + </para> + <para> + Patterns may be unqualified, e.g. <literal>myrel*</literal>, or they + may be schema-qualified, e.g. <literal>myschema*.myrel*</literal> or + database-qualified and schema-qualified, e.g. + <literal>mydb*.myscheam*.myrel*</literal>. A database-qualified + pattern will add matching databases to the list of databases to be + checked. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term> - <term><option>--host=<replaceable class="parameter">hostname</replaceable></option></term> + <term><option>-R <replaceable class="parameter">pattern</replaceable></option></term> + <term><option>--exclude-relation=<replaceable class="parameter">pattern</replaceable></option></term> <listitem> <para> - 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. + Exclude relations matching the specified + <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>. + This option can be specified more than once. + </para> + <para> + As with <option>--relation</option>, the + <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link> may be unqualified, schema-qualified, + or database- and schema-qualified. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-i <replaceable class="parameter">pattern</replaceable></option></term> - <term><option>--index=<replaceable class="parameter">pattern</replaceable></option></term> + <term><option>-s <replaceable class="parameter">pattern</replaceable></option></term> + <term><option>--schema=<replaceable class="parameter">pattern</replaceable></option></term> <listitem> <para> - Check indexes matching the specified - <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>, - unless they are otherwise excluded. + Check tables and indexes in schemas matching the specified + <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>, unless they are otherwise excluded. This option can be specified more than once. </para> <para> - This is similar to the <option>--relation</option> option, except that - it applies only to indexes, not tables. + To select only tables in schemas matching a particular pattern, + consider using something like + <literal>--table=SCHEMAPAT.* --no-dependent-indexes</literal>. + To select only indexes, consider using something like + <literal>--index=SCHEMAPAT.*</literal>. + </para> + <para> + A schema pattern may be database-qualified. For example, you may + write <literal>--schema=mydb*.myschema*</literal> to select + schemas matching <literal>myschema*</literal> in databases matching + <literal>mydb*</literal>. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-I <replaceable class="parameter">pattern</replaceable></option></term> - <term><option>--exclude-index=<replaceable class="parameter">pattern</replaceable></option></term> + <term><option>-S <replaceable class="parameter">pattern</replaceable></option></term> + <term><option>--exclude-schema=<replaceable class="parameter">pattern</replaceable></option></term> <listitem> <para> - Exclude indexes matching the specified + Exclude tables and indexes in schemas matching the specified <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>. This option can be specified more than once. </para> <para> - This is similar to the <option>--exclude-relation</option> option, - except that it applies only to indexes, not tables. + As with <option>--schema</option>, the pattern may be + database-qualified. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--install-missing</option></term> - <term><option>--install-missing=<replaceable class="parameter">schema</replaceable></option></term> + <term><option>-t <replaceable class="parameter">pattern</replaceable></option></term> + <term><option>--table=<replaceable class="parameter">pattern</replaceable></option></term> <listitem> <para> - 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 - <replaceable class="parameter">schema</replaceable>, or if not specified - into schema <literal>pg_catalog</literal>. + Check tables matching the specified + <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>, + unless they are otherwise excluded. + This option can be specified more than once. </para> <para> - At present, the only required extension is <xref linkend="amcheck"/>. + This is similar to the <option>--relation</option> option, except that + it applies only to tables, not indexes. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-j <replaceable class="parameter">num</replaceable></option></term> - <term><option>--jobs=<replaceable class="parameter">num</replaceable></option></term> + <term><option>-T <replaceable class="parameter">pattern</replaceable></option></term> + <term><option>--exclude-table=<replaceable class="parameter">pattern</replaceable></option></term> <listitem> <para> - Use <replaceable>num</replaceable> concurrent connections to the server, - or one per object to be checked, whichever is less. + Exclude tables matching the specified + <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>. + This option can be specified more than once. </para> <para> - The default is to use a single connection. + This is similar to the <option>--exclude-relation</option> option, + except that it applies only to tables, not indexes. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term> + <term><option>--no-dependent-indexes</option></term> <listitem> <para> - Specifies a database or - <link linkend="libpq-connstring">connection string</link> to be - used to discover the list of databases to be checked. If neither - <option>--all</option> 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 - <literal>postgres</literal> or, if that fails, - <literal>template1</literal>. + 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 <literal>--index</literal> or + <literal>--relation</literal>. This option suppresses that behavior. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--no-dependent-indexes</option></term> + <term><option>--no-dependent-toast</option></term> <listitem> <para> - 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 <literal>--index</literal> or - <literal>--relation</literal>. 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 <literal>--table</literal> or <literal>--relation</literal>. + This option suppresses that behavior. </para> </listitem> </varlistentry> @@ -292,15 +294,21 @@ PostgreSQL documentation </para> </listitem> </varlistentry> + </variablelist> + </para> + <para> + The following command-line options control checking of tables: + + <variablelist> <varlistentry> - <term><option>--no-dependent-toast</option></term> + <term><option>--exclude-toast-pointers</option></term> <listitem> <para> - 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 <literal>--table</literal> or <literal>--relation</literal>. - This option suppresses that behavior. + 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. </para> </listitem> </varlistentry> @@ -321,91 +329,83 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--parent-check</option></term> + <term><option>--skip=<replaceable class="parameter">option</replaceable></option></term> <listitem> <para> - For each btree index checked, use <xref linkend="amcheck"/>'s - <function>bt_index_parent_check</function> function, which performs - additional checks of parent/child relationships during index checking. + If <literal>all-frozen</literal> is given, table corruption checks + will skip over pages in all tables that are marked as all frozen. </para> <para> - The default is to use <application>amcheck</application>'s - <function>bt_index_check</function> function, but note that use of the - <option>--rootdescend</option> option implicitly selects - <function>bt_index_parent_check</function>. + If <literal>all-visible</literal> is given, table corruption checks + will skip over pages in all tables that are marked as all visible. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></option></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> - <listitem> <para> - Specifies the TCP port or local Unix domain socket file extension on - which the server is listening for connections. + By default, no pages are skipped. This can be specified as + <literal>none</literal>, but since this is the default, it need not be + mentioned. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-P</option></term> - <term><option>--progress</option></term> + <term><option>--startblock=<replaceable class="parameter">block</replaceable></option></term> <listitem> <para> - 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. + 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 <literal>--endblock</literal> + for further caveats. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-q</option></term> - <term><option>--quiet</option></term> + <term><option>--endblock=<replaceable class="parameter">block</replaceable></option></term> <listitem> <para> - Print fewer messages, and less detail regarding any server errors. + 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 + <option>--exclude-toast-pointers</option>. </para> </listitem> </varlistentry> + </variablelist> + </para> + <para> + The following command-line options control checking of B-tree indexes: + + <variablelist> <varlistentry> - <term><option>-r <replaceable class="parameter">pattern</replaceable></option></term> - <term><option>--relation=<replaceable class="parameter">pattern</replaceable></option></term> + <term><option>--heapallindexed</option></term> <listitem> <para> - Check relations matching the specified - <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>, - unless they are otherwise excluded. - This option can be specified more than once. - </para> - <para> - Patterns may be unqualified, e.g. <literal>myrel*</literal>, or they - may be schema-qualified, e.g. <literal>myschema*.myrel*</literal> or - database-qualified and schema-qualified, e.g. - <literal>mydb*.myscheam*.myrel*</literal>. A database-qualified - pattern will add matching databases to the list of databases to be - checked. + For each index checked, verify the presence of all heap tuples as index + tuples in the index using <xref linkend="amcheck"/>'s + <option>heapallindexed</option> option. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-R <replaceable class="parameter">pattern</replaceable></option></term> - <term><option>--exclude-relation=<replaceable class="parameter">pattern</replaceable></option></term> + <term><option>--parent-check</option></term> <listitem> <para> - Exclude relations matching the specified - <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>. - This option can be specified more than once. + For each btree index checked, use <xref linkend="amcheck"/>'s + <function>bt_index_parent_check</function> function, which performs + additional checks of parent/child relationships during index checking. </para> <para> - As with <option>--relation</option>, the - <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link> may be unqualified, schema-qualified, - or database- and schema-qualified. + The default is to use <application>amcheck</application>'s + <function>bt_index_check</function> function, but note that use of the + <option>--rootdescend</option> option implicitly selects + <function>bt_index_parent_check</function>. </para> </listitem> </varlistentry> @@ -431,119 +431,148 @@ PostgreSQL documentation </para> </listitem> </varlistentry> + </variablelist> + </para> + <para> + The following command-line options control the connection to the server: + + <variablelist> <varlistentry> - <term><option>-s <replaceable class="parameter">pattern</replaceable></option></term> - <term><option>--schema=<replaceable class="parameter">pattern</replaceable></option></term> + <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">hostname</replaceable></option></term> <listitem> <para> - Check tables and indexes in schemas matching the specified - <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>, unless they are otherwise excluded. - This option can be specified more than once. - </para> - <para> - To select only tables in schemas matching a particular pattern, - consider using something like - <literal>--table=SCHEMAPAT.* --no-dependent-indexes</literal>. - To select only indexes, consider using something like - <literal>--index=SCHEMAPAT.*</literal>. + 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. </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> + <listitem> <para> - A schema pattern may be database-qualified. For example, you may - write <literal>--schema=mydb*.myschema*</literal> to select - schemas matching <literal>myschema*</literal> in databases matching - <literal>mydb*</literal>. + Specifies the TCP port or local Unix domain socket file extension on + which the server is listening for connections. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-S <replaceable class="parameter">pattern</replaceable></option></term> - <term><option>--exclude-schema=<replaceable class="parameter">pattern</replaceable></option></term> + <term><option>-U</option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <listitem> <para> - Exclude tables and indexes in schemas matching the specified - <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>. - This option can be specified more than once. + User name to connect as. </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-w</option></term> + <term><option>--no-password</option></term> + <listitem> <para> - As with <option>--schema</option>, the pattern may be - database-qualified. + Never issue a password prompt. If the server requires password + authentication and a password is not available by other means such as + a <filename>.pgpass</filename> file, the connection attempt will fail. + This option can be useful in batch jobs and scripts where no user is + present to enter a password. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--skip=<replaceable class="parameter">option</replaceable></option></term> + <term><option>-W</option></term> + <term><option>--password</option></term> <listitem> <para> - If <literal>all-frozen</literal> is given, table corruption checks - will skip over pages in all tables that are marked as all frozen. + Force <application>pg_amcheck</application> to prompt for a password + before connecting to a database. </para> <para> - If <literal>all-visible</literal> is given, table corruption checks - will skip over pages in all tables that are marked as all visible. + This option is never essential, since + <application>pg_amcheck</application> will automatically prompt for a + password if the server demands password authentication. However, + <application>pg_amcheck</application> will waste a connection attempt + finding out that the server wants a password. In some cases it is + worth typing <option>-W</option> to avoid the extra connection attempt. </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term> + <listitem> <para> - By default, no pages are skipped. This can be specified as - <literal>none</literal>, but since this is the default, it need not be - mentioned. + Specifies a database or + <link linkend="libpq-connstring">connection string</link> to be + used to discover the list of databases to be checked. If neither + <option>--all</option> 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 + <literal>postgres</literal> or, if that fails, + <literal>template1</literal>. </para> </listitem> </varlistentry> + </variablelist> + </para> + + <para> + Other options are also available: + <variablelist> <varlistentry> - <term><option>--startblock=<replaceable class="parameter">block</replaceable></option></term> + <term><option>-e</option></term> + <term><option>--echo</option></term> <listitem> <para> - 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 <literal>--endblock</literal> - for further caveats. + Echo to stdout all SQL sent to the server. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-t <replaceable class="parameter">pattern</replaceable></option></term> - <term><option>--table=<replaceable class="parameter">pattern</replaceable></option></term> + <term><option>-j <replaceable class="parameter">num</replaceable></option></term> + <term><option>--jobs=<replaceable class="parameter">num</replaceable></option></term> <listitem> <para> - Check tables matching the specified - <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>, - unless they are otherwise excluded. - This option can be specified more than once. + Use <replaceable>num</replaceable> concurrent connections to the server, + or one per object to be checked, whichever is less. </para> <para> - This is similar to the <option>--relation</option> option, except that - it applies only to tables, not indexes. + The default is to use a single connection. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-T <replaceable class="parameter">pattern</replaceable></option></term> - <term><option>--exclude-table=<replaceable class="parameter">pattern</replaceable></option></term> + <term><option>-q</option></term> + <term><option>--quiet</option></term> <listitem> <para> - Exclude tables matching the specified - <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>. - This option can be specified more than once. - </para> - <para> - This is similar to the <option>--exclude-relation</option> option, - except that it applies only to tables, not indexes. + Print fewer messages, and less detail regarding any server errors. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-U</option></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> + <term><option>-P</option></term> + <term><option>--progress</option></term> <listitem> <para> - User name to connect as. + 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. </para> </listitem> </varlistentry> @@ -571,38 +600,32 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</option></term> - <term><option>--no-password</option></term> + <term><option>--install-missing</option></term> + <term><option>--install-missing=<replaceable class="parameter">schema</replaceable></option></term> <listitem> <para> - Never issue a password prompt. If the server requires password - authentication and a password is not available by other means such as - a <filename>.pgpass</filename> file, the connection attempt will fail. - This option can be useful in batch jobs and scripts where no user is - present to enter a password. + 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 + <replaceable class="parameter">schema</replaceable>, or if not specified + into schema <literal>pg_catalog</literal>. + </para> + <para> + At present, the only required extension is <xref linkend="amcheck"/>. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-W</option></term> - <term><option>--password</option></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> - Force <application>pg_amcheck</application> to prompt for a password - before connecting to a database. - </para> - <para> - This option is never essential, since - <application>pg_amcheck</application> will automatically prompt for a - password if the server demands password authentication. However, - <application>pg_amcheck</application> will waste a connection attempt - finding out that the server wants a password. In some cases it is - worth typing <option>-W</option> to avoid the extra connection attempt. + Show help about <application>pg_amcheck</application> command line + arguments, and exit. </para> </listitem> </varlistentry> - </variablelist> </para> </refsect1> 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); |