doc-hacking.patch
application/octet-stream
Filename: doc-hacking.patch
Type: application/octet-stream
Part: 0
Message:
Re: pg_amcheck contrib application
Patch
Format: unified
| File | + | − |
|---|---|---|
| doc/src/sgml/pgamcheck.sgml | 120 | 233 |
diff --git a/doc/src/sgml/pgamcheck.sgml b/doc/src/sgml/pgamcheck.sgml
index b960c47305..062e1e7a3f 100644
--- a/doc/src/sgml/pgamcheck.sgml
+++ b/doc/src/sgml/pgamcheck.sgml
@@ -42,6 +42,25 @@
relation types are silently skipped.
</para>
+ <para>
+ If <literal>dbname</literal> is specified, it should be the name of a
+ single database to check, and no other database selection options should
+ be present. Otherwise, if any database selection options are present,
+ all matching databases will be checked. If no such options are present,
+ the default database will be checked. Database selection options include
+ <option>--all</option>, <option>--database</option> and
+ <option>--exclude-database</option>. They also include
+ <option>--relation</option>, <option>--exclude-relation</option>,
+ <option>--table</option>, <option>--exclude-table</option>,
+ <option>--index</option>, and <option>--exclude-index</option>,
+ but only when such options are used with a three-part pattern
+ (e.g. <option>mydb*.myschema*.myrel*</option>).
+ </para>
+
+ <para>
+ <replaceable>dbname</replaceable> can also be a
+ <link linkend="libpq-connstring">connection string</link>.
+ </para>
</refsect1>
<refsect1>
@@ -51,47 +70,13 @@
pg_amcheck accepts the following command-line arguments:
<variablelist>
-
- <varlistentry>
- <term><option><replaceable class="parameter">dbname</replaceable></option></term>
- <listitem>
- <para>
- Specifies the name of a database to be checked, or a connection string
- to use while connecting.
- </para>
- <para>
- If no <replaceable>dbname</replaceable> is specified, and if
- <option>-a</option> <option>--all</option> is not used, the database name
- is read from the environment variable <envar>PGDATABASE</envar>. If
- that is not set, the user name specified for the connection is used.
- The <replaceable>dbname</replaceable> can be a <link
- linkend="libpq-connstring">connection string</link>. If so, connection
- string parameters will override any conflicting command line options,
- and connection string parameters other than the database
- name itself will be re-used when connecting to other databases.
- </para>
- <para>
- If a connection string is given which contains no database name, the other
- parameters of the string will be used while the database name to use is
- determined as described above.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>-a</option></term>
<term><option>--all</option></term>
<listitem>
<para>
- Perform checking in all databases which are not otherwise excluded.
- </para>
- <para>
- In the absence of any other options, selects all objects across all
- schemas and databases.
- </para>
- <para>
- Option <option>-D</option> <option>--exclude-database</option> takes
- precedence over <option>-a</option> <option>--all</option>.
+ Check all databases, except for any excluded via
+ <option>--exclude-database</option>.
</para>
</listitem>
</varlistentry>
@@ -101,22 +86,10 @@
<term><option>--database=<replaceable class="parameter">pattern</replaceable></option></term>
<listitem>
<para>
- Perform checking in databases matching the specified
- <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>
- that are not otherwise excluded.
- </para>
- <para>
- This option may be specified multiple times to list more than one
- pattern. By default, all objects in all matching databases will be
- checked.
- </para>
- <para>
- If <option>-a</option> <option>--all</option> is also specified,
- <option>-d</option> <option>--database</option> has no effect.
- </para>
- <para>
- Option <option>-D</option> <option>--exclude-database</option> takes
- precedence over <option>-d</option> <option>--database</option>.
+ Check databases matching the specified
+ <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>,
+ except for any excluded by <option>--exclude-database</option>.
+ This option can be specified more than once.
</para>
</listitem>
</varlistentry>
@@ -126,20 +99,9 @@
<term><option>--exclude-database=<replaceable class="parameter">pattern</replaceable></option></term>
<listitem>
<para>
- Do not include databases matching other patterns or included by option
- <option>-a</option> <option>--all</option> if they also match the
- specified exclusion
+ Exclude databases matching the given
<link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>.
- </para>
- <para>
- This does not exclude any database that was listed explicitly as a
- <replaceable>dbname</replaceable> on the command line, nor does it exclude
- the database chosen in the absence of any
- <replaceable>dbname</replaceable> argument.
- </para>
- <para>
- This option may be specified multiple times to list more than one
- exclusion pattern.
+ This option can be specified more than once.
</para>
</listitem>
</varlistentry>
@@ -149,8 +111,7 @@
<term><option>--echo</option></term>
<listitem>
<para>
- Print to stdout all commands and queries being executed against the
- server.
+ Echo to stdout all SQL sent to the server.
</para>
</listitem>
</varlistentry>
@@ -159,21 +120,13 @@
<term><option>--endblock=<replaceable class="parameter">block</replaceable></option></term>
<listitem>
<para>
- Check table blocks up to and including the specified ending block
- number. An error will occur if the table relation being checked has
- fewer than this number of blocks.
- </para>
- <para>
- By default, checking is performed up to and including the final block.
- This option will be applied to all table relations that are checked,
- including toast tables, but note that unless
- <option>--exclude-toast-pointers</option> is given, toast pointers found
- in the main table will be followed into the toast table without regard
- to the location in the toast table.
- </para>
- <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.
+ 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 suppresed using <option>--exclude-toast-pointers</option>.
</para>
</listitem>
</varlistentry>
@@ -182,21 +135,10 @@
<term><option>--exclude-toast-pointers</option></term>
<listitem>
<para>
- When checking main relations, do not look up entries in toast tables
- corresponding to toast pointers in the main relation.
- </para>
- <para>
- The default behavior checks each toast pointer encountered in the main
- table to verify, as much as possible, that the pointer points at
- something in the toast table that is reasonable. Toast pointers which
- point beyond the end of the toast table, or to the middle (rather than
- the beginning) of a toast entry, are identified as corrupt.
- </para>
- <para>
- The process by which <xref linkend="amcheck"/>'s
- <function>verify_heapam</function> function checks each toast pointer is
- slow and may be improved in a future release. Some users may wish to
- disable this check to save time.
+ 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>
@@ -240,13 +182,14 @@
<term><option>--index=<replaceable class="parameter">pattern</replaceable></option></term>
<listitem>
<para>
- Perform checks on indexes which match the specified
- <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>
+ 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>
<para>
- This is similar to the <option>-r</option> <option>--relation</option>
- option, except that it applies only to indexes, not tables.
+ This is similar to the <option>--relation</option> option, except that
+ it applies only to indexes, not tables.
</para>
</listitem>
</varlistentry>
@@ -256,13 +199,13 @@
<term><option>--exclude-index=<replaceable class="parameter">pattern</replaceable></option></term>
<listitem>
<para>
- Exclude checks on the indexes which match the specified
+ 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>
<para>
- This is similar to the <option>-R</option>
- <option>--exclude-relation</option> option, except that it applies only
- to indexes, not tables.
+ This is similar to the <option>--exclude-relation</option> option,
+ except that it applies only to indexes, not tables.
</para>
</listitem>
</varlistentry>
@@ -273,7 +216,7 @@
<listitem>
<para>
Use <replaceable>num</replaceable> concurrent connections to the server,
- or one per object to be checked, whichever number is smaller.
+ or one per object to be checked, whichever is less.
</para>
<para>
The default is to use a single connection.
@@ -285,20 +228,17 @@
<term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term>
<listitem>
<para>
- Specifies the name of the database to connect to to discover which
- databases should be checked, when
- <option>-a</option>/<option>--all</option> is used. If not specified,
- the <literal>postgres</literal> database will be used, or if that does
- not exist, <literal>template1</literal> will be used. This can be a
- <link linkend="libpq-connstring">connection string</link>. If so,
- connection string parameters will override any conflicting command line
- options. Also, connection string parameters other than the database
- name itself will be re-used when connecting to other databases.
- </para>
- <para>
- If a connection string is given which contains no database name, the other
- parameters of the string will be used while the database name to use is
- determined as described above.
+ 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>
@@ -307,14 +247,10 @@
<term><option>--no-dependent-indexes</option></term>
<listitem>
<para>
- When including a table relation in the list of relations to check, do
- not automatically include btree indexes associated with table.
- </para>
- <para>
- By default, all tables to be checked will also have checks performed on
- their associated btree indexes, if any. If this option is given, only
- those indexes which match a <option>--relation</option> or
- <option>--index</option> pattern will be checked.
+ 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>
@@ -323,17 +259,12 @@
<term><option>--no-strict-names</option></term>
<listitem>
<para>
- When calculating the list of databases to check, and the objects within
- those databases to be checked, do not raise an error for database,
- schema, relation, table, or index inclusion patterns which match no
- corresponding objects.
- </para>
- <para>
- Exclusion patterns are not required to match any objects, but by
- default unmatched inclusion patterns raise an error, including when
- they fail to match as a result of an exclusion pattern having
- prohibited them matching an existent object, and when they fail to
- match a database because it is unconnectable (datallowconn is false).
+ By default, if an argument to <literal>--database</literal>,
+ <literal>--table</literal>, <literal>--index</literal>,
+ or <literal>--relation</literal> matches no objects, it is a fatal
+ error. This option downgrades that error to a warning.
+ If this option is used with <literal>--quiet</literal>, the warning
+ will be supressed as well.
</para>
</listitem>
</varlistentry>
@@ -342,14 +273,10 @@
<term><option>--no-dependent-toast</option></term>
<listitem>
<para>
- When including a table relation in the list of relations to check, do
- not automatically include toast tables associated with table.
- </para>
- <para>
- By default, all tables to be checked will also have checks performed on
- their associated toast tables, if any. If this option is given, only
- those toast tables which match a <option>--relation</option> or
- <option>--table</option> pattern will be checked.
+ 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>
@@ -359,7 +286,7 @@
<listitem>
<para>
After reporting all corruptions on the first page of a table where
- corruptions are found, stop processing that table relation and move on
+ corruption is found, stop processing that table relation and move on
to the next table or index.
</para>
<para>
@@ -402,7 +329,11 @@
<term><option>--progress</option></term>
<listitem>
<para>
- Show progress information about how many relations have been checked.
+ 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>
@@ -412,11 +343,7 @@
<term><option>--quiet</option></term>
<listitem>
<para>
- Do not write additional messages beyond those about corruption.
- </para>
- <para>
- This option does not quiet any output specifically due to the use of
- the <option>-e</option> <option>--echo</option> option.
+ Print fewer messages, and less detail regarding any server errors.
</para>
</listitem>
</varlistentry>
@@ -426,27 +353,18 @@
<term><option>--relation=<replaceable class="parameter">pattern</replaceable></option></term>
<listitem>
<para>
- Perform checking on all relations matching the specified
- <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>
+ 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>
- This option may be specified multiple times to list more than one
- pattern.
- </para>
- <para>
- Patterns may be unqualified, or they may be schema-qualified or
- database- and schema-qualified, such as
- <literal>"my*relation"</literal>,
- <literal>"my*schema*.my*relation*"</literal>, or
- <literal>"my*database.my*schema.my*relation</literal>. There is no
- problem specifying relation patterns that match databases that are not
- otherwise included, as the relation in the matching database will still
- be checked.
- </para>
- <para>
- The <option>-R</option> <option>--exclude-relation</option> option takes
- precedence over <option>-r</option> <option>--relation</option>.
+ 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>
@@ -456,20 +374,15 @@
<term><option>--exclude-relation=<replaceable class="parameter">pattern</replaceable></option></term>
<listitem>
<para>
- Exclude checks on relations matching the specified
+ 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>-r</option> <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>
- <para>
- The <option>-R</option> <option>--exclude-relation</option> option takes
- precedence over <option>-r</option> <option>--relation</option>,
- <option>-t</option> <option>--table</option> and <option>-i</option>
- <option>--index</option>.
- </para>
</listitem>
</varlistentry>
@@ -500,26 +413,16 @@
<term><option>--schema=<replaceable class="parameter">pattern</replaceable></option></term>
<listitem>
<para>
- Perform checking in schemas matching the specified
- <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link> that are not 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 option may be specified multiple times to list more than one
- pattern for checking. By default, all objects in all matching schema(s)
- will be checked.
- </para>
- <para>
- Option <option>-S</option> <option>--exclude-schema</option> takes
- precedence over <option>-s</option> <option>--schema</option>.
- </para>
- <para>
- Note that both tables and indexes are included using this option, which
- might not be what you want if you are also using
- <option>--no-dependent-indexes</option>. To specify all tables in a
- schema without also specifying all indexes, <option>--table</option> can
- be used with a pattern that specifies the schema. For example, to check
- all tables in schema <literal>corp</literal>, the option
- <literal>--table="corp.*"</literal> may be used.
+ 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>
</listitem>
</varlistentry>
@@ -529,18 +432,9 @@
<term><option>--exclude-schema=<replaceable class="parameter">pattern</replaceable></option></term>
<listitem>
<para>
- Do not perform checking in schemas matching the specified
+ Exclude tables and indexes in schemas matching the specified
<link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>.
- </para>
- <para>
- This option may be specified multiple times to list more than one
- pattern for exclusion.
- </para>
- <para>
- If a schema which is included using
- <option>-s</option> <option>--schema</option> is also excluded using
- <option>-S</option> <option>--exclude-schema</option>, the schema will
- be excluded.
+ This option can be specified more than once.
</para>
</listitem>
</varlistentry>
@@ -553,12 +447,12 @@
will skip over pages in all tables that are marked as all frozen.
</para>
<para>
- If <literal>"all-visible"</literal> is given, table corruption checks
+ If <literal>all-visible</literal> is given, table corruption checks
will skip over pages in all tables that are marked as all visible.
</para>
<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
+ <literal>none</literal>, but since this is the default, it need not be
mentioned.
</para>
</listitem>
@@ -568,20 +462,11 @@
<term><option>--startblock=<replaceable class="parameter">block</replaceable></option></term>
<listitem>
<para>
- Check table blocks beginning with the specified block number. An error
- will occur if the table relation being checked has fewer than this number
- of blocks.
- </para>
- <para>
- By default, checking begins with block zero. This option will be applied to all
- table relations that are checked, including toast tables, but note
- that unless <option>--exclude-toast-pointers</option> is given, toast
- pointers found in the main table will be followed into the toast table
- without regard to the location in the toast table.
- </para>
- <para>
- This option does not apply to indexes, and is probably only useful when
- checking a single table.
+ 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>
@@ -591,13 +476,14 @@
<term><option>--table=<replaceable class="parameter">pattern</replaceable></option></term>
<listitem>
<para>
- Perform checks on all tables matching the specified
- <link linkend="app-psql-patterns"><replaceable class="parameter">pattern</replaceable></link>
+ 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>
- This is similar to the <option>-r</option> <option>--relation</option>
- option, except that it applies only to tables, not indexes.
+ This is similar to the <option>--relation</option> option, except that
+ it applies only to tables, not indexes.
</para>
</listitem>
</varlistentry>
@@ -607,13 +493,13 @@
<term><option>--exclude-table=<replaceable class="parameter">pattern</replaceable></option></term>
<listitem>
<para>
- Exclude checks on tables matching the specified
+ 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>-R</option>
- <option>--exclude-relation</option> option, except that it applies only
- to tables, not indexes.
+ This is similar to the <option>--exclude-relation</option> option,
+ except that it applies only to tables, not indexes.
</para>
</listitem>
</varlistentry>
@@ -633,8 +519,9 @@
<term><option>--verbose</option></term>
<listitem>
<para>
- Increases the log level verbosity. This option may be given more than
- once.
+ 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.
</para>
</listitem>
</varlistentry>