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.
+
+ If dbname 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
+ , and
+ . They also include
+ , ,
+ , ,
+ , and ,
+ but only when such options are used with a three-part pattern
+ (e.g. ).
+
+
+
+ dbname can also be a
+ connection string.
+
@@ -51,47 +70,13 @@
pg_amcheck accepts the following command-line arguments:
-
-
-
-
-
- Specifies the name of a database to be checked, or a connection string
- to use while connecting.
-
-
- If no dbname is specified, and if
- is not used, the database name
- is read from the environment variable PGDATABASE. If
- that is not set, the user name specified for the connection is used.
- The dbname can be a connection string. 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.
-
-
- 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.
-
-
-
-
- Perform checking in all databases which are not otherwise excluded.
-
-
- In the absence of any other options, selects all objects across all
- schemas and databases.
-
-
- Option takes
- precedence over .
+ Check all databases, except for any excluded via
+ .
@@ -101,22 +86,10 @@
- Perform checking in databases matching the specified
- pattern
- that are not otherwise excluded.
-
-
- This option may be specified multiple times to list more than one
- pattern. By default, all objects in all matching databases will be
- checked.
-
-
- If is also specified,
- has no effect.
-
-
- Option takes
- precedence over .
+ Check databases matching the specified
+ pattern,
+ except for any excluded by .
+ This option can be specified more than once.
@@ -126,20 +99,9 @@
- Do not include databases matching other patterns or included by option
- if they also match the
- specified exclusion
+ Exclude databases matching the given
pattern.
-
-
- This does not exclude any database that was listed explicitly as a
- dbname on the command line, nor does it exclude
- the database chosen in the absence of any
- dbname argument.
-
-
- This option may be specified multiple times to list more than one
- exclusion pattern.
+ This option can be specified more than once.
@@ -149,8 +111,7 @@
- Print to stdout all commands and queries being executed against the
- server.
+ Echo to stdout all SQL sent to the server.
@@ -159,21 +120,13 @@
- 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.
-
-
- 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
- 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.
-
-
+ 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 .
@@ -182,21 +135,10 @@
- When checking main relations, do not look up entries in toast tables
- corresponding to toast pointers in the main relation.
-
-
- 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.
-
-
- The process by which 's
- verify_heapam 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.
@@ -240,13 +182,14 @@
- Perform checks on indexes which match the specified
- pattern
+ Check indexes matching the specified
+ pattern,
unless they are otherwise excluded.
+ This option can be specified more than once.
- This is similar to the
- option, except that it applies only to indexes, not tables.
+ This is similar to the option, except that
+ it applies only to indexes, not tables.
@@ -256,13 +199,13 @@
- Exclude checks on the indexes which match the specified
+ Exclude indexes matching the specified
pattern.
+ This option can be specified more than once.
- This is similar to the
- option, except that it applies only
- to indexes, not tables.
+ This is similar to the option,
+ except that it applies only to indexes, not tables.
@@ -273,7 +216,7 @@
Use num 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.
The default is to use a single connection.
@@ -285,20 +228,17 @@
- Specifies the name of the database to connect to to discover which
- databases should be checked, when
- / is used. If not specified,
- the postgres database will be used, or if that does
- not exist, template1 will be used. This can be a
- connection string. 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.
-
-
- 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
+ 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.
@@ -307,14 +247,10 @@
- When including a table relation in the list of relations to check, do
- not automatically include btree indexes associated with table.
-
-
- 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 or
- 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 --index or
+ --relation. This option suppresses that behavior.
@@ -323,17 +259,12 @@
- 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.
-
-
- 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 --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.
@@ -342,14 +273,10 @@
- When including a table relation in the list of relations to check, do
- not automatically include toast tables associated with table.
-
-
- 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 or
- 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 --table or --relation.
+ This option suppresses that behavior.
@@ -359,7 +286,7 @@
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.
@@ -402,7 +329,11 @@
- 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.
@@ -412,11 +343,7 @@
- Do not write additional messages beyond those about corruption.
-
-
- This option does not quiet any output specifically due to the use of
- the option.
+ Print fewer messages, and less detail regarding any server errors.
@@ -426,27 +353,18 @@
- Perform checking on all relations matching the specified
- pattern
+ Check relations matching the specified
+ pattern,
unless they are otherwise excluded.
+ This option can be specified more than once.
- This option may be specified multiple times to list more than one
- pattern.
-
-
- Patterns may be unqualified, or they may be schema-qualified or
- database- and schema-qualified, such as
- "my*relation",
- "my*schema*.my*relation*", or
- "my*database.my*schema.my*relation. 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.
-
-
- The option takes
- precedence over .
+ Patterns may be unqualified, e.g. myrel*, or they
+ may be schema-qualified, e.g. myschema*.myrel* or
+ database-qualified and schema-qualified, e.g.
+ mydb*.myscheam*.myrel*. A database-qualified
+ pattern will add matching databases to the list of databases to be
+ checked.
@@ -456,20 +374,15 @@
- Exclude checks on relations matching the specified
+ Exclude relations matching the specified
pattern.
+ This option can be specified more than once.
As with , the
pattern may be unqualified, schema-qualified,
or database- and schema-qualified.
-
- The option takes
- precedence over ,
- and
- .
-
@@ -500,26 +413,16 @@
- Perform checking in schemas matching the specified
- pattern that are not otherwise excluded.
+ Check tables and indexes in schemas matching the specified
+ pattern, unless they are otherwise excluded.
+ This option can be specified more than once.
- 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.
-
-
- Option takes
- precedence over .
-
-
- Note that both tables and indexes are included using this option, which
- might not be what you want if you are also using
- . To specify all tables in a
- schema without also specifying all indexes, can
- be used with a pattern that specifies the schema. For example, to check
- all tables in schema corp, the option
- --table="corp.*" may be used.
+ To select only tables in schemas matching a particular pattern,
+ consider using something like
+ --table=SCHEMAPAT.* --no-dependent-indexes.
+ To select only indexes, consider using something like
+ --index=SCHEMAPAT.*.
@@ -529,18 +432,9 @@
- Do not perform checking in schemas matching the specified
+ Exclude tables and indexes in schemas matching the specified
pattern.
-
-
- This option may be specified multiple times to list more than one
- pattern for exclusion.
-
-
- If a schema which is included using
- is also excluded using
- , the schema will
- be excluded.
+ This option can be specified more than once.
@@ -553,12 +447,12 @@
will skip over pages in all tables that are marked as all frozen.
- If "all-visible" is given, table corruption checks
+ 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
+ none, but since this is the default, it need not be
mentioned.
@@ -568,20 +462,11 @@
- 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.
-
-
- 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 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.
-
-
- 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 --endblock
+ for further caveats.
@@ -591,13 +476,14 @@
- Perform checks on all tables matching the specified
- pattern
+ Check tables matching the specified
+ pattern,
unless they are otherwise excluded.
+ This option can be specified more than once.
- This is similar to the
- option, except that it applies only to tables, not indexes.
+ This is similar to the option, except that
+ it applies only to tables, not indexes.
@@ -607,13 +493,13 @@
- Exclude checks on tables matching the specified
+ Exclude tables matching the specified
pattern.
+ This option can be specified more than once.
- This is similar to the
- option, except that it applies only
- to tables, not indexes.
+ This is similar to the option,
+ except that it applies only to tables, not indexes.
@@ -633,8 +519,9 @@
- 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.