PG_AMCHECK(1)

📦 version 16.15, in opensuse-leap 16.0

💅 PG_AMCHECK(1) — PostgreSQL 16.15 Documentation 🎀

okay bestie, sit down, grab a strawberry drink 🍓, because we're about to talk about pg_amcheck — yes that's the PostgreSQL 16.15 documentation, and yes it's giving main character energy fr fr ✨

🌸 NAME 🌸

pg_amcheck — the tool that checks for corruption in one or more PostgreSQL databases 💀 like, it literally goes looking for the bad vibes inside your data.

🦋 SYNOPSIS 🦋

pg_amcheck [option...] [dbname]

that's it. that's the whole vibe check. periodt 💅

✨ DESCRIPTION ✨

okay so pg_amcheck is the bestie that runs amcheck's corruption checking functions against one or more databases 🫶 and like, it's lowkey flexible — you get options to pick which schemas, tables, and indexes to check 👑, which kinds of checking to perform, and whether to do the checks in parallel, and if so, how many parallel connections to establish and use 🔥

Heads up on what's supported: only ordinary and toast table relations, materialized views, sequences, and btree indexes are currently supported. Any other relation types? silently skipped 🙈 like they're not even invited to the party, no note, no nothing.

🌈 picking your databases 🌈

so here's the tea on how it decides what to check ☕

  • if dbname is specified, it should be the name of a single database to check, and no other database selection options should be present 🚫 — like, one database, one main character, no plus-ones.
  • otherwise, if any database selection options are present, all matching databases will be checked 💖 — the whole group chat.
  • if no such options are present, the default database will be checked ⭐ — the fallback bestie.

🧚 database selection options include:

  • --all
  • --database
  • --exclude-database

these also count as database selection options, but only when used with a three-part pattern (e.g. mydb*.myschema*.myrel*):

  • --relation
  • --exclude-relation
  • --table
  • --exclude-table
  • --index
  • --exclude-index

and finally these count too — but only when used with a two-part pattern (e.g. mydb*.myschema*):

  • --schema
  • --exclude-schema
🎀 oh and one more thing — dbname can also be a connection string. iconic, honestly. ✨

...to be continued, bestie — there's more, don't go anywhere 💜

✨ OPTIONS ✨

Okay bestie, here's where the real tea gets spilled 💅 — the following command-line options control what is checked:

  • -a, --all — Check all databases, except for any excluded via --exclude-database. Literally all of them, no cap.
  • *-d *pattern, --database=pattern — Check databases matching the specified pattern, except for any excluded by --exclude-database. This option can be specified more than once, so go off 🫶
  • *-D *pattern, --exclude-database=pattern — Exclude databases matching the given pattern. This option can be specified more than once. Not me ghosting those databases fr.
  • *-i *pattern, --index=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 --relation option, except that it applies only to indexes, not to other relation types. Read that again, bestie — indexes only 👑

  • *-I *pattern, --exclude-index=pattern — Exclude indexes matching the specified pattern. This option can be specified more than once.

This is similar to the --exclude-relation option, except that it applies only to indexes, not other relation types.

  • *-r *pattern, --relation=pattern — Check relations matching the specified pattern, unless they are otherwise excluded. This option can be specified more than once.

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*.myschema*.myrel*. A database-qualified pattern will add matching databases to the list of databases to be checked. It's giving ✨main character pattern matching✨.

  • *-R *pattern, --exclude-relation=pattern — Exclude relations matching the specified pattern. This option can be specified more than once.

As with --relation, the pattern may be unqualified, schema-qualified, or database- and schema-qualified.

  • *-s *pattern, --schema=pattern — Check tables and indexes in schemas matching the specified pattern, unless they are otherwise excluded. This option can be specified more than once.

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.*. Lowkey genius honestly.

A schema pattern may be database-qualified. For example, you may write --schema=mydb*.myschema* to select schemas matching myschema* in databases matching mydb*.

  • *-S *pattern, --exclude-schema=pattern — Exclude tables and indexes in schemas matching the specified pattern. This option can be specified more than once.

As with --schema, the pattern may be database-qualified.

  • *-t *pattern, --table=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 --relation option, except that it applies only to tables, materialized views, and sequences, not to indexes. Know the difference, bestie 💖

  • *-T *pattern, --exclude-table=pattern — Exclude tables matching the specified pattern. This option can be specified more than once.

This is similar to the --exclude-relation option, except that it applies only to tables, materialized views, and sequences, not to indexes.

  • --no-dependent-indexes — 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. So yeah, it stops the plus-ones from coming along 🎀
  • --no-dependent-toast — 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.
  • --no-strict-names — 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. So it goes from 💀 to 🙈.

🍓 Options that control checking of tables

  • --exclude-toast-pointers — 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. Slow and optional? yeah, skip it if you want, no judgment.
  • --on-error-stop — After reporting all corruptions on the first page of a table where corruption is found, stop processing that table relation and move on to the next table or index.

Note that index checking always stops after the first corrupt page. This option only has meaning relative to table relations. Periodt.

  • *--skip=option* — If all-frozen is given, table corruption checks will skip over pages in all tables that are marked as all frozen.

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 mentioned.

  • *--startblock=block* — 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.
  • *--endblock=block* — 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 --exclude-toast-pointers. Sneaky, I know 😭

🌈 Options that control checking of B-tree indexes

  • --heapallindexed — For each index checked, verify the presence of all heap tuples as index tuples in the index using amcheck's heapallindexed option. Checkin' everybody's presence like a group chat roll call 💅
  • --parent-check — For each btree index checked, use amcheck's bt_index_parent_check function, which performs additional checks of parent/child relationships during index checking.

The default is to use amcheck's bt_index_check function, but note that use of the --rootdescend option implicitly selects bt_index_parent_check.

  • --rootdescend — For each index checked, re-find tuples on the leaf level by performing a new search from the root page for each tuple using amcheck's rootdescend option.

Use of this option implicitly also selects the --parent-check option.

This form of verification was originally written to help in the development of btree index features. It may be of limited use or even of no use in helping detect the kinds of corruption that occur in practice. It may also cause corruption checking to take considerably longer and consume considerably more resources on the server. Like, it's iconic but it's also a lot, yk?

Warning ⚠️ The extra checks performed against B-tree indexes when the --parent-check option or the --rootdescend option is specified require relatively strong relation-level locks. These checks are the only checks that will block concurrent data modification from INSERT, UPDATE, and DELETE commands. So yeah, this one actually blocks people — be aware before you hit go 🫶

🦋 Options that control the connection to the server

  • *-h *hostname, --host=hostname — 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.
  • *-p *port, --port=port — Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections.
  • *-U, --username=username* — User name to connect as.
  • -w, --no-password — Never issue a password prompt. If the server requires password authentication and a password is not available by other means such as a .pgpass 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. Built for the unattended era ✨
  • -W, --password — Force pg_amcheck to prompt for a password before connecting to a database.

This option is never essential, since pg_amcheck will automatically prompt for a password if the server demands password authentication. However, pg_amcheck will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt. Save yourself the round trip, bestie 🎀

  • *--maintenance-db=dbname* — Specifies a database or connection string to be used to discover the list of databases to be checked. If neither --all 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.

🧚 Other options are also available:

  • -e, --echo — Echo to stdout all SQL sent to the server. Full transparency, we love to see it.
  • *-j *num, --jobs=num — Use num concurrent connections to the server, or one per object to be checked, whichever is less.

The default is to use a single connection. Multitask, queen 👑

  • -P, --progress — 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. The little bar is honestly so satisfying.
  • -v, --verbose — 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.
  • -V, --version — Print the pg_amcheck version and exit.
  • --install-missing, *--install-missing=schema* — 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 schema, or if not specified into schema pg_catalog.

At present, the only required extension is amcheck.

  • -?, --help — Show help about pg_amcheck command line arguments, and exit.

🌸 NOTES 🌸

pg_amcheck is designed to work with PostgreSQL 14.0 and later. Older versions? Not invited to the party, sorry 🎀

💜 SEE ALSO 💜

amcheck

And that's the whole thing, bestie — you made it to the end 🫶✨ This was PostgreSQL 16.15, dated 2026, filed under PG_AMCHECK(1). Go forth and check those pages, ily, bye 💅💖

📦 where this page comes from