diff options
author | Peter Eisentraut | 2023-09-28 10:08:54 +0000 |
---|---|---|
committer | Peter Eisentraut | 2023-09-28 10:08:54 +0000 |
commit | 5f1b00e64aee58a83558b5036d9877dfcfba4252 (patch) | |
tree | 717c46135af13078a6749fe346c2fed3cbcfc01c | |
parent | a11d8e10f226c5a2072c1640bd1d70403ae4c4fa (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.sgml | 62 | ||||
-rw-r--r-- | src/bin/pg_resetwal/pg_resetwal.c | 3 |
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")); |