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.