[prev in list] [next in list] [prev in thread] [next in thread]
List: pgsql-hackers
Subject: [HACKERS] pg_resetxlog reference page reorganization
From: Peter Eisentraut <peter_e () gmx ! net>
Date: 2016-02-29 23:53:03
Message-ID: 56D4D9DF.8000906 () gmx ! net
[Download RAW message or body]
The pg_resetxlog reference page has grown over the years into an
unnavigable jungle, so here is a patch that reorganizes it to be more in
the style of the other ref pages, with a normal options list.
["0001-doc-Reorganize-pg_resetxlog-reference-page.patch" (application/x-patch)]
From a9024195e9f7a0b47e592f39938bdc9743152a70 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Mon, 29 Feb 2016 18:48:34 -0500
Subject: [PATCH] doc: Reorganize pg_resetxlog reference page
The pg_resetxlog reference page didn't have a proper options list, only
running text listing the options and some explanations of them. This
might have worked when there were only a few options, but the list has
grown over the releases, and now it's hard to find an option and its
associated explanation. So write out the options list as on other
reference pages.
---
doc/src/sgml/ref/pg_resetxlog.sgml | 222 ++++++++++++++++++++++++-------------
1 file changed, 144 insertions(+), 78 deletions(-)
diff --git a/doc/src/sgml/ref/pg_resetxlog.sgml b/doc/src/sgml/ref/pg_resetxlog.sgml
index 1bcc5a7..fd9d0be 100644
--- a/doc/src/sgml/ref/pg_resetxlog.sgml
+++ b/doc/src/sgml/ref/pg_resetxlog.sgml
@@ -22,15 +22,9 @@
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_resetxlog</command>
- <arg choice="opt"><option>-c</option> <replaceable \
class="parameter">xid</replaceable>,<replaceable \
class="parameter">xid</replaceable></arg> <arg \
choice="opt"><option>-f</option></arg> <arg choice="opt"><option>-n</option></arg>
- <arg choice="opt"><option>-o</option> <replaceable \
class="parameter">oid</replaceable></arg>
- <arg choice="opt"><option>-x</option> <replaceable \
class="parameter">xid</replaceable></arg>
- <arg choice="opt"><option>-e</option> <replaceable \
class="parameter">xid_epoch</replaceable></arg>
- <arg choice="opt"><option>-m</option> <replaceable \
class="parameter">mxid</replaceable>,<replaceable \
class="parameter">mxid</replaceable></arg>
- <arg choice="opt"><option>-O</option> <replaceable \
class="parameter">mxoff</replaceable></arg>
- <arg choice="opt"><option>-l</option> <replaceable \
class="parameter">xlogfile</replaceable></arg> + <arg \
rep="repeat"><replaceable>option</replaceable></arg> <arg choice="req"><arg \
choice="opt"><option>-D</option></arg> <replaceable \
class="parameter">datadir</replaceable></arg> </cmdsynopsis>
</refsynopsisdiv>
@@ -76,78 +70,108 @@ <title>Description</title>
execute any data-modifying operations in the database before you dump,
as any such action is likely to make the corruption worse.
</para>
+ </refsect1>
- <para>
- The <option>-o</>, <option>-x</>, <option>-e</>,
- <option>-m</>, <option>-O</>,
- <option>-c</>
- and <option>-l</>
- options allow the next OID, next transaction ID, next transaction ID's
- epoch, next and oldest multitransaction ID, next multitransaction offset,
- oldest and newest transaction IDs for which the commit time can be retrieved,
- and WAL
- starting address values to be set manually. These are only needed when
- <command>pg_resetxlog</command> is unable to determine appropriate values
- by reading <filename>pg_control</>. Safe values can be determined as
- follows:
+ <refsect1>
+ <title>Options</title>
- <itemizedlist>
+ <variablelist>
+ <varlistentry>
+ <term><option>-f</option></term>
<listitem>
<para>
- A safe value for the next transaction ID (<option>-x</>)
- can be determined by looking for the numerically largest
- file name in the directory <filename>pg_clog</> under the data directory,
- adding one,
- and then multiplying by 1048576. Note that the file names are in
- hexadecimal. It is usually easiest to specify the option value in
- hexadecimal too. For example, if <filename>0011</> is the largest entry
- in <filename>pg_clog</>, <literal>-x 0x1200000</> will work (five
- trailing zeroes provide the proper multiplier).
+ Force <command>pg_resetxlog</command> to proceed even if it cannot determine
+ valid data for <filename>pg_control</>, as explained above.
</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n</option></term>
<listitem>
<para>
- A safe value for the next multitransaction ID (first part of <option>-m</>)
- can be determined by looking for the numerically largest
- file name in the directory <filename>pg_multixact/offsets</> under the
- data directory, adding one, and then multiplying by 65536.
- Conversely, a safe value for the oldest multitransaction ID (second part of
- <option>-m</>)
- can be determined by looking for the numerically smallest
- file name in the same directory and multiplying by 65536.
- As above, the file names are in hexadecimal, so the easiest way to do
- this is to specify the option value in hexadecimal and append four zeroes.
+ The <option>-n</> (no operation) option instructs
+ <command>pg_resetxlog</command> to print the values reconstructed from
+ <filename>pg_control</> and values about to be changed, and then exit
+ without modifying anything. This is mainly a debugging tool, but can be
+ useful as a sanity check before allowing <command>pg_resetxlog</command>
+ to proceed for real.
</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V</option></term>
+ <term><option>--version</option></term>
+ <listitem><para>Display version information, then exit.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-?</option></term>
+ <term><option>--help</option></term>
+ <listitem><para>Show help, then exit.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The following options are only needed when
+ <command>pg_resetxlog</command> is unable to determine appropriate values
+ by reading <filename>pg_control</>. Safe values can be determined as
+ described below. For values that take numeric arguments, hexadecimal
+ values can be specified by using the prefix <literal>0x</literal>.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-c</option> <replaceable \
class="parameter">xid</replaceable>,<replaceable \
class="parameter">xid</replaceable></term> <listitem>
<para>
- A safe value for the next multitransaction offset (<option>-O</>)
- can be determined by looking for the numerically largest
- file name in the directory <filename>pg_multixact/members</> under the
- data directory, adding one, and then multiplying by 52352. As above,
- the file names are in hexadecimal. There is no simple recipe such as
- the ones above of appending zeroes.
+ Manually set the oldest and newest transaction IDs for which the commit
+ time can be retrieved.
</para>
- </listitem>
- <listitem>
<para>
A safe value for the oldest transaction ID for which the commit time can
- be retrieved (first part of <option>-c</>) can be determined by looking
+ be retrieved (first part) can be determined by looking
for the numerically smallest file name in the directory
<filename>pg_commit_ts</> under the data directory. Conversely, a safe
value for the newest transaction ID for which the commit time can be
- retrieved (second part of <option>-c</>) can be determined by looking for
- the numerically greatest file name in the same directory. As above, the
- file names are in hexadecimal.
+ retrieved (second part) can be determined by looking for the numerically
+ greatest file name in the same directory. The file names are in
+ hexadecimal.
</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-e</option> <replaceable \
class="parameter">xid_epoch</replaceable></term> <listitem>
<para>
- The WAL starting address (<option>-l</>) should be
+ Manually set the next transaction ID's epoch.
+ </para>
+
+ <para>
+ The transaction ID epoch is not actually stored anywhere in the database
+ except in the field that is set by <command>pg_resetxlog</command>,
+ so any value will work so far as the database itself is concerned.
+ You might need to adjust this value to ensure that replication
+ systems such as <application>Slony-I</> and
+ <application>Skytools</> work correctly —
+ if so, an appropriate value should be obtainable from the state of
+ the downstream replicated database.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-l</option> <replaceable \
class="parameter">xlogfile</replaceable></term> + <listitem>
+ <para>
+ Manually set the WAL starting address.
+ </para>
+
+ <para>
+ The WAL starting address should be
larger than any WAL segment file name currently existing in
the directory <filename>pg_xlog</> under the data directory.
These names are also in hexadecimal and have three parts. The first
@@ -168,46 +192,81 @@ <title>Description</title>
</para>
</note>
</listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-m</option> <replaceable \
class="parameter">mxid</replaceable>,<replaceable \
class="parameter">mxid</replaceable></term> + <listitem>
+ <para>
+ Manually set the next and oldest multitransaction ID.
+ </para>
+
+ <para>
+ A safe value for the next multitransaction ID (first part) can be
+ determined by looking for the numerically largest file name in the
+ directory <filename>pg_multixact/offsets</> under the data directory,
+ adding one, and then multiplying by 65536 (0x10000). Conversely, a safe
+ value for the oldest multitransaction ID (second part of
+ <option>-m</>) can be determined by looking for the numerically smallest
+ file name in the same directory and multiplying by 65536. The file
+ names are in hexadecimal, so the easiest way to do this is to specify
+ the option value in hexadecimal and append four zeroes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o</option> <replaceable \
class="parameter">oid</replaceable></term> <listitem>
<para>
+ Manually set the next OID.
+ </para>
+
+ <para>
There is no comparably easy way to determine a next OID that's beyond
the largest one in the database, but fortunately it is not critical to
get the next-OID setting right.
</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-O</option> <replaceable \
class="parameter">mxoff</replaceable></term> <listitem>
<para>
- The transaction ID epoch is not actually stored anywhere in the database
- except in the field that is set by <command>pg_resetxlog</command>,
- so any value will work so far as the database itself is concerned.
- You might need to adjust this value to ensure that replication
- systems such as <application>Slony-I</> and
- <application>Skytools</> work correctly —
- if so, an appropriate value should be obtainable from the state of
- the downstream replicated database.
+ Manually set the next multitransaction offset.
</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The <option>-n</> (no operation) option instructs
- <command>pg_resetxlog</command> to print the values reconstructed from
- <filename>pg_control</> and values about to be changed, and then exit
- without modifying anything. This is mainly a debugging tool, but can be
- useful as a sanity check before allowing <command>pg_resetxlog</command>
- to proceed for real.
- </para>
+ <para>
+ A safe value can be determined by looking for the numerically largest
+ file name in the directory <filename>pg_multixact/members</> under the
+ data directory, adding one, and then multiplying by 52352 (0xCC80).
+ The file names are in hexadecimal. There is no simple recipe such as
+ the ones for other options of appending zeroes.
+ </para>
+ </listitem>
+ </varlistentry>
- <para>
- The <option>-V</> and <option>--version</> options print
- the <application>pg_resetxlog</application> version and exit. The
- options <option>-?</> and <option>--help</> show supported arguments,
- and exit.
- </para>
+ <varlistentry>
+ <term><option>-x</option> <replaceable \
class="parameter">xid</replaceable></term> + <listitem>
+ <para>
+ Manually set the next transaction ID.
+ </para>
+ <para>
+ A safe value can be determined by looking for the numerically largest
+ file name in the directory <filename>pg_clog</> under the data directory,
+ adding one,
+ and then multiplying by 1048576 (0x100000). Note that the file names are in
+ hexadecimal. It is usually easiest to specify the option value in
+ hexadecimal too. For example, if <filename>0011</> is the largest entry
+ in <filename>pg_clog</>, <literal>-x 0x1200000</> will work (five
+ trailing zeroes provide the proper multiplier).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
<refsect1>
@@ -224,4 +283,11 @@ <title>Notes</title>
</para>
</refsect1>
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="app-pgcontroldata"></member>
+ </simplelist>
+ </refsect1>
</refentry>
--
2.7.2
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic