Skip to content

Commit 448e86c

Browse files
sfrostsfrost
committed
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
1 parent cf8384a commit 448e86c

10 files changed

+198
-6
lines changed

‎doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<!-- doc/src/sgml/obsolete-pgxlogdump.sgml -->
2+
<!--
3+
See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
4+
-->
5+
6+
<sect1 id="app-pgreceivexlog" xreflabel="pg_receivexlog">
7+
<title><command>pg_receivexlog</command> renamed to <command>pg_receivewal</command></title>
8+
9+
<indexterm>
10+
<primary>pg_receivexlog</primary>
11+
<see>pg_receivewal</see>
12+
</indexterm>
13+
14+
<para>
15+
PostgreSQL 9.6 and below provided a command named
16+
<command>pg_receivexlog</command>
17+
<indexterm><primary>pg_receivexlog</primary></indexterm>
18+
to fetch write-ahead-log (WAL) files. This command was renamed to <command>pg_receivewal</command>, see
19+
<xref linkend="app-pgreceivewal"/> for documentation of <command>pg_receivewal</command> and see
20+
<link linkend="release-prior">the release notes for PostgreSQL 10</link> for details
21+
on this change.
22+
</para>
23+
24+
</sect1>

‎doc/src/sgml/appendix-obsolete-pgresetxlog.sgml

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<!-- doc/src/sgml/obsolete-pgresetxlog.sgml -->
2+
<!--
3+
See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
4+
-->
5+
6+
<sect1 id="app-pgresetxlog" xreflabel="pg_resetxlog">
7+
<title><command>pg_resetxlog</command> renamed to <command>pg_resetwal</command></title>
8+
9+
<indexterm>
10+
<primary>pg_resetxlog</primary>
11+
<see>pg_resetwal</see>
12+
</indexterm>
13+
14+
<para>
15+
PostgreSQL 9.6 and below provided a command named
16+
<command>pg_resetxlog</command>
17+
<indexterm><primary>pg_resetxlog</primary></indexterm>
18+
to reset the write-ahead-log (WAL) files. This command was renamed to <command>pg_resetwal</command>, see
19+
<xref linkend="app-pgresetwal"/> for documentation of <command>pg_resetwal</command> and see
20+
<link linkend="release-prior">the release notes for PostgreSQL 10</link> for details
21+
on this change.
22+
</para>
23+
24+
</sect1>

‎doc/src/sgml/appendix-obsolete-pgxlogdump.sgml

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<!-- doc/src/sgml/obsolete-pgxlogdump.sgml -->
2+
<!--
3+
See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
4+
-->
5+
6+
<sect1 id="pgxlogdump" xreflabel="pg_xlogdump">
7+
<title><command>pg_xlogdump</command> renamed to <command>pg_waldump</command></title>
8+
9+
<indexterm>
10+
<primary>pg_xlogdump</primary>
11+
<see>pg_waldump</see>
12+
</indexterm>
13+
14+
<para>
15+
PostgreSQL 9.6 and below provided a command named
16+
<command>pg_xlogdump</command>
17+
<indexterm><primary>pg_xlogdump</primary></indexterm>
18+
to read write-ahead-log (WAL) files. This command was renamed to <command>pg_waldump</command>, see
19+
<xref linkend="pgwaldump"/> for documentation of <command>pg_waldump</command> and see
20+
<link linkend="release-prior">the release notes for PostgreSQL 10</link> for details
21+
on this change.
22+
</para>
23+
24+
</sect1>

‎doc/src/sgml/appendix-obsolete-recovery-config.sgml

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
<!-- doc/src/sgml/obsolete-recovery-config.sgml -->
2+
<!--
3+
See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
4+
-->
5+
6+
<sect1 id="recovery-config" xreflabel="recovery.conf">
7+
<title><filename>recovery.conf</filename> file merged into <filename>postgresql.conf</filename></title>
8+
9+
<indexterm>
10+
<primary><filename>recovery.conf</filename></primary>
11+
</indexterm>
12+
13+
<para>
14+
PostgreSQL 11 and below used a configuration file named
15+
<filename>recovery.conf</filename>
16+
<indexterm><primary>recovery.conf</primary></indexterm>
17+
to manage replicas and standbys. Support for this file was removed in PostgreSQL 12. See
18+
<link linkend="release-prior">the release notes for PostgreSQL 12</link> for details
19+
on this change.
20+
</para>
21+
22+
<para>
23+
On PostgreSQL 12 and above,
24+
<link linkend="continuous-archiving">archive recovery, streaming replication, and PITR</link>
25+
are configured using
26+
<link linkend="runtime-config-replication-standby">normal server configuration parameters</link>.
27+
These are set in <filename>postgresql.conf</filename> or via
28+
<link linkend="sql-altersystem">ALTER SYSTEM</link>
29+
like any other parameter.
30+
</para>
31+
32+
<para>
33+
The server will not start if a <filename>recovery.conf</filename> exists.
34+
</para>
35+
36+
<para>
37+
The
38+
<literal>trigger_file</literal>
39+
<indexterm>
40+
<primary>trigger_file</primary>
41+
<see>promote_trigger_file</see>
42+
</indexterm>
43+
setting has been renamed to
44+
<xref linkend="guc-promote-trigger-file"/>.
45+
</para>
46+
47+
<para>
48+
The
49+
<literal>standby_mode</literal>
50+
<indexterm>
51+
<primary>standby_mode</primary>
52+
<see>standby.signal</see>
53+
</indexterm>
54+
setting has been removed. A <filename>standby.signal</filename> file in the data directory
55+
is used instead. See <xref linkend="standby-server-operation"/> for details.
56+
</para>
57+
58+
</sect1>

‎doc/src/sgml/appendix-obsolete.sgml

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<!-- doc/src/sgml/obsolete.sgml -->
2+
3+
<appendix id="appendix-obsolete">
4+
<title>Obsolete or Renamed Features</title>
5+
6+
<para>
7+
Functionality is sometimes removed from PostgreSQL, feature, setting
8+
and file names sometimes change, or documentation moves to different
9+
places. This section directs users coming from old versions of the
10+
documentation or from external links to the appropriate new location
11+
for the information they need.
12+
</para>
13+
14+
<!--
15+
This section exists so that people following /current/ links to documentation
16+
don't get a 404 when we move or rename things. And users who find old versions
17+
of the docs in searches or old command names when checking the index can
18+
follow links to the new commands.
19+
20+
Each subsection here should retain the same <chapter>, <appendix> and/or
21+
<sect1> "id" attribute that was used for the relevant documentation before
22+
it was renamed or moved. Do not prepend "obsolete-" or anything, keep it
23+
exactly the same. These ids are used to determine the filenames for generated
24+
HTML docs so changing them will break links.
25+
26+
Each entry should also insert index terms redirecting from the old to new
27+
names. The recommended spelling is
28+
29+
<indexterm><primary>oldname</primary><see>newname</see></indexterm>
30+
31+
We don't bother with attempting to maintain down-version linking, e.g from
32+
pg_waldump to pg_xlogdump. Users of old versions should use old docs. There
33+
is no need to add index terms pointing from the new to old names.
34+
-->
35+
36+
&obsolete-recovery-config;
37+
&obsolete-pgxlogdump;
38+
&obsolete-pgresetxlog;
39+
&obsolete-pgreceivexlog;
40+
41+
</appendix>

‎doc/src/sgml/config.sgml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4062,8 +4062,9 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
40624062
<title>Standby Servers</title>
40634063

40644064
<para>
4065-
These settings control the behavior of a standby server that is
4066-
to receive replication data. Their values on the master server
4065+
These settings control the behavior of a
4066+
<link linkend="standby-server-operation">standby server</link>
4067+
that is to receive replication data. Their values on the master server
40674068
are irrelevant.
40684069
</para>
40694070

‎doc/src/sgml/filelist.sgml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -179,3 +179,10 @@
179179

180180
<!-- back matter -->
181181
<!ENTITY biblio SYSTEM "biblio.sgml">
182+
183+
<!-- Stubs for removed entries to preserve public links -->
184+
<!ENTITY obsolete SYSTEM "appendix-obsolete.sgml">
185+
<!ENTITY obsolete-recovery-config SYSTEM "appendix-obsolete-recovery-config.sgml">
186+
<!ENTITY obsolete-pgxlogdump SYSTEM "appendix-obsolete-pgxlogdump.sgml">
187+
<!ENTITY obsolete-pgresetxlog SYSTEM "appendix-obsolete-pgresetxlog.sgml">
188+
<!ENTITY obsolete-pgreceivexlog SYSTEM "appendix-obsolete-pgreceivexlog.sgml">

‎doc/src/sgml/high-availability.sgml

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -611,9 +611,17 @@ protocol to make nodes agree on a serializable transactional order.
611611

612612
</sect2>
613613

614-
<sect2 id="standby-server-operation">
614+
<sect2 id="standby-server-operation" xreflabel="Standby Server Operation">
615615
<title>Standby Server Operation</title>
616616

617+
<para>
618+
A server enters standby mode if a
619+
<anchor id="file-standby-signal" xreflabel="standby.signal"/>
620+
<filename>standby.signal</filename>
621+
<indexterm><primary><filename>standby.signal</filename></primary></indexterm>
622+
file exists in the data directory when the server is started.
623+
</para>
624+
617625
<para>
618626
In standby mode, the server continuously applies WAL received from the
619627
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.
686694
<para>
687695
To set up the standby server, restore the base backup taken from primary
688696
server (see <xref linkend="backup-pitr-recovery"/>). Create a file
689-
<filename>standby.signal</filename> in the standby's cluster data
697+
<link linkend="file-standby-signal"><filename>standby.signal</filename></link><indexterm><primary>standby.signal</primary></indexterm>
698+
in the standby's cluster data
690699
directory. Set <xref linkend="guc-restore-command"/> to a simple command to copy files from
691700
the WAL archive. If you plan to have multiple standby servers for high
692701
availability purposes, make sure that <varname>recovery_target_timeline</varname> is set to
@@ -2103,7 +2112,8 @@ if (!triggered)
21032112

21042113
<para>
21052114
If <varname>hot_standby</varname> is <literal>on</literal> in <filename>postgresql.conf</filename>
2106-
(the default value) and there is a <filename>standby.signal</filename>
2115+
(the default value) and there is a
2116+
<link linkend="file-standby-signal"><filename>standby.signal</filename></link><indexterm><primary>standby.signal</primary><secondary>for hot standby</secondary></indexterm>
21072117
file present, the server will run in Hot Standby mode.
21082118
However, it may take some time for Hot Standby connections to be allowed,
21092119
because the server will not accept connections until it has completed

‎doc/src/sgml/postgres.sgml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -278,6 +278,7 @@
278278
&docguide;
279279
&limits;
280280
&acronyms;
281+
&obsolete;
281282

282283
</part>
283284

‎doc/src/sgml/ref/pg_basebackup.sgml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,9 @@ PostgreSQL documentation
215215
<listitem>
216216

217217
<para>
218-
Create <filename>standby.signal</filename> and append connection settings
218+
Create <link linkend="file-standby-signal"><filename>standby.signal</filename></link>
219+
<indexterm><primary><filename>standby.signal</filename></primary><secondary>pg_basebackup --write-recovery-conf</secondary></indexterm>
220+
file and append connection settings
219221
to <filename>postgresql.auto.conf</filename> in the output
220222
directory (or into the base archive file when using tar format) to
221223
ease setting up a standby server.

0 commit comments

Comments
 (0)