Adding upstream version 14.5.upstream/14.5 upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
author: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-05-04 12:15:05 +0000
committer: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-05-04 12:15:05 +0000
commit: 46651ce6fe013220ed397add242004d764fc0153 (patch)
tree: 6e5299f990f88e60174a1d3ae6e48eedd2688b2b /doc/src/sgml/html/app-pgamcheck.html
parent: Initial commit. (diff)
download: postgresql-14-upstream.tar.xz
postgresql-14-upstream.zip
1 files changed, 292 insertions, 0 deletions
diff --git a/doc/src/sgml/html/app-pgamcheck.html b/doc/src/sgml/html/app-pgamcheck.html
new file mode 100644
index 0000000..085da06
--- /dev/null
+++ b/doc/src/sgml/html/app-pgamcheck.html
@@ -0,0 +1,292 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_amcheck</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-ecpg.html" title="ecpg" /><link rel="next" href="app-pgbasebackup.html" title="pg_basebackup" /></head><body id="docContent" class="container-fluid col-10"><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span xmlns="http://www.w3.org/1999/xhtml" class="application">pg_amcheck</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-ecpg.html" title="ecpg">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 14.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgbasebackup.html" title="pg_basebackup">Next</a></td></tr></table><hr></hr></div><div class="refentry" id="APP-PGAMCHECK"><div class="titlepage"></div><a id="id-1.9.4.9.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_amcheck</span></span></h2><p>pg_amcheck — checks for corruption in one or more
+  <span class="productname">PostgreSQL</span> databases</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.9.4.1"><code class="command">pg_amcheck</code> [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>dbname</code></em>]</p></div></div><div class="refsect1" id="id-1.9.4.9.5"><h2>Description</h2><p>
+   <span class="application">pg_amcheck</span> supports running
+   <a class="xref" href="amcheck.html" title="F.2. amcheck">amcheck</a>'s corruption checking functions against one or
+   more databases, with options to select which schemas, tables and indexes to
+   check, which kinds of checking to perform, and whether to perform the checks
+   in parallel, and if so, the number of parallel connections to establish and
+   use.
+  </p><p>
+   Only table relations and btree indexes are currently supported.  Other
+   relation types are silently skipped.
+  </p><p>
+   If <code class="literal">dbname</code> 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
+   <code class="option">--all</code>, <code class="option">--database</code> and
+   <code class="option">--exclude-database</code>. They also include
+   <code class="option">--relation</code>, <code class="option">--exclude-relation</code>,
+   <code class="option">--table</code>, <code class="option">--exclude-table</code>,
+   <code class="option">--index</code>, and <code class="option">--exclude-index</code>,
+   but only when such options are used with a three-part pattern
+   (e.g. <code class="option">mydb*.myschema*.myrel*</code>).  Finally, they include
+   <code class="option">--schema</code> and <code class="option">--exclude-schema</code>
+   when such options are used with a two-part pattern
+   (e.g. <code class="option">mydb*.myschema*</code>).
+  </p><p>
+   <em class="replaceable"><code>dbname</code></em> can also be a
+   <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a>.
+  </p></div><div class="refsect1" id="id-1.9.4.9.6"><h2>Options</h2><p>
+   The following command-line options control what is checked:
+
+   </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-a</code><br /></span><span class="term"><code class="option">--all</code></span></dt><dd><p>
+       Check all databases, except for any excluded via
+       <code class="option">--exclude-database</code>.
+      </p></dd><dt><span class="term"><code class="option">-d <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--database=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+       Check databases matching the specified
+       <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>,
+       except for any excluded by <code class="option">--exclude-database</code>.
+       This option can be specified more than once.
+      </p></dd><dt><span class="term"><code class="option">-D <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--exclude-database=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+       Exclude databases matching the given
+       <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>.
+       This option can be specified more than once.
+      </p></dd><dt><span class="term"><code class="option">-i <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--index=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+       Check indexes matching the specified
+       <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>,
+       unless they are otherwise excluded.
+       This option can be specified more than once.
+      </p><p>
+       This is similar to the <code class="option">--relation</code> option, except that
+       it applies only to indexes, not tables.
+      </p></dd><dt><span class="term"><code class="option">-I <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--exclude-index=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+       Exclude indexes matching the specified
+       <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>.
+       This option can be specified more than once.
+      </p><p>
+       This is similar to the <code class="option">--exclude-relation</code> option,
+       except that it applies only to indexes, not tables.
+      </p></dd><dt><span class="term"><code class="option">-r <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--relation=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+       Check relations matching the specified
+       <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>,
+       unless they are otherwise excluded.
+       This option can be specified more than once.
+      </p><p>
+       Patterns may be unqualified, e.g. <code class="literal">myrel*</code>, or they
+       may be schema-qualified, e.g. <code class="literal">myschema*.myrel*</code> or
+       database-qualified and schema-qualified, e.g.
+       <code class="literal">mydb*.myscheam*.myrel*</code>. A database-qualified
+       pattern will add matching databases to the list of databases to be
+       checked.
+      </p></dd><dt><span class="term"><code class="option">-R <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--exclude-relation=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+       Exclude relations matching the specified
+       <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>.
+       This option can be specified more than once.
+      </p><p>
+       As with <code class="option">--relation</code>, the
+       <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> may be unqualified, schema-qualified,
+       or database- and schema-qualified.
+      </p></dd><dt><span class="term"><code class="option">-s <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--schema=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+       Check tables and indexes in schemas matching the specified
+       <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>, unless they are otherwise excluded.
+       This option can be specified more than once.
+      </p><p>
+       To select only tables in schemas matching a particular pattern,
+       consider using something like
+       <code class="literal">--table=SCHEMAPAT.* --no-dependent-indexes</code>.
+       To select only indexes, consider using something like
+       <code class="literal">--index=SCHEMAPAT.*</code>.
+      </p><p>
+       A schema pattern may be database-qualified. For example, you may
+       write <code class="literal">--schema=mydb*.myschema*</code> to select
+       schemas matching <code class="literal">myschema*</code> in databases matching
+       <code class="literal">mydb*</code>.
+      </p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--exclude-schema=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+       Exclude tables and indexes in schemas matching the specified
+       <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>.
+       This option can be specified more than once.
+      </p><p>
+       As with <code class="option">--schema</code>, the pattern may be
+       database-qualified.
+      </p></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--table=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+       Check tables matching the specified
+       <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>,
+       unless they are otherwise excluded.
+       This option can be specified more than once.
+      </p><p>
+       This is similar to the <code class="option">--relation</code> option, except that
+       it applies only to tables, not indexes.
+      </p></dd><dt><span class="term"><code class="option">-T <em class="replaceable"><code>pattern</code></em></code><br /></span><span class="term"><code class="option">--exclude-table=<em class="replaceable"><code>pattern</code></em></code></span></dt><dd><p>
+       Exclude tables matching the specified
+       <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a>.
+       This option can be specified more than once.
+      </p><p>
+       This is similar to the <code class="option">--exclude-relation</code> option,
+       except that it applies only to tables, not indexes.
+      </p></dd><dt><span class="term"><code class="option">--no-dependent-indexes</code></span></dt><dd><p>
+       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 <code class="literal">--index</code> or
+       <code class="literal">--relation</code>. This option suppresses that behavior.
+      </p></dd><dt><span class="term"><code class="option">--no-dependent-toast</code></span></dt><dd><p>
+       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 <code class="literal">--table</code> or <code class="literal">--relation</code>.
+       This option suppresses that behavior.
+      </p></dd><dt><span class="term"><code class="option">--no-strict-names</code></span></dt><dd><p>
+       By default, if an argument to <code class="literal">--database</code>,
+       <code class="literal">--table</code>, <code class="literal">--index</code>,
+       or <code class="literal">--relation</code> matches no objects, it is a fatal
+       error. This option downgrades that error to a warning.
+      </p></dd></dl></div><p>
+  </p><p>
+   The following command-line options control checking of tables:
+
+   </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--exclude-toast-pointers</code></span></dt><dd><p>
+       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.
+      </p></dd><dt><span class="term"><code class="option">--on-error-stop</code></span></dt><dd><p>
+       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.
+      </p><p>
+       Note that index checking always stops after the first corrupt page.
+       This option only has meaning relative to table relations.
+      </p></dd><dt><span class="term"><code class="option">--skip=<em class="replaceable"><code>option</code></em></code></span></dt><dd><p>
+       If <code class="literal">all-frozen</code> is given, table corruption checks
+       will skip over pages in all tables that are marked as all frozen.
+      </p><p>
+       If <code class="literal">all-visible</code> is given, table corruption checks
+       will skip over pages in all tables that are marked as all visible.
+      </p><p>
+       By default, no pages are skipped.  This can be specified as
+       <code class="literal">none</code>, but since this is the default, it need not be
+       mentioned.
+      </p></dd><dt><span class="term"><code class="option">--startblock=<em class="replaceable"><code>block</code></em></code></span></dt><dd><p>
+       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 <code class="literal">--endblock</code>
+       for further caveats.
+      </p></dd><dt><span class="term"><code class="option">--endblock=<em class="replaceable"><code>block</code></em></code></span></dt><dd><p>
+       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
+       <code class="option">--exclude-toast-pointers</code>.
+      </p></dd></dl></div><p>
+  </p><p>
+   The following command-line options control checking of B-tree indexes:
+
+   </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--heapallindexed</code></span></dt><dd><p>
+       For each index checked, verify the presence of all heap tuples as index
+       tuples in the index using <a class="xref" href="amcheck.html" title="F.2. amcheck">amcheck</a>'s
+       <code class="option">heapallindexed</code> option.
+      </p></dd><dt><span class="term"><code class="option">--parent-check</code></span></dt><dd><p>
+       For each btree index checked, use <a class="xref" href="amcheck.html" title="F.2. amcheck">amcheck</a>'s
+       <code class="function">bt_index_parent_check</code> function, which performs
+       additional checks of parent/child relationships during index checking.
+      </p><p>
+       The default is to use <span class="application">amcheck</span>'s
+       <code class="function">bt_index_check</code> function, but note that use of the
+       <code class="option">--rootdescend</code> option implicitly selects
+       <code class="function">bt_index_parent_check</code>.
+      </p></dd><dt><span class="term"><code class="option">--rootdescend</code></span></dt><dd><p>
+       For each index checked, re-find tuples on the leaf level by performing a
+       new search from the root page for each tuple using
+       <a class="xref" href="amcheck.html" title="F.2. amcheck">amcheck</a>'s <code class="option">rootdescend</code> option.
+      </p><p>
+       Use of this option implicitly also selects the
+       <code class="option">--parent-check</code> option.
+      </p><p>
+       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.
+      </p></dd></dl></div><p>
+  </p><div class="warning"><h3 class="title">Warning</h3><p>
+    The extra checks performed against B-tree indexes when the
+    <code class="option">--parent-check</code> option or the
+    <code class="option">--rootdescend</code> option is specified require
+    relatively strong relation-level locks.  These checks are the only
+    checks that will block concurrent data modification from
+    <code class="command">INSERT</code>, <code class="command">UPDATE</code>, and
+    <code class="command">DELETE</code> commands.
+   </p></div><p>
+   The following command-line options control the connection to the server:
+
+   </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-h <em class="replaceable"><code>hostname</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>hostname</code></em></code></span></dt><dd><p>
+       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></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+       Specifies the TCP port or local Unix domain socket file extension on
+       which the server is listening for connections.
+      </p></dd><dt><span class="term"><code class="option">-U</code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+       User name to connect as.
+      </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+       Never issue a password prompt.  If the server requires password
+       authentication and a password is not available by other means such as
+       a <code class="filename">.pgpass</code> 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.
+      </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+       Force <span class="application">pg_amcheck</span> to prompt for a password
+       before connecting to a database.
+      </p><p>
+       This option is never essential, since
+       <span class="application">pg_amcheck</span> will automatically prompt for a
+       password if the server demands password authentication.  However,
+       <span class="application">pg_amcheck</span> will waste a connection attempt
+       finding out that the server wants a password.  In some cases it is
+       worth typing <code class="option">-W</code> to avoid the extra connection attempt.
+      </p></dd><dt><span class="term"><code class="option">--maintenance-db=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
+       Specifies a database or
+       <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a> to be
+       used to discover the list of databases to be checked. If neither
+       <code class="option">--all</code> 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
+       <code class="literal">postgres</code> or, if that fails,
+       <code class="literal">template1</code>.
+      </p></dd></dl></div><p>
+  </p><p>
+   Other options are also available:
+
+   </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--echo</code></span></dt><dd><p>
+      Echo to stdout all SQL sent to the server.
+      </p></dd><dt><span class="term"><code class="option">-j <em class="replaceable"><code>num</code></em></code><br /></span><span class="term"><code class="option">--jobs=<em class="replaceable"><code>num</code></em></code></span></dt><dd><p>
+       Use <em class="replaceable"><code>num</code></em> concurrent connections to the server,
+       or one per object to be checked, whichever is less.
+      </p><p>
+       The default is to use a single connection.
+      </p></dd><dt><span class="term"><code class="option">-P</code><br /></span><span class="term"><code class="option">--progress</code></span></dt><dd><p>
+       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.
+      </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
+       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.
+      </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+       Print the <span class="application">pg_amcheck</span> version and exit.
+      </p></dd><dt><span class="term"><code class="option">--install-missing</code><br /></span><span class="term"><code class="option">--install-missing=<em class="replaceable"><code>schema</code></em></code></span></dt><dd><p>
+       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
+       <em class="replaceable"><code>schema</code></em>, or if not specified
+       into schema <code class="literal">pg_catalog</code>.
+      </p><p>
+       At present, the only required extension is <a class="xref" href="amcheck.html" title="F.2. amcheck">amcheck</a>.
+      </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+       Show help about <span class="application">pg_amcheck</span> command line
+       arguments, and exit.
+      </p></dd></dl></div><p>
+  </p></div><div class="refsect1" id="id-1.9.4.9.7"><h2>Notes</h2><p>
+   <span class="application">pg_amcheck</span> is designed to work with
+   <span class="productname">PostgreSQL</span> 14.0 and later.
+  </p></div><div class="refsect1" id="id-1.9.4.9.8"><h2>See Also</h2><span class="simplelist"><a class="xref" href="amcheck.html" title="F.2. amcheck">amcheck</a></span></div></div><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-ecpg.html" title="ecpg">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgbasebackup.html" title="pg_basebackup">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span xmlns="http://www.w3.org/1999/xhtml" class="application">ecpg</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 14.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span xmlns="http://www.w3.org/1999/xhtml" class="application">pg_basebackup</span></td></tr></table></div></body></html>
+\ No newline at end of file
author	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-05-04 12:15:05 +0000
committer	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-05-04 12:15:05 +0000
commit	46651ce6fe013220ed397add242004d764fc0153 (patch)
tree	6e5299f990f88e60174a1d3ae6e48eedd2688b2b /doc/src/sgml/html/app-pgamcheck.html
parent	Initial commit. (diff)
download	postgresql-14-upstream.tar.xz postgresql-14-upstream.zip