doc: Improve documentation about pg_resetwal -f option

Reviewed-by: Aleksander Alekseev 
Discussion: https://www.postgresql.org/message-id/flat/0f3ab4a1-ae80-56e8-3426-6b4a02507687@eisentraut.org

diff --git a/doc/src/sgml/ref/pg_resetwal.sgml b/doc/src/sgml/ref/pg_resetwal.sgml
index fd539f560433d2f017b47c826ace0d58a4d63102..08cd3ce5fc20a8e0a05e0b426588e221ef5a57a1 100644 (file)
--- a/doc/src/sgml/ref/pg_resetwal.sgml
+++ b/doc/src/sgml/ref/pg_resetwal.sgml
@@ -52,21 +52,33 @@ PostgreSQL documentation
   
 
   
-   After running this command, it should be possible to start the server,
+   Some options, such as --wal-segsize (see below), can also
+   be used to modify certain global settings of a database cluster without the
+   need to rerun initdb.  This can be done safely on an
+   otherwise sound database cluster, if none of the dangerous modes mentioned
+   below are used.
+  
+
+  
+   If pg_resetwal 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.  pg_resetwal
+   will require the -f (force) option to be specified before
+   working on a data directory in an unclean shutdown state or with a
+   corrupted control file.
+  
+
+  
+   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 initdb, and restore.  After restore, check for
    inconsistencies and repair as needed.
   
 
-  
-   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.
-   pg_resetwal does not use the environment variable
-   PGDATA.
-  
-
   
    If pg_resetwal complains that it cannot determine
    valid data for pg_control, you can force it to proceed anyway
@@ -82,19 +94,41 @@ PostgreSQL documentation
    execute any data-modifying operations in the database before you dump,
    as any such action is likely to make the corruption worse.
   
+
+  
+   This utility can only be run by the user who installed the server, because
+   it requires read/write access to the data directory.
+  
  
 
  
   Options
 
   
+   
+    datadir
+    -D datadir
+    --pgdata=datadir
+    
+     
+      Specifies the location of the database directory.
+      For safety reasons, you must specify the data directory on the command
+      line.  pg_resetwal does not use the environment
+      variable PGDATA.
+     
+    
+   
+
    
     -f
     --force
     
      
-      Force pg_resetwal to proceed even if it cannot determine
-      valid data for pg_control, as explained above.
+      Force pg_resetwal 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
+      pg_resetwal cannot determine valid data for
+      pg_control.
      
     
    
@@ -284,6 +318,12 @@ PostgreSQL documentation
       linkend="app-initdb"/> for more information.
      
 
+     
+      This option can also be used to change the WAL segment size of an
+      existing database cluster, avoiding the need to
+      re-initdb.
+     
+
      
       
        While pg_resetwal 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 35876e1c957937eacfab7aeba58e767befd837c9..47e05bd2c95ff6e9df46d1ca126e008f1a81f0f1 100644 (file)
--- 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"));