Greetings, * Stephen Frost (sfr...@snowman.net) wrote: > Awesome, attached is just a rebase (not that anything really changed). > Unless someone wants to speak up, I'll commit this soonish (hopefully > tomorrow, but at least sometime later this week).
Alright, as this took a bit more playing with to work cleanly in the back-branches, I'm putting it back out there with full patches for all the back-branches, in case anyone sees anything I missed, but I think I got it all right and the docs build for me and at least going through all the new pages, everything looks good to me. Naturally, only included the appropriate pieces in each of the back branches (v10 got the xlog -> WAL changes, v11 had the same, v12 had those plus the recovery.conf changes, as did v13 and HEAD). Once these all go in, I'll update the default roles patch as discussed elsewhere and backpatch that too. If there's other things we've done that would be good to include here, I'd be happy to work with anyone who's interested in putting in the effort to add more. For now, this seems like a pretty good set though. Unless there's anything further, will commit these soon. Thanks! Stephen
From 87e551a82f1bef202e040b3ddd1acc9ffb31bf8a Mon Sep 17 00:00:00 2001 From: Stephen Frost <sfr...@snowman.net> Date: Mon, 22 Mar 2021 12:45:41 -0400 Subject: [PATCH] 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 Discussion: https://postgr.es/m/CAGRY4nzPNOyYQ_1-pWYToUVqQ0ThqP5jdURnJMZPm539fdizOg%40mail.gmail.com Backpatch-through: 10 --- .../sgml/appendix-obsolete-pgreceivexlog.sgml | 24 ++++++++ .../sgml/appendix-obsolete-pgresetxlog.sgml | 24 ++++++++ .../sgml/appendix-obsolete-pgxlogdump.sgml | 24 ++++++++ .../appendix-obsolete-recovery-config.sgml | 58 +++++++++++++++++++ doc/src/sgml/appendix-obsolete.sgml | 40 +++++++++++++ doc/src/sgml/config.sgml | 4 +- doc/src/sgml/filelist.sgml | 7 +++ doc/src/sgml/high-availability.sgml | 16 ++++- doc/src/sgml/postgres.sgml | 1 + doc/src/sgml/ref/pg_basebackup.sgml | 5 +- 10 files changed, 198 insertions(+), 5 deletions(-) create mode 100644 doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml create mode 100644 doc/src/sgml/appendix-obsolete-pgresetxlog.sgml create mode 100644 doc/src/sgml/appendix-obsolete-pgxlogdump.sgml create mode 100644 doc/src/sgml/appendix-obsolete-recovery-config.sgml create mode 100644 doc/src/sgml/appendix-obsolete.sgml diff --git a/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml new file mode 100644 index 0000000000..30bae2f7a2 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/obsolete-pgxlogdump.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="app-pgreceivexlog" xreflabel="pg_receivexlog"> + <title><command>pg_receivexlog</command> renamed to <command>pg_recievewal</command></title> + + <indexterm> + <primary>pg_receivexlog</primary> + <see>pg_receivewal</see> + </indexterm> + + <para> + PostgreSQL 9.6 and below provided a command named + <command>pg_receivexlog</command> + <indexterm><primary>pg_receivexlog</primary></indexterm> + to fetch write-ahead-log (WAL) files. This command was renamed to <command>pg_receivewal</command>, see + <xref linkend="app-pgreceivewal"/> for documentation of <command>pg_receivewal</command> and see + <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details + on this change. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml new file mode 100644 index 0000000000..7d999301f1 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/obsolete-pgresetxlog.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="app-pgresetxlog" xreflabel="pg_resetxlog"> + <title><command>pg_resetxlog</command> renamed to <command>pg_resetwal</command></title> + + <indexterm> + <primary>pg_resetxlog</primary> + <see>pg_resetwal</see> + </indexterm> + + <para> + PostgreSQL 9.6 and below provided a command named + <command>pg_resetxlog</command> + <indexterm><primary>pg_resetxlog</primary></indexterm> + to reset the write-ahead-log (WAL) files. This command was renamed to <command>pg_resetwal</command>, see + <xref linkend="app-pgresetwal"/> for documentation of <command>pg_resetwal</command> and see + <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details + on this change. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml new file mode 100644 index 0000000000..4173fee041 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/obsolete-pgxlogdump.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="pgxlogdump" xreflabel="pg_xlogdump"> + <title><command>pg_xlogdump</command> renamed to <command>pg_waldump</command></title> + + <indexterm> + <primary>pg_xlogdump</primary> + <see>pg_waldump</see> + </indexterm> + + <para> + PostgreSQL 9.6 and below provided a command named + <command>pg_xlogdump</command> + <indexterm><primary>pg_xlogdump</primary></indexterm> + to read write-ahead-log (WAL) files. This command was renamed to <command>pg_waldump</command>, see + <xref linkend="pgwaldump"/> for documentation of <command>pg_waldump</command> and see + <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details + on this change. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete-recovery-config.sgml b/doc/src/sgml/appendix-obsolete-recovery-config.sgml new file mode 100644 index 0000000000..924205ae78 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-recovery-config.sgml @@ -0,0 +1,58 @@ +<!-- doc/src/sgml/obsolete-recovery-config.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="recovery-config" xreflabel="recovery.conf"> + <title><filename>recovery.conf</filename> file merged into <filename>postgresql.conf</filename></title> + + <indexterm> + <primary><filename>recovery.conf</filename></primary> + </indexterm> + + <para> + PostgreSQL 11 and below used a configuration file named + <filename>recovery.conf</filename> + <indexterm><primary>recovery.conf</primary></indexterm> + to manage replicas and standbys. Support for this file was removed in PostgreSQL 12. See + <link linkend="release-prior">the release notes for PostgreSQL 12</link> for details + on this change. + </para> + + <para> + On PostgreSQL 12 and above, + <link linkend="continuous-archiving">archive recovery, streaming replication, and PITR</link> + are configured using + <link linkend="runtime-config-replication-standby">normal server configuration parameters</link>. + These are set in <filename>postgresql.conf</filename> or via + <link linkend="sql-altersystem">ALTER SYSTEM</link> + like any other parameter. + </para> + + <para> + The server will not start if a <filename>recovery.conf</filename> exists. + </para> + + <para> + The + <literal>trigger_file</literal> + <indexterm> + <primary>trigger_file</primary> + <see>promote_trigger_file</see> + </indexterm> + setting has been renamed to + <xref linkend="guc-promote-trigger-file"/> + </para> + + <para> + The + <literal>standby_mode</literal> + <indexterm> + <primary>standby_mode</primary> + <see>standby.signal</see> + </indexterm> + setting has been removed. A <filename>standby.signal</filename> file in the data directory + is used instead. See <xref linkend="standby-server-operation"/> for details. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete.sgml b/doc/src/sgml/appendix-obsolete.sgml new file mode 100644 index 0000000000..f75573931f --- /dev/null +++ b/doc/src/sgml/appendix-obsolete.sgml @@ -0,0 +1,40 @@ +<!-- doc/src/sgml/obsolete.sgml --> + +<appendix id="appendix-obsolete"> + <title>Obsolete or renamed features, settings and files</title> + + <para> + Functionality is sometimes removed from PostgreSQL or documentation for it + 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. + </para> + + <!-- + This section exists so that people following /current/ links to documentation + don't get a 404 when we move or rename things. And users who find old versions + of the docs in searches or old command names when checking the index can + follow links to the new commands. + + Each subsection here should retain the same <chapter>, <appendix> and/or + <sect1> "id" attribute that was used for the relevant documentation before + it was renamed or moved. Do not prepend "obsolete-" or anything, keep it + exactly the same. These ids are used to determine the filenames for generated + HTML docs so changing them will break links. + + Each entry should also insert index terms redirecting from the old to new + names. The recommended spelling is + + <indexterm><primary>oldname</primary><see>newname</see></indexterm> + + We don't bother with attempting to maintain down-version linking, e.g from + pg_waldump to pg_xlogdump. Users of old versions should use old docs. There + is no need to add index terms pointing from the new to old names. + --> + + &obsolete-recovery-config; + &obsolete-pgxlogdump; + &obsolete-pgresetxlog; + &obsolete-pgreceivexlog; + +</appendix> diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index ddc6d789d8..b24b8f9b7e 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -4312,7 +4312,9 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" <title>Standby Servers</title> <para> - These settings control the behavior of a standby server that is + These settings control the behavior of a + <link linkend="standby-server-operation">standby server</link> + that is to receive replication data. Their values on the primary server are irrelevant. </para> diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index db1d369743..70ad6a4a4f 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -184,3 +184,10 @@ <!-- back matter --> <!ENTITY biblio SYSTEM "biblio.sgml"> + +<!-- Stubs for removed entries to preserve public links --> +<!ENTITY obsolete SYSTEM "appendix-obsolete.sgml"> +<!ENTITY obsolete-recovery-config SYSTEM "appendix-obsolete-recovery-config.sgml"> +<!ENTITY obsolete-pgxlogdump SYSTEM "appendix-obsolete-pgxlogdump.sgml"> +<!ENTITY obsolete-pgresetxlog SYSTEM "appendix-obsolete-pgresetxlog.sgml"> +<!ENTITY obsolete-pgreceivexlog SYSTEM "appendix-obsolete-pgreceivexlog.sgml"> diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index f49f5c0108..c072110ba6 100644 --- 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. </sect2> - <sect2 id="standby-server-operation"> + <sect2 id="standby-server-operation" xreflabel="Standby Server Operation"> <title>Standby Server Operation</title> + <para> + A server enters standby mode if a + <anchor id="file-standby-signal" xreflabel="standby.signal"/> + <filename>standby.signal</filename> + <indexterm><primary><filename>standby.signal</filename></primary></indexterm> + file exists in the data directory when the server is started. + </para> + <para> 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. <para> To set up the standby server, restore the base backup taken from primary server (see <xref linkend="backup-pitr-recovery"/>). Create a file - <filename>standby.signal</filename> in the standby's cluster data + <link linkend="file-standby-signal"><filename>standby.signal</filename></link><indexterm><primary>standby.signal</primary></indexterm> + in the standby's cluster data directory. Set <xref linkend="guc-restore-command"/> 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 <varname>recovery_target_timeline</varname> is set to @@ -1936,7 +1945,8 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)' <para> If <varname>hot_standby</varname> is <literal>on</literal> in <filename>postgresql.conf</filename> - (the default value) and there is a <filename>standby.signal</filename> + (the default value) and there is a + <link linkend="file-standby-signal"><filename>standby.signal</filename></link><indexterm><primary>standby.signal</primary><secondary>for hot standby</secondary></indexterm> 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 730d5fdc34..d453be3909 100644 --- 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; </part> diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml index 8ce103301f..a3e292d44a 100644 --- a/doc/src/sgml/ref/pg_basebackup.sgml +++ b/doc/src/sgml/ref/pg_basebackup.sgml @@ -199,7 +199,10 @@ PostgreSQL documentation <listitem> <para> - Creates a <filename>standby.signal</filename> file and appends + Creates a + <link linkend="file-standby-signal"><filename>standby.signal</filename></link> + <indexterm><primary><filename>standby.signal</filename></primary><secondary>pg_basebackup --write-recovery-conf</secondary></indexterm> + file and appends connection settings to the <filename>postgresql.auto.conf</filename> file in the target directory (or within the base archive file when using tar format). This eases setting up a standby server using the -- 2.27.0
From 08021ddc7366091b443d6d07226ca718f87471a8 Mon Sep 17 00:00:00 2001 From: Stephen Frost <sfr...@snowman.net> Date: Sun, 28 Mar 2021 11:46:33 -0400 Subject: [PATCH] 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 Discussion: https://postgr.es/m/CAGRY4nzPNOyYQ_1-pWYToUVqQ0ThqP5jdURnJMZPm539fdizOg%40mail.gmail.com Backpatch-through: 10 --- .../sgml/appendix-obsolete-pgreceivexlog.sgml | 24 ++++++++++++ .../sgml/appendix-obsolete-pgresetxlog.sgml | 24 ++++++++++++ .../sgml/appendix-obsolete-pgxlogdump.sgml | 24 ++++++++++++ doc/src/sgml/appendix-obsolete.sgml | 39 +++++++++++++++++++ doc/src/sgml/filelist.sgml | 6 +++ doc/src/sgml/postgres.sgml | 1 + 6 files changed, 118 insertions(+) create mode 100644 doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml create mode 100644 doc/src/sgml/appendix-obsolete-pgresetxlog.sgml create mode 100644 doc/src/sgml/appendix-obsolete-pgxlogdump.sgml create mode 100644 doc/src/sgml/appendix-obsolete.sgml diff --git a/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml new file mode 100644 index 0000000000..6f34f12a37 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/obsolete-pgxlogdump.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="app-pgreceivexlog" xreflabel="pg_receivexlog"> + <title><command>pg_receivexlog</command> renamed to <command>pg_recievewal</command></title> + + <indexterm> + <primary>pg_receivexlog</primary> + <see>pg_receivewal</see> + </indexterm> + + <para> + PostgreSQL 9.6 and below provided a command named + <command>pg_receivexlog</command> + <indexterm><primary>pg_receivexlog</primary></indexterm> + to fetch write-ahead-log (WAL) files. This command was renamed to <command>pg_receivewal</command>, see + <xref linkend="app-pgreceivewal"> for documentation of <command>pg_receivewal</command> and see + <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details + on this change. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml new file mode 100644 index 0000000000..a17cbce563 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/obsolete-pgresetxlog.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="app-pgresetxlog" xreflabel="pg_resetxlog"> + <title><command>pg_resetxlog</command> renamed to <command>pg_resetwal</command></title> + + <indexterm> + <primary>pg_resetxlog</primary> + <see>pg_resetwal</see> + </indexterm> + + <para> + PostgreSQL 9.6 and below provided a command named + <command>pg_resetxlog</command> + <indexterm><primary>pg_resetxlog</primary></indexterm> + to reset the write-ahead-log (WAL) files. This command was renamed to <command>pg_resetwal</command>, see + <xref linkend="app-pgresetwal"> for documentation of <command>pg_resetwal</command> and see + <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details + on this change. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml new file mode 100644 index 0000000000..28e004edea --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/obsolete-pgxlogdump.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="pgxlogdump" xreflabel="pg_xlogdump"> + <title><command>pg_xlogdump</command> renamed to <command>pg_waldump</command></title> + + <indexterm> + <primary>pg_xlogdump</primary> + <see>pg_waldump</see> + </indexterm> + + <para> + PostgreSQL 9.6 and below provided a command named + <command>pg_xlogdump</command> + <indexterm><primary>pg_xlogdump</primary></indexterm> + to read write-ahead-log (WAL) files. This command was renamed to <command>pg_waldump</command>, see + <xref linkend="pgwaldump"> for documentation of <command>pg_waldump</command> and see + <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details + on this change. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete.sgml b/doc/src/sgml/appendix-obsolete.sgml new file mode 100644 index 0000000000..f93f146aea --- /dev/null +++ b/doc/src/sgml/appendix-obsolete.sgml @@ -0,0 +1,39 @@ +<!-- doc/src/sgml/obsolete.sgml --> + +<appendix id="appendix-obsolete"> + <title>Obsolete or renamed features, settings and files</title> + + <para> + Functionality is sometimes removed from PostgreSQL or documentation for it + 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. + </para> + + <!-- + This section exists so that people following /current/ links to documentation + don't get a 404 when we move or rename things. And users who find old versions + of the docs in searches or old command names when checking the index can + follow links to the new commands. + + Each subsection here should retain the same <chapter>, <appendix> and/or + <sect1> "id" attribute that was used for the relevant documentation before + it was renamed or moved. Do not prepend "obsolete-" or anything, keep it + exactly the same. These ids are used to determine the filenames for generated + HTML docs so changing them will break links. + + Each entry should also insert index terms redirecting from the old to new + names. The recommended spelling is + + <indexterm><primary>oldname</primary><see>newname</see></indexterm> + + We don't bother with attempting to maintain down-version linking, e.g from + pg_waldump to pg_xlogdump. Users of old versions should use old docs. There + is no need to add index terms pointing from the new to old names. + --> + + &obsolete-pgxlogdump; + &obsolete-pgresetxlog; + &obsolete-pgreceivexlog; + +</appendix> diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 8afe1a6b40..2f9d192c41 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -178,6 +178,12 @@ <!-- back matter --> <!ENTITY biblio SYSTEM "biblio.sgml"> +<!-- Stubs for removed entries to preserve public links --> +<!ENTITY obsolete SYSTEM "appendix-obsolete.sgml"> +<!ENTITY obsolete-pgxlogdump SYSTEM "appendix-obsolete-pgxlogdump.sgml"> +<!ENTITY obsolete-pgresetxlog SYSTEM "appendix-obsolete-pgresetxlog.sgml"> +<!ENTITY obsolete-pgreceivexlog SYSTEM "appendix-obsolete-pgreceivexlog.sgml"> + <!-- Some parts of the documentation are also source for some plain-text files used during installation. To selectively ignore or include diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 8a3bfc9b0d..0eba39d17a 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -273,6 +273,7 @@ &sourcerepo; &docguide; &acronyms; + &obsolete; </part> -- 2.27.0
From 1b71bf79d6bc8a0ddac9097636fafd94708fa765 Mon Sep 17 00:00:00 2001 From: Stephen Frost <sfr...@snowman.net> Date: Sun, 28 Mar 2021 11:38:11 -0400 Subject: [PATCH] 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 Discussion: https://postgr.es/m/CAGRY4nzPNOyYQ_1-pWYToUVqQ0ThqP5jdURnJMZPm539fdizOg%40mail.gmail.com Backpatch-through: 10 --- .../sgml/appendix-obsolete-pgreceivexlog.sgml | 24 ++++++++++++ .../sgml/appendix-obsolete-pgresetxlog.sgml | 24 ++++++++++++ .../sgml/appendix-obsolete-pgxlogdump.sgml | 24 ++++++++++++ doc/src/sgml/appendix-obsolete.sgml | 39 +++++++++++++++++++ doc/src/sgml/filelist.sgml | 6 +++ doc/src/sgml/postgres.sgml | 1 + 6 files changed, 118 insertions(+) create mode 100644 doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml create mode 100644 doc/src/sgml/appendix-obsolete-pgresetxlog.sgml create mode 100644 doc/src/sgml/appendix-obsolete-pgxlogdump.sgml create mode 100644 doc/src/sgml/appendix-obsolete.sgml diff --git a/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml new file mode 100644 index 0000000000..30bae2f7a2 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/obsolete-pgxlogdump.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="app-pgreceivexlog" xreflabel="pg_receivexlog"> + <title><command>pg_receivexlog</command> renamed to <command>pg_recievewal</command></title> + + <indexterm> + <primary>pg_receivexlog</primary> + <see>pg_receivewal</see> + </indexterm> + + <para> + PostgreSQL 9.6 and below provided a command named + <command>pg_receivexlog</command> + <indexterm><primary>pg_receivexlog</primary></indexterm> + to fetch write-ahead-log (WAL) files. This command was renamed to <command>pg_receivewal</command>, see + <xref linkend="app-pgreceivewal"/> for documentation of <command>pg_receivewal</command> and see + <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details + on this change. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml new file mode 100644 index 0000000000..7d999301f1 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/obsolete-pgresetxlog.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="app-pgresetxlog" xreflabel="pg_resetxlog"> + <title><command>pg_resetxlog</command> renamed to <command>pg_resetwal</command></title> + + <indexterm> + <primary>pg_resetxlog</primary> + <see>pg_resetwal</see> + </indexterm> + + <para> + PostgreSQL 9.6 and below provided a command named + <command>pg_resetxlog</command> + <indexterm><primary>pg_resetxlog</primary></indexterm> + to reset the write-ahead-log (WAL) files. This command was renamed to <command>pg_resetwal</command>, see + <xref linkend="app-pgresetwal"/> for documentation of <command>pg_resetwal</command> and see + <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details + on this change. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml new file mode 100644 index 0000000000..4173fee041 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/obsolete-pgxlogdump.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="pgxlogdump" xreflabel="pg_xlogdump"> + <title><command>pg_xlogdump</command> renamed to <command>pg_waldump</command></title> + + <indexterm> + <primary>pg_xlogdump</primary> + <see>pg_waldump</see> + </indexterm> + + <para> + PostgreSQL 9.6 and below provided a command named + <command>pg_xlogdump</command> + <indexterm><primary>pg_xlogdump</primary></indexterm> + to read write-ahead-log (WAL) files. This command was renamed to <command>pg_waldump</command>, see + <xref linkend="pgwaldump"/> for documentation of <command>pg_waldump</command> and see + <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details + on this change. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete.sgml b/doc/src/sgml/appendix-obsolete.sgml new file mode 100644 index 0000000000..f93f146aea --- /dev/null +++ b/doc/src/sgml/appendix-obsolete.sgml @@ -0,0 +1,39 @@ +<!-- doc/src/sgml/obsolete.sgml --> + +<appendix id="appendix-obsolete"> + <title>Obsolete or renamed features, settings and files</title> + + <para> + Functionality is sometimes removed from PostgreSQL or documentation for it + 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. + </para> + + <!-- + This section exists so that people following /current/ links to documentation + don't get a 404 when we move or rename things. And users who find old versions + of the docs in searches or old command names when checking the index can + follow links to the new commands. + + Each subsection here should retain the same <chapter>, <appendix> and/or + <sect1> "id" attribute that was used for the relevant documentation before + it was renamed or moved. Do not prepend "obsolete-" or anything, keep it + exactly the same. These ids are used to determine the filenames for generated + HTML docs so changing them will break links. + + Each entry should also insert index terms redirecting from the old to new + names. The recommended spelling is + + <indexterm><primary>oldname</primary><see>newname</see></indexterm> + + We don't bother with attempting to maintain down-version linking, e.g from + pg_waldump to pg_xlogdump. Users of old versions should use old docs. There + is no need to add index terms pointing from the new to old names. + --> + + &obsolete-pgxlogdump; + &obsolete-pgresetxlog; + &obsolete-pgreceivexlog; + +</appendix> diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index c34e64bdc4..c906715a31 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -177,3 +177,9 @@ <!-- back matter --> <!ENTITY biblio SYSTEM "biblio.sgml"> + +<!-- Stubs for removed entries to preserve public links --> +<!ENTITY obsolete SYSTEM "appendix-obsolete.sgml"> +<!ENTITY obsolete-pgxlogdump SYSTEM "appendix-obsolete-pgxlogdump.sgml"> +<!ENTITY obsolete-pgresetxlog SYSTEM "appendix-obsolete-pgresetxlog.sgml"> +<!ENTITY obsolete-pgreceivexlog SYSTEM "appendix-obsolete-pgreceivexlog.sgml"> diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 0070603fc3..6968d90f9b 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -277,6 +277,7 @@ &sourcerepo; &docguide; &acronyms; + &obsolete; </part> -- 2.27.0
From 74a438d99fd10ada87f259d68251f648e98cb03e Mon Sep 17 00:00:00 2001 From: Stephen Frost <sfr...@snowman.net> Date: Fri, 26 Mar 2021 18:12:13 -0400 Subject: [PATCH] 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 Discussion: https://postgr.es/m/CAGRY4nzPNOyYQ_1-pWYToUVqQ0ThqP5jdURnJMZPm539fdizOg%40mail.gmail.com Backpatch-through: 10 --- .../sgml/appendix-obsolete-pgreceivexlog.sgml | 24 ++++++++ .../sgml/appendix-obsolete-pgresetxlog.sgml | 24 ++++++++ .../sgml/appendix-obsolete-pgxlogdump.sgml | 24 ++++++++ .../appendix-obsolete-recovery-config.sgml | 58 +++++++++++++++++++ doc/src/sgml/appendix-obsolete.sgml | 40 +++++++++++++ doc/src/sgml/config.sgml | 5 +- doc/src/sgml/filelist.sgml | 7 +++ doc/src/sgml/high-availability.sgml | 16 ++++- doc/src/sgml/postgres.sgml | 1 + doc/src/sgml/ref/pg_basebackup.sgml | 4 +- 10 files changed, 197 insertions(+), 6 deletions(-) create mode 100644 doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml create mode 100644 doc/src/sgml/appendix-obsolete-pgresetxlog.sgml create mode 100644 doc/src/sgml/appendix-obsolete-pgxlogdump.sgml create mode 100644 doc/src/sgml/appendix-obsolete-recovery-config.sgml create mode 100644 doc/src/sgml/appendix-obsolete.sgml diff --git a/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml new file mode 100644 index 0000000000..30bae2f7a2 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/obsolete-pgxlogdump.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="app-pgreceivexlog" xreflabel="pg_receivexlog"> + <title><command>pg_receivexlog</command> renamed to <command>pg_recievewal</command></title> + + <indexterm> + <primary>pg_receivexlog</primary> + <see>pg_receivewal</see> + </indexterm> + + <para> + PostgreSQL 9.6 and below provided a command named + <command>pg_receivexlog</command> + <indexterm><primary>pg_receivexlog</primary></indexterm> + to fetch write-ahead-log (WAL) files. This command was renamed to <command>pg_receivewal</command>, see + <xref linkend="app-pgreceivewal"/> for documentation of <command>pg_receivewal</command> and see + <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details + on this change. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml new file mode 100644 index 0000000000..7d999301f1 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/obsolete-pgresetxlog.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="app-pgresetxlog" xreflabel="pg_resetxlog"> + <title><command>pg_resetxlog</command> renamed to <command>pg_resetwal</command></title> + + <indexterm> + <primary>pg_resetxlog</primary> + <see>pg_resetwal</see> + </indexterm> + + <para> + PostgreSQL 9.6 and below provided a command named + <command>pg_resetxlog</command> + <indexterm><primary>pg_resetxlog</primary></indexterm> + to reset the write-ahead-log (WAL) files. This command was renamed to <command>pg_resetwal</command>, see + <xref linkend="app-pgresetwal"/> for documentation of <command>pg_resetwal</command> and see + <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details + on this change. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml new file mode 100644 index 0000000000..4173fee041 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/obsolete-pgxlogdump.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="pgxlogdump" xreflabel="pg_xlogdump"> + <title><command>pg_xlogdump</command> renamed to <command>pg_waldump</command></title> + + <indexterm> + <primary>pg_xlogdump</primary> + <see>pg_waldump</see> + </indexterm> + + <para> + PostgreSQL 9.6 and below provided a command named + <command>pg_xlogdump</command> + <indexterm><primary>pg_xlogdump</primary></indexterm> + to read write-ahead-log (WAL) files. This command was renamed to <command>pg_waldump</command>, see + <xref linkend="pgwaldump"/> for documentation of <command>pg_waldump</command> and see + <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details + on this change. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete-recovery-config.sgml b/doc/src/sgml/appendix-obsolete-recovery-config.sgml new file mode 100644 index 0000000000..924205ae78 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-recovery-config.sgml @@ -0,0 +1,58 @@ +<!-- doc/src/sgml/obsolete-recovery-config.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="recovery-config" xreflabel="recovery.conf"> + <title><filename>recovery.conf</filename> file merged into <filename>postgresql.conf</filename></title> + + <indexterm> + <primary><filename>recovery.conf</filename></primary> + </indexterm> + + <para> + PostgreSQL 11 and below used a configuration file named + <filename>recovery.conf</filename> + <indexterm><primary>recovery.conf</primary></indexterm> + to manage replicas and standbys. Support for this file was removed in PostgreSQL 12. See + <link linkend="release-prior">the release notes for PostgreSQL 12</link> for details + on this change. + </para> + + <para> + On PostgreSQL 12 and above, + <link linkend="continuous-archiving">archive recovery, streaming replication, and PITR</link> + are configured using + <link linkend="runtime-config-replication-standby">normal server configuration parameters</link>. + These are set in <filename>postgresql.conf</filename> or via + <link linkend="sql-altersystem">ALTER SYSTEM</link> + like any other parameter. + </para> + + <para> + The server will not start if a <filename>recovery.conf</filename> exists. + </para> + + <para> + The + <literal>trigger_file</literal> + <indexterm> + <primary>trigger_file</primary> + <see>promote_trigger_file</see> + </indexterm> + setting has been renamed to + <xref linkend="guc-promote-trigger-file"/> + </para> + + <para> + The + <literal>standby_mode</literal> + <indexterm> + <primary>standby_mode</primary> + <see>standby.signal</see> + </indexterm> + setting has been removed. A <filename>standby.signal</filename> file in the data directory + is used instead. See <xref linkend="standby-server-operation"/> for details. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete.sgml b/doc/src/sgml/appendix-obsolete.sgml new file mode 100644 index 0000000000..f75573931f --- /dev/null +++ b/doc/src/sgml/appendix-obsolete.sgml @@ -0,0 +1,40 @@ +<!-- doc/src/sgml/obsolete.sgml --> + +<appendix id="appendix-obsolete"> + <title>Obsolete or renamed features, settings and files</title> + + <para> + Functionality is sometimes removed from PostgreSQL or documentation for it + 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. + </para> + + <!-- + This section exists so that people following /current/ links to documentation + don't get a 404 when we move or rename things. And users who find old versions + of the docs in searches or old command names when checking the index can + follow links to the new commands. + + Each subsection here should retain the same <chapter>, <appendix> and/or + <sect1> "id" attribute that was used for the relevant documentation before + it was renamed or moved. Do not prepend "obsolete-" or anything, keep it + exactly the same. These ids are used to determine the filenames for generated + HTML docs so changing them will break links. + + Each entry should also insert index terms redirecting from the old to new + names. The recommended spelling is + + <indexterm><primary>oldname</primary><see>newname</see></indexterm> + + We don't bother with attempting to maintain down-version linking, e.g from + pg_waldump to pg_xlogdump. Users of old versions should use old docs. There + is no need to add index terms pointing from the new to old names. + --> + + &obsolete-recovery-config; + &obsolete-pgxlogdump; + &obsolete-pgresetxlog; + &obsolete-pgreceivexlog; + +</appendix> diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index da323621b5..3cb7d04ef7 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -4062,8 +4062,9 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" <title>Standby Servers</title> <para> - These settings control the behavior of a standby server that is - to receive replication data. Their values on the master server + These settings control the behavior of a + <link linkend="standby-server-operation">standby server</link> + that is to receive replication data. Their values on the master server are irrelevant. </para> diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 8960f11278..332cb4a7d1 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -179,3 +179,10 @@ <!-- back matter --> <!ENTITY biblio SYSTEM "biblio.sgml"> + +<!-- Stubs for removed entries to preserve public links --> +<!ENTITY obsolete SYSTEM "appendix-obsolete.sgml"> +<!ENTITY obsolete-recovery-config SYSTEM "appendix-obsolete-recovery-config.sgml"> +<!ENTITY obsolete-pgxlogdump SYSTEM "appendix-obsolete-pgxlogdump.sgml"> +<!ENTITY obsolete-pgresetxlog SYSTEM "appendix-obsolete-pgresetxlog.sgml"> +<!ENTITY obsolete-pgreceivexlog SYSTEM "appendix-obsolete-pgreceivexlog.sgml"> diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index 07d3982c30..22ac33bda3 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -611,9 +611,17 @@ protocol to make nodes agree on a serializable transactional order. </sect2> - <sect2 id="standby-server-operation"> + <sect2 id="standby-server-operation" xreflabel="Standby Server Operation"> <title>Standby Server Operation</title> + <para> + A server enters standby mode if a + <anchor id="file-standby-signal" xreflabel="standby.signal"/> + <filename>standby.signal</filename> + <indexterm><primary><filename>standby.signal</filename></primary></indexterm> + file exists in the data directory when the server is started. + </para> + <para> In standby mode, the server continuously applies WAL received from the master server. The standby server can read WAL from a WAL archive @@ -686,7 +694,8 @@ protocol to make nodes agree on a serializable transactional order. <para> To set up the standby server, restore the base backup taken from primary server (see <xref linkend="backup-pitr-recovery"/>). Create a file - <filename>standby.signal</filename> in the standby's cluster data + <link linkend="file-standby-signal"><filename>standby.signal</filename></link><indexterm><primary>standby.signal</primary></indexterm> + in the standby's cluster data directory. Set <xref linkend="guc-restore-command"/> 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 <varname>recovery_target_timeline</varname> is set to @@ -2103,7 +2112,8 @@ if (!triggered) <para> If <varname>hot_standby</varname> is <literal>on</literal> in <filename>postgresql.conf</filename> - (the default value) and there is a <filename>standby.signal</filename> + (the default value) and there is a + <link linkend="file-standby-signal"><filename>standby.signal</filename></link><indexterm><primary>standby.signal</primary><secondary>for hot standby</secondary></indexterm> 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 3e115f1c76..25d8f2204b 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -278,6 +278,7 @@ &docguide; &limits; &acronyms; + &obsolete; </part> diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml index 01dac10257..fde143c763 100644 --- a/doc/src/sgml/ref/pg_basebackup.sgml +++ b/doc/src/sgml/ref/pg_basebackup.sgml @@ -215,7 +215,9 @@ PostgreSQL documentation <listitem> <para> - Create <filename>standby.signal</filename> and append connection settings + Create <link linkend="file-standby-signal"><filename>standby.signal</filename></link> + <indexterm><primary><filename>standby.signal</filename></primary><secondary>pg_basebackup --write-recovery-conf</secondary></indexterm> + file and append connection settings to <filename>postgresql.auto.conf</filename> in the output directory (or into the base archive file when using tar format) to ease setting up a standby server. -- 2.27.0
From d155726ac4cea4427bd6b5c67452d4dfdf38dc51 Mon Sep 17 00:00:00 2001 From: Stephen Frost <sfr...@snowman.net> Date: Fri, 26 Mar 2021 17:51:04 -0400 Subject: [PATCH] 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 Discussion: https://postgr.es/m/CAGRY4nzPNOyYQ_1-pWYToUVqQ0ThqP5jdURnJMZPm539fdizOg%40mail.gmail.com Backpatch-through: 10 --- .../sgml/appendix-obsolete-pgreceivexlog.sgml | 24 ++++++++ .../sgml/appendix-obsolete-pgresetxlog.sgml | 24 ++++++++ .../sgml/appendix-obsolete-pgxlogdump.sgml | 24 ++++++++ .../appendix-obsolete-recovery-config.sgml | 58 +++++++++++++++++++ doc/src/sgml/appendix-obsolete.sgml | 40 +++++++++++++ doc/src/sgml/config.sgml | 5 +- doc/src/sgml/filelist.sgml | 7 +++ doc/src/sgml/high-availability.sgml | 16 ++++- doc/src/sgml/postgres.sgml | 1 + doc/src/sgml/ref/pg_basebackup.sgml | 5 +- 10 files changed, 198 insertions(+), 6 deletions(-) create mode 100644 doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml create mode 100644 doc/src/sgml/appendix-obsolete-pgresetxlog.sgml create mode 100644 doc/src/sgml/appendix-obsolete-pgxlogdump.sgml create mode 100644 doc/src/sgml/appendix-obsolete-recovery-config.sgml create mode 100644 doc/src/sgml/appendix-obsolete.sgml diff --git a/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml new file mode 100644 index 0000000000..30bae2f7a2 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/obsolete-pgxlogdump.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="app-pgreceivexlog" xreflabel="pg_receivexlog"> + <title><command>pg_receivexlog</command> renamed to <command>pg_recievewal</command></title> + + <indexterm> + <primary>pg_receivexlog</primary> + <see>pg_receivewal</see> + </indexterm> + + <para> + PostgreSQL 9.6 and below provided a command named + <command>pg_receivexlog</command> + <indexterm><primary>pg_receivexlog</primary></indexterm> + to fetch write-ahead-log (WAL) files. This command was renamed to <command>pg_receivewal</command>, see + <xref linkend="app-pgreceivewal"/> for documentation of <command>pg_receivewal</command> and see + <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details + on this change. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml new file mode 100644 index 0000000000..7d999301f1 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/obsolete-pgresetxlog.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="app-pgresetxlog" xreflabel="pg_resetxlog"> + <title><command>pg_resetxlog</command> renamed to <command>pg_resetwal</command></title> + + <indexterm> + <primary>pg_resetxlog</primary> + <see>pg_resetwal</see> + </indexterm> + + <para> + PostgreSQL 9.6 and below provided a command named + <command>pg_resetxlog</command> + <indexterm><primary>pg_resetxlog</primary></indexterm> + to reset the write-ahead-log (WAL) files. This command was renamed to <command>pg_resetwal</command>, see + <xref linkend="app-pgresetwal"/> for documentation of <command>pg_resetwal</command> and see + <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details + on this change. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml new file mode 100644 index 0000000000..4173fee041 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml @@ -0,0 +1,24 @@ +<!-- doc/src/sgml/obsolete-pgxlogdump.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="pgxlogdump" xreflabel="pg_xlogdump"> + <title><command>pg_xlogdump</command> renamed to <command>pg_waldump</command></title> + + <indexterm> + <primary>pg_xlogdump</primary> + <see>pg_waldump</see> + </indexterm> + + <para> + PostgreSQL 9.6 and below provided a command named + <command>pg_xlogdump</command> + <indexterm><primary>pg_xlogdump</primary></indexterm> + to read write-ahead-log (WAL) files. This command was renamed to <command>pg_waldump</command>, see + <xref linkend="pgwaldump"/> for documentation of <command>pg_waldump</command> and see + <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details + on this change. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete-recovery-config.sgml b/doc/src/sgml/appendix-obsolete-recovery-config.sgml new file mode 100644 index 0000000000..924205ae78 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-recovery-config.sgml @@ -0,0 +1,58 @@ +<!-- doc/src/sgml/obsolete-recovery-config.sgml --> +<!-- + See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute. +--> + +<sect1 id="recovery-config" xreflabel="recovery.conf"> + <title><filename>recovery.conf</filename> file merged into <filename>postgresql.conf</filename></title> + + <indexterm> + <primary><filename>recovery.conf</filename></primary> + </indexterm> + + <para> + PostgreSQL 11 and below used a configuration file named + <filename>recovery.conf</filename> + <indexterm><primary>recovery.conf</primary></indexterm> + to manage replicas and standbys. Support for this file was removed in PostgreSQL 12. See + <link linkend="release-prior">the release notes for PostgreSQL 12</link> for details + on this change. + </para> + + <para> + On PostgreSQL 12 and above, + <link linkend="continuous-archiving">archive recovery, streaming replication, and PITR</link> + are configured using + <link linkend="runtime-config-replication-standby">normal server configuration parameters</link>. + These are set in <filename>postgresql.conf</filename> or via + <link linkend="sql-altersystem">ALTER SYSTEM</link> + like any other parameter. + </para> + + <para> + The server will not start if a <filename>recovery.conf</filename> exists. + </para> + + <para> + The + <literal>trigger_file</literal> + <indexterm> + <primary>trigger_file</primary> + <see>promote_trigger_file</see> + </indexterm> + setting has been renamed to + <xref linkend="guc-promote-trigger-file"/> + </para> + + <para> + The + <literal>standby_mode</literal> + <indexterm> + <primary>standby_mode</primary> + <see>standby.signal</see> + </indexterm> + setting has been removed. A <filename>standby.signal</filename> file in the data directory + is used instead. See <xref linkend="standby-server-operation"/> for details. + </para> + +</sect1> diff --git a/doc/src/sgml/appendix-obsolete.sgml b/doc/src/sgml/appendix-obsolete.sgml new file mode 100644 index 0000000000..f75573931f --- /dev/null +++ b/doc/src/sgml/appendix-obsolete.sgml @@ -0,0 +1,40 @@ +<!-- doc/src/sgml/obsolete.sgml --> + +<appendix id="appendix-obsolete"> + <title>Obsolete or renamed features, settings and files</title> + + <para> + Functionality is sometimes removed from PostgreSQL or documentation for it + 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. + </para> + + <!-- + This section exists so that people following /current/ links to documentation + don't get a 404 when we move or rename things. And users who find old versions + of the docs in searches or old command names when checking the index can + follow links to the new commands. + + Each subsection here should retain the same <chapter>, <appendix> and/or + <sect1> "id" attribute that was used for the relevant documentation before + it was renamed or moved. Do not prepend "obsolete-" or anything, keep it + exactly the same. These ids are used to determine the filenames for generated + HTML docs so changing them will break links. + + Each entry should also insert index terms redirecting from the old to new + names. The recommended spelling is + + <indexterm><primary>oldname</primary><see>newname</see></indexterm> + + We don't bother with attempting to maintain down-version linking, e.g from + pg_waldump to pg_xlogdump. Users of old versions should use old docs. There + is no need to add index terms pointing from the new to old names. + --> + + &obsolete-recovery-config; + &obsolete-pgxlogdump; + &obsolete-pgresetxlog; + &obsolete-pgreceivexlog; + +</appendix> diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index dd2778611f..28fd0670f7 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -4196,8 +4196,9 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class=" <title>Standby Servers</title> <para> - These settings control the behavior of a standby server that is - to receive replication data. Their values on the master server + These settings control the behavior of a + <link linkend="standby-server-operation">standby server</link> + that is to receive replication data. Their values on the master server are irrelevant. </para> diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 68179f71cd..6c8b12376e 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -182,3 +182,10 @@ <!-- back matter --> <!ENTITY biblio SYSTEM "biblio.sgml"> + +<!-- Stubs for removed entries to preserve public links --> +<!ENTITY obsolete SYSTEM "appendix-obsolete.sgml"> +<!ENTITY obsolete-recovery-config SYSTEM "appendix-obsolete-recovery-config.sgml"> +<!ENTITY obsolete-pgxlogdump SYSTEM "appendix-obsolete-pgxlogdump.sgml"> +<!ENTITY obsolete-pgresetxlog SYSTEM "appendix-obsolete-pgresetxlog.sgml"> +<!ENTITY obsolete-pgreceivexlog SYSTEM "appendix-obsolete-pgreceivexlog.sgml"> diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index 2e7fa4a92e..37c44396f8 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -615,9 +615,17 @@ protocol to make nodes agree on a serializable transactional order. </sect2> - <sect2 id="standby-server-operation"> + <sect2 id="standby-server-operation" xreflabel="Standby Server Operation"> <title>Standby Server Operation</title> + <para> + A server enters standby mode if a + <anchor id="file-standby-signal" xreflabel="standby.signal"/> + <filename>standby.signal</filename> + <indexterm><primary><filename>standby.signal</filename></primary></indexterm> + file exists in the data directory when the server is started. + </para> + <para> In standby mode, the server continuously applies WAL received from the master server. The standby server can read WAL from a WAL archive @@ -691,7 +699,8 @@ protocol to make nodes agree on a serializable transactional order. <para> To set up the standby server, restore the base backup taken from primary server (see <xref linkend="backup-pitr-recovery"/>). Create a file - <filename>standby.signal</filename> in the standby's cluster data + <link linkend="file-standby-signal"><filename>standby.signal</filename></link><indexterm><primary>standby.signal</primary></indexterm> + in the standby's cluster data directory. Set <xref linkend="guc-restore-command"/> 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 <varname>recovery_target_timeline</varname> is set to @@ -2114,7 +2123,8 @@ if (!triggered) <para> If <varname>hot_standby</varname> is <literal>on</literal> in <filename>postgresql.conf</filename> - (the default value) and there is a <filename>standby.signal</filename> + (the default value) and there is a + <link linkend="file-standby-signal"><filename>standby.signal</filename></link><indexterm><primary>standby.signal</primary><secondary>for hot standby</secondary></indexterm> 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 c41ce9499b..763941e1e1 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -288,6 +288,7 @@ break is not needed in a wider output rendering. &acronyms; &glossary; &color; + &obsolete; </part> diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml index 03f31b2879..ac442b81a5 100644 --- a/doc/src/sgml/ref/pg_basebackup.sgml +++ b/doc/src/sgml/ref/pg_basebackup.sgml @@ -199,7 +199,10 @@ PostgreSQL documentation <listitem> <para> - Creates a <filename>standby.signal</filename> file and appends + Creates a + <link linkend="file-standby-signal"><filename>standby.signal</filename></link> + <indexterm><primary><filename>standby.signal</filename></primary><secondary>pg_basebackup --write-recovery-conf</secondary></indexterm> + file and appends connection settings to the <filename>postgresql.auto.conf</filename> file in the target directory (or within the base archive file when using tar format). This eases setting up a standby server using the -- 2.27.0
signature.asc
Description: PGP signature
