Skip to content

Commit 3b0c647

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 522d1a8 commit 3b0c647

10 files changed

+199
-5
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 & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4312,7 +4312,9 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
43124312
<title>Standby Servers</title>
43134313

43144314
<para>
4315-
These settings control the behavior of a standby server that is
4315+
These settings control the behavior of a
4316+
<link linkend="standby-server-operation">standby server</link>
4317+
that is
43164318
to receive replication data. Their values on the primary server
43174319
are irrelevant.
43184320
</para>

‎doc/src/sgml/filelist.sgml

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

185185
<!-- back matter -->
186186
<!ENTITY biblio SYSTEM "biblio.sgml">
187+
188+
<!-- Stubs for removed entries to preserve public links -->
189+
<!ENTITY obsolete SYSTEM "appendix-obsolete.sgml">
190+
<!ENTITY obsolete-recovery-config SYSTEM "appendix-obsolete-recovery-config.sgml">
191+
<!ENTITY obsolete-pgxlogdump SYSTEM "appendix-obsolete-pgxlogdump.sgml">
192+
<!ENTITY obsolete-pgresetxlog SYSTEM "appendix-obsolete-pgresetxlog.sgml">
193+
<!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
@@ -613,9 +613,17 @@ protocol to make nodes agree on a serializable transactional order.
613613

614614
</sect2>
615615

616-
<sect2 id="standby-server-operation">
616+
<sect2 id="standby-server-operation" xreflabel="Standby Server Operation">
617617
<title>Standby Server Operation</title>
618618

619+
<para>
620+
A server enters standby mode if a
621+
<anchor id="file-standby-signal" xreflabel="standby.signal"/>
622+
<filename>standby.signal</filename>
623+
<indexterm><primary><filename>standby.signal</filename></primary></indexterm>
624+
file exists in the data directory when the server is started.
625+
</para>
626+
619627
<para>
620628
In standby mode, the server continuously applies WAL received from the
621629
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.
689697
<para>
690698
To set up the standby server, restore the base backup taken from primary
691699
server (see <xref linkend="backup-pitr-recovery"/>). Create a file
692-
<filename>standby.signal</filename> in the standby's cluster data
700+
<link linkend="file-standby-signal"><filename>standby.signal</filename></link><indexterm><primary>standby.signal</primary></indexterm>
701+
in the standby's cluster data
693702
directory. Set <xref linkend="guc-restore-command"/> to a simple command to copy files from
694703
the WAL archive. If you plan to have multiple standby servers for high
695704
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)'
19361945

19371946
<para>
19381947
If <varname>hot_standby</varname> is <literal>on</literal> in <filename>postgresql.conf</filename>
1939-
(the default value) and there is a <filename>standby.signal</filename>
1948+
(the default value) and there is a
1949+
<link linkend="file-standby-signal"><filename>standby.signal</filename></link><indexterm><primary>standby.signal</primary><secondary>for hot standby</secondary></indexterm>
19401950
file present, the server will run in Hot Standby mode.
19411951
However, it may take some time for Hot Standby connections to be allowed,
19421952
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
@@ -289,6 +289,7 @@ break is not needed in a wider output rendering.
289289
&acronyms;
290290
&glossary;
291291
&color;
292+
&obsolete;
292293

293294
</part>
294295

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -199,7 +199,10 @@ PostgreSQL documentation
199199
<listitem>
200200

201201
<para>
202-
Creates a <filename>standby.signal</filename> file and appends
202+
Creates a
203+
<link linkend="file-standby-signal"><filename>standby.signal</filename></link>
204+
<indexterm><primary><filename>standby.signal</filename></primary><secondary>pg_basebackup --write-recovery-conf</secondary></indexterm>
205+
file and appends
203206
connection settings to the <filename>postgresql.auto.conf</filename>
204207
file in the target directory (or within the base archive file when
205208
using tar format). This eases setting up a standby server using the

0 commit comments

Comments
 (0)