diff options
Diffstat (limited to 'doc/src/sgml/ref/pg_resetwal.sgml')
| -rw-r--r-- | doc/src/sgml/ref/pg_resetwal.sgml | 386 |
1 files changed, 386 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/pg_resetwal.sgml b/doc/src/sgml/ref/pg_resetwal.sgml new file mode 100644 index 0000000..fd539f5 --- /dev/null +++ b/doc/src/sgml/ref/pg_resetwal.sgml @@ -0,0 +1,386 @@ +<!-- +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> + After running this command, 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> + This utility can only be run by the user who installed the server, because + it requires read/write access to the data 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> + + <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> + </refsect1> + + <refsect1> + <title>Options</title> + + <variablelist> + <varlistentry> + <term><option>-f</option></term> + <term><option>--force</option></term> + <listitem> + <para> + Force <command>pg_resetwal</command> to proceed even if it cannot determine + valid data for <filename>pg_control</filename>, as explained above. + </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>. + </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> + </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> + </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> + </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> + + <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> + </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> + </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> |