begriffs open source - ai-pg/blob - full-docs/txt/app-pgamcheck.txt

   1
   2 pg_amcheck
   3
   4    pg_amcheck — checks for corruption in one or more PostgreSQL databases
   5
   6 Synopsis
   7
   8    pg_amcheck [option...] [dbname]
   9
  10 Description
  11
  12    pg_amcheck supports running amcheck's corruption checking functions
  13    against one or more databases, with options to select which schemas,
  14    tables and indexes to check, which kinds of checking to perform, and
  15    whether to perform the checks in parallel, and if so, the number of
  16    parallel connections to establish and use.
  17
  18    Only ordinary and toast table relations, materialized views, sequences,
  19    and btree indexes are currently supported. Other relation types are
  20    silently skipped.
  21
  22    If dbname is specified, it should be the name of a single database to
  23    check, and no other database selection options should be present.
  24    Otherwise, if any database selection options are present, all matching
  25    databases will be checked. If no such options are present, the default
  26    database will be checked. Database selection options include --all,
  27    --database and --exclude-database. They also include --relation,
  28    --exclude-relation, --table, --exclude-table, --index, and
  29    --exclude-index, but only when such options are used with a three-part
  30    pattern (e.g. mydb*.myschema*.myrel*). Finally, they include --schema
  31    and --exclude-schema when such options are used with a two-part pattern
  32    (e.g. mydb*.myschema*).
  33
  34    dbname can also be a connection string.
  35
  36 Options
  37
  38    The following command-line options control what is checked:
  39
  40    -a
  41           --all
  42           Check all databases, except for any excluded via
  43           --exclude-database.
  44
  45    -d pattern
  46           --database=pattern
  47           Check databases matching the specified pattern, except for any
  48           excluded by --exclude-database. This option can be specified
  49           more than once.
  50
  51    -D pattern
  52           --exclude-database=pattern
  53           Exclude databases matching the given pattern. This option can be
  54           specified more than once.
  55
  56    -i pattern
  57           --index=pattern
  58           Check indexes matching the specified pattern, unless they are
  59           otherwise excluded. This option can be specified more than once.
  60
  61           This is similar to the --relation option, except that it applies
  62           only to indexes, not to other relation types.
  63
  64    -I pattern
  65           --exclude-index=pattern
  66           Exclude indexes matching the specified pattern. This option can
  67           be specified more than once.
  68
  69           This is similar to the --exclude-relation option, except that it
  70           applies only to indexes, not other relation types.
  71
  72    -r pattern
  73           --relation=pattern
  74           Check relations matching the specified pattern, unless they are
  75           otherwise excluded. This option can be specified more than once.
  76
  77           Patterns may be unqualified, e.g. myrel*, or they may be
  78           schema-qualified, e.g. myschema*.myrel* or database-qualified
  79           and schema-qualified, e.g. mydb*.myschema*.myrel*. A
  80           database-qualified pattern will add matching databases to the
  81           list of databases to be checked.
  82
  83    -R pattern
  84           --exclude-relation=pattern
  85           Exclude relations matching the specified pattern. This option
  86           can be specified more than once.
  87
  88           As with --relation, the pattern may be unqualified,
  89           schema-qualified, or database- and schema-qualified.
  90
  91    -s pattern
  92           --schema=pattern
  93           Check tables and indexes in schemas matching the specified
  94           pattern, unless they are otherwise excluded. This option can be
  95           specified more than once.
  96
  97           To select only tables in schemas matching a particular pattern,
  98           consider using something like --table=SCHEMAPAT.*
  99           --no-dependent-indexes. To select only indexes, consider using
 100           something like --index=SCHEMAPAT.*.
 101
 102           A schema pattern may be database-qualified. For example, you may
 103           write --schema=mydb*.myschema* to select schemas matching
 104           myschema* in databases matching mydb*.
 105
 106    -S pattern
 107           --exclude-schema=pattern
 108           Exclude tables and indexes in schemas matching the specified
 109           pattern. This option can be specified more than once.
 110
 111           As with --schema, the pattern may be database-qualified.
 112
 113    -t pattern
 114           --table=pattern
 115           Check tables matching the specified pattern, unless they are
 116           otherwise excluded. This option can be specified more than once.
 117
 118           This is similar to the --relation option, except that it applies
 119           only to tables, materialized views, and sequences, not to
 120           indexes.
 121
 122    -T pattern
 123           --exclude-table=pattern
 124           Exclude tables matching the specified pattern. This option can
 125           be specified more than once.
 126
 127           This is similar to the --exclude-relation option, except that it
 128           applies only to tables, materialized views, and sequences, not
 129           to indexes.
 130
 131    --no-dependent-indexes
 132           By default, if a table is checked, any btree indexes of that
 133           table will also be checked, even if they are not explicitly
 134           selected by an option such as --index or --relation. This option
 135           suppresses that behavior.
 136
 137    --no-dependent-toast
 138           By default, if a table is checked, its toast table, if any, will
 139           also be checked, even if it is not explicitly selected by an
 140           option such as --table or --relation. This option suppresses
 141           that behavior.
 142
 143    --no-strict-names
 144           By default, if an argument to --database, --table, --index, or
 145           --relation matches no objects, it is a fatal error. This option
 146           downgrades that error to a warning.
 147
 148    The following command-line options control checking of tables:
 149
 150    --exclude-toast-pointers
 151           By default, whenever a toast pointer is encountered in a table,
 152           a lookup is performed to ensure that it references
 153           apparently-valid entries in the toast table. These checks can be
 154           quite slow, and this option can be used to skip them.
 155
 156    --on-error-stop
 157           After reporting all corruptions on the first page of a table
 158           where corruption is found, stop processing that table relation
 159           and move on to the next table or index.
 160
 161           Note that index checking always stops after the first corrupt
 162           page. This option only has meaning relative to table relations.
 163
 164    --skip=option
 165           If all-frozen is given, table corruption checks will skip over
 166           pages in all tables that are marked as all frozen.
 167
 168           If all-visible is given, table corruption checks will skip over
 169           pages in all tables that are marked as all visible.
 170
 171           By default, no pages are skipped. This can be specified as none,
 172           but since this is the default, it need not be mentioned.
 173
 174    --startblock=block
 175           Start checking at the specified block number. An error will
 176           occur if the table relation being checked has fewer than this
 177           number of blocks. This option does not apply to indexes, and is
 178           probably only useful when checking a single table relation. See
 179           --endblock for further caveats.
 180
 181    --endblock=block
 182           End checking at the specified block number. An error will occur
 183           if the table relation being checked has fewer than this number
 184           of blocks. This option does not apply to indexes, and is
 185           probably only useful when checking a single table relation. If
 186           both a regular table and a toast table are checked, this option
 187           will apply to both, but higher-numbered toast blocks may still
 188           be accessed while validating toast pointers, unless that is
 189           suppressed using --exclude-toast-pointers.
 190
 191    The following command-line options control checking of B-tree indexes:
 192
 193    --checkunique
 194           For each index with unique constraint checked, verify that no
 195           more than one among duplicate entries is visible in the index
 196           using amcheck's checkunique option.
 197
 198    --heapallindexed
 199           For each index checked, verify the presence of all heap tuples
 200           as index tuples in the index using amcheck's heapallindexed
 201           option.
 202
 203    --parent-check
 204           For each btree index checked, use amcheck's
 205           bt_index_parent_check function, which performs additional checks
 206           of parent/child relationships during index checking.
 207
 208           The default is to use amcheck's bt_index_check function, but
 209           note that use of the --rootdescend option implicitly selects
 210           bt_index_parent_check.
 211
 212    --rootdescend
 213           For each index checked, re-find tuples on the leaf level by
 214           performing a new search from the root page for each tuple using
 215           amcheck's rootdescend option.
 216
 217           Use of this option implicitly also selects the --parent-check
 218           option.
 219
 220           This form of verification was originally written to help in the
 221           development of btree index features. It may be of limited use or
 222           even of no use in helping detect the kinds of corruption that
 223           occur in practice. It may also cause corruption checking to take
 224           considerably longer and consume considerably more resources on
 225           the server.
 226
 227 Warning
 228
 229    The extra checks performed against B-tree indexes when the
 230    --parent-check option or the --rootdescend option is specified require
 231    relatively strong relation-level locks. These checks are the only
 232    checks that will block concurrent data modification from INSERT,
 233    UPDATE, and DELETE commands.
 234
 235    The following command-line options control the connection to the
 236    server:
 237
 238    -h hostname
 239           --host=hostname
 240           Specifies the host name of the machine on which the server is
 241           running. If the value begins with a slash, it is used as the
 242           directory for the Unix domain socket.
 243
 244    -p port
 245           --port=port
 246           Specifies the TCP port or local Unix domain socket file
 247           extension on which the server is listening for connections.
 248
 249    -U
 250           --username=username
 251           User name to connect as.
 252
 253    -w
 254           --no-password
 255           Never issue a password prompt. If the server requires password
 256           authentication and a password is not available by other means
 257           such as a .pgpass file, the connection attempt will fail. This
 258           option can be useful in batch jobs and scripts where no user is
 259           present to enter a password.
 260
 261    -W
 262           --password
 263           Force pg_amcheck to prompt for a password before connecting to a
 264           database.
 265
 266           This option is never essential, since pg_amcheck will
 267           automatically prompt for a password if the server demands
 268           password authentication. However, pg_amcheck will waste a
 269           connection attempt finding out that the server wants a password.
 270           In some cases it is worth typing -W to avoid the extra
 271           connection attempt.
 272
 273    --maintenance-db=dbname
 274           Specifies a database or connection string to be used to discover
 275           the list of databases to be checked. If neither --all nor any
 276           option including a database pattern is used, no such connection
 277           is required and this option does nothing. Otherwise, any
 278           connection string parameters other than the database name which
 279           are included in the value for this option will also be used when
 280           connecting to the databases being checked. If this option is
 281           omitted, the default is postgres or, if that fails, template1.
 282
 283    Other options are also available:
 284
 285    -e
 286           --echo
 287           Echo to stdout all SQL sent to the server.
 288
 289    -j num
 290           --jobs=num
 291           Use num concurrent connections to the server, or one per object
 292           to be checked, whichever is less.
 293
 294           The default is to use a single connection.
 295
 296    -P
 297           --progress
 298           Show progress information. Progress information includes the
 299           number of relations for which checking has been completed, and
 300           the total size of those relations. It also includes the total
 301           number of relations that will eventually be checked, and the
 302           estimated size of those relations.
 303
 304    -v
 305           --verbose
 306           Print more messages. In particular, this will print a message
 307           for each relation being checked, and will increase the level of
 308           detail shown for server errors.
 309
 310    -V
 311           --version
 312           Print the pg_amcheck version and exit.
 313
 314    --install-missing
 315           --install-missing=schema
 316           Install any missing extensions that are required to check the
 317           database(s). If not yet installed, each extension's objects will
 318           be installed into the given schema, or if not specified into
 319           schema pg_catalog.
 320
 321           At present, the only required extension is amcheck.
 322
 323    -?
 324           --help
 325           Show help about pg_amcheck command line arguments, and exit.
 326
 327 Environment
 328
 329    pg_amcheck, like most other PostgreSQL utilities, also uses the
 330    environment variables supported by libpq (see Section 32.15).
 331
 332    The environment variable PG_COLOR specifies whether to use color in
 333    diagnostic messages. Possible values are always, auto and never.
 334
 335 Notes
 336
 337    pg_amcheck is designed to work with PostgreSQL 14.0 and later.
 338
 339 See Also
 340
 341    amcheck