433 lines
17 KiB
Plaintext
433 lines
17 KiB
Plaintext
<!--
|
|
doc/src/sgml/ref/pg_resetwal.sgml
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="app-pgresetwal">
|
|
<indexterm zone="app-pgresetwal">
|
|
<primary>pg_resetwal</primary>
|
|
</indexterm>
|
|
|
|
<refmeta>
|
|
<refentrytitle><application>pg_resetwal</application></refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>pg_resetwal</refname>
|
|
<refpurpose>reset the write-ahead log and other control information of a <productname>PostgreSQL</productname> database cluster</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>pg_resetwal</command>
|
|
<group choice="opt">
|
|
<arg choice="plain"><option>-f</option></arg>
|
|
<arg choice="plain"><option>--force</option></arg>
|
|
</group>
|
|
<group choice="opt">
|
|
<arg choice="plain"><option>-n</option></arg>
|
|
<arg choice="plain"><option>--dry-run</option></arg>
|
|
</group>
|
|
<arg rep="repeat"><replaceable>option</replaceable></arg>
|
|
<group choice="plain">
|
|
<group choice="opt">
|
|
<arg choice="plain"><option>-D</option></arg>
|
|
<arg choice="plain"><option>--pgdata</option></arg>
|
|
</group>
|
|
<replaceable class="parameter">datadir</replaceable>
|
|
</group>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="r1-app-pgresetwal-1">
|
|
<title>Description</title>
|
|
<para>
|
|
<command>pg_resetwal</command> clears the write-ahead log (WAL) and
|
|
optionally resets some other control information stored in the
|
|
<filename>pg_control</filename> file. This function is sometimes needed
|
|
if these files have become corrupted. It should be used only as a
|
|
last resort, when the server will not start due to such corruption.
|
|
</para>
|
|
|
|
<para>
|
|
Some options, such as <option>--wal-segsize</option> (see below), can also
|
|
be used to modify certain global settings of a database cluster without the
|
|
need to rerun <command>initdb</command>. This can be done safely on an
|
|
otherwise sound database cluster, if none of the dangerous modes mentioned
|
|
below are used.
|
|
</para>
|
|
|
|
<para>
|
|
If <command>pg_resetwal</command> is used on a data directory where the
|
|
server has been cleanly shut down and the control file is sound, then it
|
|
will have no effect on the contents of the database system, except that no
|
|
longer used WAL files are cleared away. Any other use is potentially
|
|
dangerous and must be done with great care. <command>pg_resetwal</command>
|
|
will require the <option>-f</option> (force) option to be specified before
|
|
working on a data directory in an unclean shutdown state or with a
|
|
corrupted control file.
|
|
</para>
|
|
|
|
<para>
|
|
After running this command on a data directory with corrupted WAL or a
|
|
corrupted control file, it should be possible to start the server,
|
|
but bear in mind that the database might contain inconsistent data due to
|
|
partially-committed transactions. You should immediately dump your data,
|
|
run <command>initdb</command>, and restore. After restore, check for
|
|
inconsistencies and repair as needed.
|
|
</para>
|
|
|
|
<para>
|
|
If <command>pg_resetwal</command> complains that it cannot determine
|
|
valid data for <filename>pg_control</filename>, you can force it to proceed anyway
|
|
by specifying the <option>-f</option> (force) option. In this case plausible
|
|
values will be substituted for the missing data. Most of the fields can be
|
|
expected to match, but manual assistance might be needed for the next OID,
|
|
next transaction ID and epoch, next multitransaction ID and offset, and
|
|
WAL starting location fields. These fields can be set using the options
|
|
discussed below. If you are not able to determine correct values for all
|
|
these fields, <option>-f</option> can still be used, but
|
|
the recovered database must be treated with even more suspicion than
|
|
usual: an immediate dump and restore is imperative. <emphasis>Do not</emphasis>
|
|
execute any data-modifying operations in the database before you dump,
|
|
as any such action is likely to make the corruption worse.
|
|
</para>
|
|
|
|
<para>
|
|
This utility can only be run by the user who installed the server, because
|
|
it requires read/write access to the data directory.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">datadir</replaceable></term>
|
|
<term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
|
|
<term><option>--pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the location of the database directory.
|
|
For safety reasons, you must specify the data directory on the command
|
|
line. <command>pg_resetwal</command> does not use the environment
|
|
variable <envar>PGDATA</envar>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-f</option></term>
|
|
<term><option>--force</option></term>
|
|
<listitem>
|
|
<para>
|
|
Force <command>pg_resetwal</command> to proceed even in situations where
|
|
it could be dangerous, as explained above. Specifically, this option is
|
|
required to proceed if the server had not been cleanly shut down or if
|
|
<command>pg_resetwal</command> cannot determine valid data for
|
|
<filename>pg_control</filename>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-n</option></term>
|
|
<term><option>--dry-run</option></term>
|
|
<listitem>
|
|
<para>
|
|
The <option>-n</option>/<option>--dry-run</option> option instructs
|
|
<command>pg_resetwal</command> to print the values reconstructed from
|
|
<filename>pg_control</filename> 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_resetwal</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_resetwal</command> is unable to determine appropriate values
|
|
by reading <filename>pg_control</filename>. 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>. Note
|
|
that these instructions only apply with the standard block size of 8 kB.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-c <replaceable class="parameter">xid</replaceable>,<replaceable class="parameter">xid</replaceable></option></term>
|
|
<term><option>--commit-timestamp-ids=<replaceable class="parameter">xid</replaceable>,<replaceable class="parameter">xid</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Manually set the oldest and newest transaction IDs for which the commit
|
|
time can be retrieved.
|
|
</para>
|
|
|
|
<para>
|
|
A safe value for the oldest transaction ID for which the commit time can
|
|
be retrieved (first part) can be determined by looking
|
|
for the numerically smallest file name in the directory
|
|
<filename>pg_commit_ts</filename> under the data directory. Conversely, a safe
|
|
value for the newest transaction ID for which the commit time can be
|
|
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>
|
|
<!-- XXX: Should there be a multiplier, similar to the other options? -->
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-e <replaceable class="parameter">xid_epoch</replaceable></option></term>
|
|
<term><option>--epoch=<replaceable class="parameter">xid_epoch</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
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_resetwal</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</application> and
|
|
<application>Skytools</application> 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 <replaceable class="parameter">walfile</replaceable></option></term>
|
|
<term><option>--next-wal-file=<replaceable class="parameter">walfile</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Manually set the WAL starting location by specifying the name of the
|
|
next WAL segment file.
|
|
</para>
|
|
|
|
<para>
|
|
The name of next WAL segment file should be
|
|
larger than any WAL segment file name currently existing in
|
|
the directory <filename>pg_wal</filename> under the data directory.
|
|
These names are also in hexadecimal and have three parts. The first
|
|
part is the <quote>timeline ID</quote> and should usually be kept the same.
|
|
For example, if <filename>00000001000000320000004A</filename> is the
|
|
largest entry in <filename>pg_wal</filename>, use <literal>-l 00000001000000320000004B</literal> or higher.
|
|
</para>
|
|
|
|
<para>
|
|
Note that when using nondefault WAL segment sizes, the numbers in the WAL
|
|
file names are different from the LSNs that are reported by system
|
|
functions and system views. This option takes a WAL file name, not an
|
|
LSN.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
<command>pg_resetwal</command> itself looks at the files in
|
|
<filename>pg_wal</filename> and chooses a default <option>-l</option> setting
|
|
beyond the last existing file name. Therefore, manual adjustment of
|
|
<option>-l</option> should only be needed if you are aware of WAL segment
|
|
files that are not currently present in <filename>pg_wal</filename>, such as
|
|
entries in an offline archive; or if the contents of
|
|
<filename>pg_wal</filename> have been lost entirely.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-m <replaceable class="parameter">mxid</replaceable>,<replaceable class="parameter">mxid</replaceable></option></term>
|
|
<term><option>--multixact-ids=<replaceable class="parameter">mxid</replaceable>,<replaceable class="parameter">mxid</replaceable></option></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</filename> 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</option>) 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>
|
|
<!-- 65536 = SLRU_PAGES_PER_SEGMENT * BLCKSZ / sizeof(MultiXactOffset) -->
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-o <replaceable class="parameter">oid</replaceable></option></term>
|
|
<term><option>--next-oid=<replaceable class="parameter">oid</replaceable></option></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 <replaceable class="parameter">mxoff</replaceable></option></term>
|
|
<term><option>--multixact-offset=<replaceable class="parameter">mxoff</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Manually set the next multitransaction offset.
|
|
</para>
|
|
|
|
<para>
|
|
A safe value can be determined by looking for the numerically largest
|
|
file name in the directory <filename>pg_multixact/members</filename> 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>
|
|
<!-- 52352 = SLRU_PAGES_PER_SEGMENT * floor(BLCKSZ/20) * 4; see multixact.c -->
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--wal-segsize=<replaceable class="parameter">wal_segment_size</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Set the new WAL segment size, in megabytes. The value must be set to a
|
|
power of 2 between 1 and 1024 (megabytes). See the same option of <xref
|
|
linkend="app-initdb"/> for more information.
|
|
</para>
|
|
|
|
<para>
|
|
This option can also be used to change the WAL segment size of an
|
|
existing database cluster, avoiding the need to
|
|
re-<command>initdb</command>.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
While <command>pg_resetwal</command> will set the WAL starting address
|
|
beyond the latest existing WAL segment file, some segment size changes
|
|
can cause previous WAL file names to be reused. It is recommended to
|
|
use <option>-l</option> together with this option to manually set the
|
|
WAL starting address if WAL file name overlap will cause problems with
|
|
your archiving strategy.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-u <replaceable class="parameter">xid</replaceable></option></term>
|
|
<term><option>--oldest-transaction-id=<replaceable class="parameter">xid</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Manually set the oldest unfrozen transaction ID.
|
|
</para>
|
|
|
|
<para>
|
|
A safe value can be determined by looking for the numerically smallest
|
|
file name in the directory <filename>pg_xact</filename> under the data directory
|
|
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>0007</filename> is the smallest entry
|
|
in <filename>pg_xact</filename>, <literal>-u 0x700000</literal> will work (five
|
|
trailing zeroes provide the proper multiplier).
|
|
</para>
|
|
<!-- 1048576 = SLRU_PAGES_PER_SEGMENT * BLCKSZ * CLOG_XACTS_PER_BYTE -->
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-x <replaceable class="parameter">xid</replaceable></option></term>
|
|
<term><option>--next-transaction-id=<replaceable class="parameter">xid</replaceable></option></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_xact</filename> 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</filename> is the largest entry
|
|
in <filename>pg_xact</filename>, <literal>-x 0x1200000</literal> will work (five
|
|
trailing zeroes provide the proper multiplier).
|
|
</para>
|
|
<!-- 1048576 = SLRU_PAGES_PER_SEGMENT * BLCKSZ * CLOG_XACTS_PER_BYTE -->
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Environment</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><envar>PG_COLOR</envar></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies whether to use color in diagnostic messages. Possible values
|
|
are <literal>always</literal>, <literal>auto</literal> and
|
|
<literal>never</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
This command must not be used when the server is
|
|
running. <command>pg_resetwal</command> will refuse to start up if
|
|
it finds a server lock file in the data directory. If the
|
|
server crashed then a lock file might have been left
|
|
behind; in that case you can remove the lock file to allow
|
|
<command>pg_resetwal</command> to run. But before you do
|
|
so, make doubly certain that there is no server process still alive.
|
|
</para>
|
|
|
|
<para>
|
|
<command>pg_resetwal</command> works only with servers of the same
|
|
major version.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="app-pgcontroldata"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|