Add a docs section for obsoleted and renamed functions and settings

The new appendix groups information on renamed or removed settings,
commands, etc into an out-of-the-way part of the docs.

The original id elements are retained in each subsection to ensure that
the same filenames are produced for HTML docs. This prevents /current/
links on the web from breaking, and allows users of the web docs
to follow links from old version pages to info on the changes in the
new version. Prior to this change, a link to /current/ for renamed
sections like the recovery.conf docs would just 404. Similarly if
someone searched for recovery.conf they would find the pg11 docs,
but there would be no /12/ or /current/ link, so they couldn't easily
find out that it was removed in pg12 or how to adapt.

Index entries are also added so that there's a breadcrumb trail for
users to follow when they know the old name, but not what we changed it
to. So a user who is trying to find out how to set standby_mode in
PostgreSQL 12+, or where pg_resetxlog went, now has more chance of
finding that information.

Craig Ringer and Stephen Frost
Reviewed-by: Euler Taveira
Discussion: https://postgr.es/m/CAGRY4nzPNOyYQ_1-pWYToUVqQ0ThqP5jdURnJMZPm539fdizOg%40mail.gmail.com
Backpatch-through: 10

diff --git a/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml
new file mode 100644 (file)
index 0000000..f74d0ae
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml
@@ -0,0 +1,24 @@
+
+
+
+
+  <command>pg_receivexlog</command> renamed to <command>pg_receivewal</command>
+
+   
+     pg_receivexlog
+     pg_receivewal
+   
+
+   
+    PostgreSQL 9.6 and below provided a command named
+    pg_receivexlog
+    pg_receivexlog
+    to fetch write-ahead-log (WAL) files.  This command was renamed to pg_receivewal, see
+     for documentation of pg_receivewal and see
+    the release notes for PostgreSQL 10 for details
+    on this change.
+   
+
+

diff --git a/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml
new file mode 100644 (file)
index 0000000..7d99930
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml
@@ -0,0 +1,24 @@
+
+
+
+
+  <command>pg_resetxlog</command> renamed to <command>pg_resetwal</command>
+
+   
+     pg_resetxlog
+     pg_resetwal
+   
+
+   
+    PostgreSQL 9.6 and below provided a command named
+    pg_resetxlog
+    pg_resetxlog
+    to reset the write-ahead-log (WAL) files.  This command was renamed to pg_resetwal, see
+     for documentation of pg_resetwal and see
+    the release notes for PostgreSQL 10 for details
+    on this change.
+   
+
+

diff --git a/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml
new file mode 100644 (file)
index 0000000..4173fee
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml
@@ -0,0 +1,24 @@
+
+
+
+
+  <command>pg_xlogdump</command> renamed to <command>pg_waldump</command>
+
+   
+     pg_xlogdump
+     pg_waldump
+   
+
+   
+    PostgreSQL 9.6 and below provided a command named
+    pg_xlogdump
+    pg_xlogdump
+    to read write-ahead-log (WAL) files.  This command was renamed to pg_waldump, see
+     for documentation of pg_waldump and see
+    the release notes for PostgreSQL 10 for details
+    on this change.
+   
+
+

diff --git a/doc/src/sgml/appendix-obsolete-recovery-config.sgml b/doc/src/sgml/appendix-obsolete-recovery-config.sgml
new file mode 100644 (file)
index 0000000..77c4289
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-recovery-config.sgml
@@ -0,0 +1,58 @@
+
+
+
+
+  <filename>recovery.conf</filename> file merged into <filename>postgresql.conf</filename>
+
+   
+     recovery.conf
+   
+
+   
+    PostgreSQL 11 and below used a configuration file named
+    recovery.conf
+    recovery.conf
+    to manage replicas and standbys. Support for this file was removed in PostgreSQL 12. See
+    the release notes for PostgreSQL 12 for details
+    on this change.
+   
+
+   
+    On PostgreSQL 12 and above,
+    archive recovery, streaming replication, and PITR
+    are configured using
+    normal server configuration parameters.
+    These are set in postgresql.conf or via
+    ALTER SYSTEM
+    like any other parameter.
+   
+
+   
+    The server will not start if a recovery.conf exists.
+   
+
+   
+    The
+    trigger_file
+    
+     trigger_file
+     promote_trigger_file
+    
+    setting has been renamed to
+    .
+   
+
+   
+    The
+    standby_mode
+    
+     standby_mode
+     standby.signal
+    
+    setting has been removed. A standby.signal file in the data directory
+    is used instead. See  for details.
+   
+
+

diff --git a/doc/src/sgml/appendix-obsolete.sgml b/doc/src/sgml/appendix-obsolete.sgml
new file mode 100644 (file)
index 0000000..ffd7d40
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete.sgml
@@ -0,0 +1,41 @@
+
+
+
+ Obsolete or Renamed Features
+
+ 
+   Functionality is sometimes removed from PostgreSQL, feature, setting
+   and file names sometimes change, or documentation moves to different
+   places. This section directs users coming from old versions of the
+   documentation or from external links to the appropriate new location
+   for the information they need.
+ 
+
+ 
+
+ &obsolete-recovery-config;
+ &obsolete-pgxlogdump;
+ &obsolete-pgresetxlog;
+ &obsolete-pgreceivexlog;
+
+

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 701cb65cc7b150df1131b6b2a4805d7252138932..d1e2e8c4c32b58fa35efdd368ff840e66953b607 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -4312,7 +4312,9 @@ ANY num_sync ( 
      Standby Servers
 
      
-      These settings control the behavior of a standby server that is
+      These settings control the behavior of a
+      standby server
+      that is
       to receive replication data.  Their values on the primary server
       are irrelevant.
      

diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index db1d369743e74bfc5916bf3af275cff0c75da101..70ad6a4a4fda6df0e5985d4b193dff41da3c6366 100644 (file)
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -184,3 +184,10 @@
 
 
 
+
+
+
+
+
+
+

diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index f49f5c01081dbf8e0d19bdd82527fdb648984ed8..c072110ba60d0dc45a14a090a27dc09e41e68482 100644 (file)
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -613,9 +613,17 @@ protocol to make nodes agree on a serializable transactional order.
 
   
 
-  
+   xreflabel="Standby Server Operation">
    Standby Server Operation
 
+   
+    A server enters standby mode if a
+    
+    standby.signal
+    standby.signal
+    file exists in the data directory when the server is started.
+   
+
    
     In standby mode, the server continuously applies WAL received from the
     primary server. The standby server can read WAL from a WAL archive
@@ -689,7 +697,8 @@ protocol to make nodes agree on a serializable transactional order.
    
     To set up the standby server, restore the base backup taken from primary
     server (see ). Create a file
-    standby.signal in the standby's cluster data
+    standby.signalstandby.signal
+    in the standby's cluster data
     directory. Set  to a simple command to copy files from
     the WAL archive. If you plan to have multiple standby servers for high
     availability purposes, make sure that recovery_target_timeline is set to
@@ -1936,7 +1945,8 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
 
    
     If hot_standby is on in postgresql.conf
-    (the default value) and there is a standby.signal
+    (the default value) and there is a
+    standby.signalstandby.signalfor hot standby
     file present, the server will run in Hot Standby mode.
     However, it may take some time for Hot Standby connections to be allowed,
     because the server will not accept connections until it has completed

diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 730d5fdc34837d7fee4cf112a39f68c130b4aeb1..d453be390903d72beab8b393ec4685778c1887db 100644 (file)
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -289,6 +289,7 @@ break is not needed in a wider output rendering.
   &acronyms;
   &glossary;
   &color;
+  &obsolete;
 
  
 

diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml
index 8ce103301f26c91094169e3a159ce51bc3f1574c..a3e292d44aea75c571bb20bd7356b827df1f0e28 100644 (file)
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -199,7 +199,10 @@ PostgreSQL documentation
       
 
        
-        Creates a standby.signal file and appends
+        Creates a
+        standby.signal
+        standby.signalpg_basebackup --write-recovery-conf
+        file and appends
         connection settings to the postgresql.auto.conf
         file in the target directory (or within the base archive file when
         using tar format).  This eases setting up a standby server using the