summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPeter Eisentraut2023-09-28 10:08:54 +0000
committerPeter Eisentraut2023-09-28 10:08:54 +0000
commit5f1b00e64aee58a83558b5036d9877dfcfba4252 (patch)
tree717c46135af13078a6749fe346c2fed3cbcfc01c
parenta11d8e10f226c5a2072c1640bd1d70403ae4c4fa (diff)
doc: Improve documentation about pg_resetwal -f option
Reviewed-by: Aleksander Alekseev <[email protected]> Discussion: https://www.postgresql.org/message-id/flat/[email protected]
-rw-r--r--doc/src/sgml/ref/pg_resetwal.sgml62
-rw-r--r--src/bin/pg_resetwal/pg_resetwal.c3
2 files changed, 53 insertions, 12 deletions
diff --git a/doc/src/sgml/ref/pg_resetwal.sgml b/doc/src/sgml/ref/pg_resetwal.sgml
index fd539f56043..08cd3ce5fc2 100644
--- a/doc/src/sgml/ref/pg_resetwal.sgml
+++ b/doc/src/sgml/ref/pg_resetwal.sgml
@@ -52,7 +52,27 @@ PostgreSQL documentation
</para>
<para>
- After running this command, it should be possible to start the server,
+ 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
@@ -60,14 +80,6 @@ PostgreSQL documentation
</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
@@ -82,6 +94,11 @@ PostgreSQL documentation
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>
@@ -89,12 +106,29 @@ PostgreSQL documentation
<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 if it cannot determine
- valid data for <filename>pg_control</filename>, as explained above.
+ 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>
@@ -284,6 +318,12 @@ PostgreSQL documentation
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
diff --git a/src/bin/pg_resetwal/pg_resetwal.c b/src/bin/pg_resetwal/pg_resetwal.c
index 35876e1c957..47e05bd2c95 100644
--- a/src/bin/pg_resetwal/pg_resetwal.c
+++ b/src/bin/pg_resetwal/pg_resetwal.c
@@ -1135,7 +1135,8 @@ usage(void)
printf(_("\nOptions:\n"));
printf(_(" [-D, --pgdata=]DATADIR data directory\n"));
- printf(_(" -f, --force force update to be done\n"));
+ printf(_(" -f, --force force update to be done even after unclean shutdown or\n"
+ " if pg_control values had to be guessed\n"));
printf(_(" -n, --dry-run no update, just show what would be done\n"));
printf(_(" -V, --version output version information, then exit\n"));
printf(_(" -?, --help show this help, then exit\n"));