Hi all
I noticed that when recovery.conf was removed in 2dedf4d9a8 (yay!) the docs
for it were removed completely as well. That's largely sensible, but is
confusing when users have upgraded and are trying to find out what
happened, or how to configure equivalent functionality.
https://www.postgresql.org/docs/11/recovery-config.html just vanished for
/12/, and as a result
https://www.postgresql.org/docs/current/recovery-config.html is a 404. I
think that's unhelpful since we encourage people to use /current/ links.
The attached patch restores the recovery-config.html page with a short note
explaining why it's gone and what to do instead. It's added to a new
appendix "Obsolete or renamed features, settings and files".
I found it remarkably hard to find out what exactly made a "standby server"
actually be a standby server in the docs so I have added a couple of
cross-references that make the role of the standby.signal file much more
discoverable from relevant locations.
I propose a policy that we preserve our <chapter> and <sect1> ids. We
should move them to an "obsolete" section at the end, like the one I
created here, and provide stubs for them instead of removing them. That'll
help prevent us from breaking links on the wider web, in 3rd party
documentation, etc.
From 9d6db17c8bff093c08a90129d0ba181554b5d3e2 Mon Sep 17 00:00:00 2001
From: Craig Ringer <craig.rin...@2ndquadrant.com>
Date: Tue, 10 Nov 2020 10:51:20 +0800
Subject: [PATCH] Link the old recovery.conf docs chapter to the new docs
Add a new docs section for obsolete topics. In it, add a section for
the removed recovery.conf documentation. Explain that recovery.conf
has been removed in Pg 12 and where to find the replacement
configuration.
This way when someone running PostgreSQL 12+ searches for
"recovery.conf" and finds the /11/ documentation for it, the website
docs will have a "latest" link that explains where it went. Right now
the docs file just ends, with no link for later versions. This also
helps people following /current/ web links from articles, blogs, etc,
who would currently get a 404.
Appropriate index terms are added to direct searchers to the right
place too.
---
.../appendix-obsolete-recovery-config.sgml | 61 +++++++++++++++++++
doc/src/sgml/appendix-obsolete.sgml | 19 ++++++
doc/src/sgml/config.sgml | 4 +-
doc/src/sgml/filelist.sgml | 4 ++
doc/src/sgml/high-availability.sgml | 16 ++++-
doc/src/sgml/postgres.sgml | 1 +
doc/src/sgml/ref/pg_basebackup.sgml | 5 +-
7 files changed, 105 insertions(+), 5 deletions(-)
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-recovery-config.sgml b/doc/src/sgml/appendix-obsolete-recovery-config.sgml
new file mode 100644
index 0000000000..98e4b2711d
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-recovery-config.sgml
@@ -0,0 +1,61 @@
+<!-- doc/src/sgml/obsolete-recovery-config.sgml -->
+<!--
+ This file exists so that people following /current/ links to documentation
+ don't get a 404, and so that people who are looking for the recovery.conf
+ documentation for postgresql 12+ can easily find out where to look instead.
+-->
+
+<sect1 id="recovery-config" xreflabel="recovery.conf">
+ <title>The <filename>recovery.conf</filename> file</title>
+
+ <indexterm>
+ <primary>obsolete</primary>
+ <secondary><filename>recovery.conf</filename></secondary>
+ </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>
+ <seealso>promote_trigger_file</seealso>
+ </indexterm>
+ setting has been renamed to
+ <xref linkend="guc-promote-trigger-file"/>
+ </para>
+
+ <para>
+ The
+ <literal>standby_mode</literal>
+ <indexterm>
+ <primary>standby_mode</primary>
+ <seealso>standby.signal</seealso>
+ </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..deebbd083d
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete.sgml
@@ -0,0 +1,19 @@
+<!-- doc/src/sgml/obsolete.sgml -->
+
+<appendix id="appendix-obsolete">
+ <title>Obsolete or renamed features, settings and files</title>
+
+ <indexterm>
+ <primary>obsolete</primary>
+ </indexterm>
+
+ <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>
+
+ &obsolete-recovery-config;
+
+</appendix>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index f043433e31..8148b19790 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -4227,7 +4227,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 38e8aa0bbf..aa1a39eedc 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -185,3 +185,7 @@
<!-- 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">
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index 19d7bd2b28..3cce684873 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
@@ -2075,7 +2084,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 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 e993e8761c..48902066d6 100644
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -198,7 +198,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.26.2
