Add docs stub for recovery.conf
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.
Attachments:
0001-Link-the-old-recovery.conf-docs-chapter-to-the-new-d.patchtext/x-patch; charset=US-ASCII; name=0001-Link-the-old-recovery.conf-docs-chapter-to-the-new-d.patchDownload
From 9d6db17c8bff093c08a90129d0ba181554b5d3e2 Mon Sep 17 00:00:00 2001
From: Craig Ringer <craig.ringer@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
On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote:
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.
I don't see the logic in carrying doc stuff that we don't have anymore.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
On Wed, Nov 11, 2020 at 12:44 PM Bruce Momjian <bruce@momjian.us> wrote:
On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote:
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.
I don't see the logic in carrying doc stuff that we don't have anymore.
I do. Saying why something went away has value. For small stuff you have
commit messages. For user-facing documentation stuff that warranted its
own page, having said page remain and describe the change seems worthwhile.
David J.
On 11 Nov 2020, at 20:44, Bruce Momjian <bruce@momjian.us> wrote:
On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote:
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.I don't see the logic in carrying doc stuff that we don't have anymore.
Well, we do have that already in <tip>'s sprinkled across the docs where it
makes sense to help transitioning users, like this one in func.sgml:
"Prior to PostgreSQL 12, it was possible to skip arbitrary text in the
input string using non-letter or non-digit characters..."
It doesn't seem like a terrible idea to do a similar one for recovery.conf.
cheers ./daniel
On Wed, Nov 11, 2020 at 08:59:40PM +0100, Daniel Gustafsson wrote:
On 11 Nov 2020, at 20:44, Bruce Momjian <bruce@momjian.us> wrote:
On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote: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.I don't see the logic in carrying doc stuff that we don't have anymore.
Well, we do have that already in <tip>'s sprinkled across the docs where it
makes sense to help transitioning users, like this one in func.sgml:"Prior to PostgreSQL 12, it was possible to skip arbitrary text in the
input string using non-letter or non-digit characters..."It doesn't seem like a terrible idea to do a similar one for recovery.conf.
I am fine with a tip. The patch looked like it was creating a new
chapter for it.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
On 11 Nov 2020, at 21:01, Bruce Momjian <bruce@momjian.us> wrote:
On Wed, Nov 11, 2020 at 08:59:40PM +0100, Daniel Gustafsson wrote:
On 11 Nov 2020, at 20:44, Bruce Momjian <bruce@momjian.us> wrote:
On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote: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.I don't see the logic in carrying doc stuff that we don't have anymore.
Well, we do have that already in <tip>'s sprinkled across the docs where it
makes sense to help transitioning users, like this one in func.sgml:"Prior to PostgreSQL 12, it was possible to skip arbitrary text in the
input string using non-letter or non-digit characters..."It doesn't seem like a terrible idea to do a similar one for recovery.conf.
I am fine with a tip. The patch looked like it was creating a new
chapter for it.
I admittedly hadn't looked at the patch, but now that I have I agree with not
adding a separate "obsolete" topic for it. I'd prefer to use tips within the
docs, they will also help guide users who search for recovery.conf and lands in
the tip which is next to the relevant updated documentation on the topic.
cheers ./daniel
On Thu, Nov 12, 2020 at 3:44 AM Bruce Momjian <bruce@momjian.us> wrote:
On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote:
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.
I don't see the logic in carrying doc stuff that we don't have anymore.
I explained why.
Here's how the rendered docs look: https://imgur.com/a/VyjzEw5
Think. You're used to recovery.conf. You've recently switched to pg 12. You
search for "recovery.conf" or "primary_slot_name" or "standby_mode" or
something. You of course land up at
https://www.postgresql.org/docs/11/recovery-config.html or another version.
What do you do now? There's no "12" or "current" link for your version. You
don't follow postgres development closely, and you have no idea we removed
the file. You might work it out from the release notes. But even then, if
you try searching for "standby_mode" in the updated docs will tell you
basically nothing, it has just vanished
Also by simply deleting the page, we've broken web links to
https://www.postgresql.org/docs/current/recovery-config.html
So there are three really good reasons:
* Help users of the web docs navigate to the right place when we remove
things
* Don't break web links (breaking links without redirects is bad, the web
is sad)
* Help upgrading users who know the old terms find the new terms
I'd welcome your suggestions on other ways to arrange this, so long as it
meets the basic requirement "retain the linktable target 'recovery-config' "
In general I think it's quite unpleasant for users to have docs sections
just vanish. I strongly suggest that we enact a policy going forwards that
any <chapter> or <sect1> removal should be accompanied by a redirect or
stub that helps users find the new contents. It regularly annoys me when
I'm trying to navigate around various versions of the docs and things just
vanish.
On Thu, Nov 12, 2020 at 4:01 AM Bruce Momjian <bruce@momjian.us> wrote:
On Wed, Nov 11, 2020 at 08:59:40PM +0100, Daniel Gustafsson wrote:
On 11 Nov 2020, at 20:44, Bruce Momjian <bruce@momjian.us> wrote:
On Tue, Nov 10, 2020 at 01:38:14PM +0800, Craig Ringer wrote: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.
I don't see the logic in carrying doc stuff that we don't have anymore.
Well, we do have that already in <tip>'s sprinkled across the docs where
it
makes sense to help transitioning users, like this one in func.sgml:
"Prior to PostgreSQL 12, it was possible to skip arbitrary text in
the
input string using non-letter or non-digit characters..."
It doesn't seem like a terrible idea to do a similar one for
recovery.conf.
I am fine with a tip. The patch looked like it was creating a new
chapter for it.
It is. Or rather, an appendix right at the end to hold info on things we
removed or renamed and where to find them now.
You can't AFAICS make docbook create a toplevel linkable file for a <tip> .
A <tip> won't un-break
https://www.postgresql.org/docs/current/recovery-config.html or make help
people who visit https://www.postgresql.org/docs/11/recovery-config.html
figure out what's going on if they're using pg12 and there's no link to
version 12 in the nav section. A <tip> won't add index entries for renamed
settings, so someone looking up "standby_mode" can find out that we've
switched to a file called "standby.signal" instead.
Pretend you're a user who has upgraded from pg 11. You're looking at the Pg
12 docs. How long does it take you to find out how to make a server into a
standby now? It took me longer than I would've expected...
On Thu, Nov 12, 2020 at 10:21:02AM +0800, Craig Ringer wrote:
Here's how the rendered docs look: https://imgur.com/a/VyjzEw5
Think. You're used to recovery.conf. You've recently switched to pg 12. You
search for "recovery.conf" or "primary_slot_name" or "standby_mode" or
something. You of course land up at https://www.postgresql.org/docs/11/
recovery-config.html or another version.What do you do now? There's no "12" or "current" link for your version. You
don't follow postgres development closely, and you have no idea we removed the
file. You might work it out from the release notes. But even then, if you try
searching for "standby_mode" in the updated docs will tell you basically
nothing, it has just vanishedAlso by simply deleting the page, we've broken web links to https://
www.postgresql.org/docs/current/recovery-config.htmlSo there are three really good reasons:
* Help users of the web docs navigate to the right place when we remove things
* Don't break web links (breaking links without redirects is bad, the web is
sad)
* Help upgrading users who know the old terms find the new termsI'd welcome your suggestions on other ways to arrange this, so long as it meets
the basic requirement "retain the linktable target 'recovery-config' "
This is certainly not the first or last time we will rename things.
Fortunately, this has already been discussed in the renaming of default
roles to predefined roles:
/messages/by-id/157742545062.1149.11052653770497832538@wrigleys.postgresql.org
This naming change has not happened yet, even though the issue is 11
months old, but the agreed-upon way to handle this is to use a website
redirect that links to the new text. You can add a "tip" there so they
understand the renaming has happened.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
Greetings,
* Bruce Momjian (bruce@momjian.us) wrote:
On Thu, Nov 12, 2020 at 10:21:02AM +0800, Craig Ringer wrote:
Here's how the rendered docs look: https://imgur.com/a/VyjzEw5
Think. You're used to recovery.conf. You've recently switched to pg 12. You
search for "recovery.conf" or "primary_slot_name" or "standby_mode" or
something. You of course land up at https://www.postgresql.org/docs/11/
recovery-config.html or another version.What do you do now? There's no "12" or "current" link for your version. You
don't follow postgres development closely, and you have no idea we removed the
file. You might work it out from the release notes. But even then, if you try
searching for "standby_mode" in the updated docs will tell you basically
nothing, it has just vanishedAlso by simply deleting the page, we've broken web links to https://
www.postgresql.org/docs/current/recovery-config.htmlSo there are three really good reasons:
* Help users of the web docs navigate to the right place when we remove things
* Don't break web links (breaking links without redirects is bad, the web is
sad)
* Help upgrading users who know the old terms find the new termsI'd welcome your suggestions on other ways to arrange this, so long as it meets
the basic requirement "retain the linktable target 'recovery-config' "This is certainly not the first or last time we will rename things.
Indeed, we've renamed things a number of times before, eg:
https://www.postgresql.org/docs/current/pgwaldump.html
where the 9.6 link goes to:
https://www.postgresql.org/docs/9.6/pgxlogdump.html
and the 'current' link from the 9.6 page goes to the pgwaldump page,
which all works pretty well, if all you're looking at is our
documentation and not considering external links into the documentation.
However, that isn't what Craig's raising a concern over here (at least,
not exclusively), it's this issue:
https://www.postgresql.org/docs/current/pgxlogdump.html
Which currently goes to a 404.
Now, the pgweb feature that Jonathan wrote recently might actually be
exactly what we need to fix that, and to address the issue with
recovery config documentation that Craig raises.
Fortunately, this has already been discussed in the renaming of default
roles to predefined roles:/messages/by-id/157742545062.1149.11052653770497832538@wrigleys.postgresql.org
This naming change has not happened yet, even though the issue is 11
months old, but the agreed-upon way to handle this is to use a website
redirect that links to the new text. You can add a "tip" there so they
understand the renaming has happened.
That rename will suffer the same problem that Craig is concerned about
here regarding the 'current' link, once it's done. I tend to agree with
Craig that it'd be good to improve on this situation, and I've reached
out to Jonathan to ask about using his new feature to have those
/current/ links redirect to the renamed page. I'm actually wondering if
maybe we should just always do that for all the dog page aliases..
Might make more sense to discuss this over on -www though.
Thanks,
Stephen
Greetings,
* Stephen Frost (sfrost@snowman.net) wrote:
* Bruce Momjian (bruce@momjian.us) wrote:
On Thu, Nov 12, 2020 at 10:21:02AM +0800, Craig Ringer wrote:
Here's how the rendered docs look: https://imgur.com/a/VyjzEw5
Think. You're used to recovery.conf. You've recently switched to pg 12. You
search for "recovery.conf" or "primary_slot_name" or "standby_mode" or
something. You of course land up at https://www.postgresql.org/docs/11/
recovery-config.html or another version.What do you do now? There's no "12" or "current" link for your version. You
don't follow postgres development closely, and you have no idea we removed the
file. You might work it out from the release notes. But even then, if you try
searching for "standby_mode" in the updated docs will tell you basically
nothing, it has just vanishedAlso by simply deleting the page, we've broken web links to https://
www.postgresql.org/docs/current/recovery-config.htmlSo there are three really good reasons:
* Help users of the web docs navigate to the right place when we remove things
* Don't break web links (breaking links without redirects is bad, the web is
sad)
* Help upgrading users who know the old terms find the new termsI'd welcome your suggestions on other ways to arrange this, so long as it meets
the basic requirement "retain the linktable target 'recovery-config' "This is certainly not the first or last time we will rename things.
Indeed, we've renamed things a number of times before, eg:
https://www.postgresql.org/docs/current/pgwaldump.html
where the 9.6 link goes to:
https://www.postgresql.org/docs/9.6/pgxlogdump.html
and the 'current' link from the 9.6 page goes to the pgwaldump page,
which all works pretty well, if all you're looking at is our
documentation and not considering external links into the documentation.However, that isn't what Craig's raising a concern over here (at least,
not exclusively), it's this issue:https://www.postgresql.org/docs/current/pgxlogdump.html
Which currently goes to a 404.
Now, the pgweb feature that Jonathan wrote recently might actually be
exactly what we need to fix that, and to address the issue with
recovery config documentation that Craig raises.
After chatting with Jonathan about this for a bit and testing it out in
our test environment, I've gone ahead and added an entry for
pgxlogdump.html to redirect to pgwaldump.html, and that seems to be
working well.
With that then- Craig, can you look at how the pgxlogdump -> pgwaldump
pages work and see if using that would address the concerns you've
raised here..?
Though we need to decide which page 'recovery-config' should go to in
newer versions.
I'm continuing to chat with Jonathan about if it'd make sense to do the
same for the other doc aliases.
Thanks,
Stephen
On Thu, Nov 12, 2020 at 09:47:42AM -0500, Stephen Frost wrote:
Fortunately, this has already been discussed in the renaming of default
roles to predefined roles:/messages/by-id/157742545062.1149.11052653770497832538@wrigleys.postgresql.org
This naming change has not happened yet, even though the issue is 11
months old, but the agreed-upon way to handle this is to use a website
redirect that links to the new text. You can add a "tip" there so they
understand the renaming has happened.That rename will suffer the same problem that Craig is concerned about
here regarding the 'current' link, once it's done. I tend to agree with
Craig that it'd be good to improve on this situation, and I've reached
out to Jonathan to ask about using his new feature to have those
/current/ links redirect to the renamed page. I'm actually wondering if
maybe we should just always do that for all the dog page aliases..Might make more sense to discuss this over on -www though.
Yes, I am thinking someone could go back and add redirects for previous
renames too. It would be interesting also to scrape the web logs for
404 errors to see which renames cause the most failures and do those
first.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
On Thu, Nov 12, 2020 at 11:25 PM Stephen Frost <sfrost@snowman.net> wrote:
Now, the pgweb feature that Jonathan wrote recently might actually be
exactly what we need to fix that, and to address the issue with
recovery config documentation that Craig raises.After chatting with Jonathan about this for a bit and testing it out in
our test environment, I've gone ahead and added an entry for
pgxlogdump.html to redirect to pgwaldump.html, and that seems to be
working well.
Thanks.
With that then- Craig, can you look at how the pgxlogdump -> pgwaldump
pages work and see if using that would address the concerns you've
raised here..?
Though we need to decide which page 'recovery-config' should go to in
newer versions.
Since we basically vanished all evidence of the old configuration, I don't
think there is a suitable place.
I maintain that simply vanishing terms from the docs without any sort of
explanation is a user-hostile action that we should fix and stop doing If
we had something in the docs and we remove it, it's not unduly burdensome
to have some index entries that point to the replacement/renamed terms, and
a short appendix entry explaining what happened.
If that is for some reason unacceptable (and I don't see anyone giving any
actual reason why) the closest I can come up with is probably redirecting
to
https://www.postgresql.org/docs/current/warm-standby.html#STANDBY-SERVER-OPERATION
. But that needs to be fixed to actually explicitly state what makes a
standby server into a standby server (per my patch), since right now it
just kind of assumes you know about standby.signal .
But... fiddling with the website addresses none of my other concerns. In
particular, it doesn't help a user understand that "standby_mode" is gone
and to look for "standby.signal" instead. It doesn't provide any "see also"
pointers for old terms to point to new terms in the index. Website
redirects won't help users with local copies of the docs or manpages who
are wondering what the heck happened to recovery.conf and standby_mode
either.
So I still think this needs a docs patch. Redirects on the website are not
sufficient. If you don't like how I spelled it, consider calling it
"important incompatible changes" or something.
The release notes are IMO not sufficient for this because (a) they don't
appear in the index; (b) you have to know something has been
removed/changed before you know to look in the relnotes for it; (c) you
have to find the relnotes for the correct release to find the info you
want. An appendix covering important renamings, removals and other
incompatible changes would address all those points *and* fix the web
links, man page names, etc.
Can anyone tell me why the solution I proposed is not acceptable, and why
we have to invent a different one instead? The website redirect is good
and all, but doesn't really solve the problem, and I still don't know
what's wrong with just fixing the docs...
On Fri, Nov 13, 2020 at 11:31 AM Craig Ringer <craig.ringer@enterprisedb.com>
wrote:
Can anyone tell me why the solution I proposed is not acceptable, and why
we have to invent a different one instead? The website redirect is good
and all, but doesn't really solve the problem, and I still don't know
what's wrong with just fixing the docs...
Also, while I'm at it, note that a search on common search engines for
"postgres standby" takes you to (an old version of) the hot standby docs.
Follow the link to the current docs. Then try to work out from there what
exactly makes a server in "archive recovery" or "standby mode".
https://www.postgresql.org/docs/current/hot-standby.html
We need some <link ....> terms on "archive recovery" and "standby mode"
there, and probably other places.
I have a draft patch that adds them and various related index
cross-referencing in my tree to submit after the recovery.conf docs patch.
Let me know if you think that might be worthwhile, 'cos I won't invest time
in it if it's going to get reflexively blocked too.
On Fri, Nov 13, 2020 at 11:31:24AM +0800, Craig Ringer wrote:
Can anyone tell me why the solution I proposed is not acceptable, and why we
have to invent a different one instead? The website� redirect is good and all,
but doesn't really solve the problem, and I still don't know what's wrong with
just fixing the docs...
Because at a certain point the number of _old_ names in the docs
obscures exactly how to operate the current software. We have tried
keeping stuff around, and we are very bad at removing stuff.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
On Thu, 12 Nov 2020 at 22:31, Craig Ringer <craig.ringer@enterprisedb.com>
wrote:
I maintain that simply vanishing terms from the docs without any sort of
explanation is a user-hostile action that we should fix and stop doing If
we had something in the docs and we remove it, it's not unduly burdensome
to have some index entries that point to the replacement/renamed terms, and
a short appendix entry explaining what happened.
This sounds very reasonable to me. I would add that while I am by no means
an expert in Postgres, although I do know a few things, I will state that
it is my professional opinion as a Web person that pages should not simply
disappear from formal documentation without some sort of indication of what
happened. There are lots of ways to accomplish an indication but for
https://www.postgresql.org/docs/current/recovery-config.html or other pages
to just disappear is definitely wrong.
On Fri, Nov 13, 2020 at 11:37:16AM +0800, Craig Ringer wrote:
I have a draft patch that adds them and various related index cross-referencing
in my tree to submit after the recovery.conf docs patch. Let me know if you
think that might be worthwhile, 'cos I won't invest time in it if it's going to
get reflexively blocked too.
So you are saying you don't think you are getting sufficient thought
into your proposal, and getting just a reflex? Just because we don't
agree with you don't mean we didn't think about it. In fact, we have
thought about it a lot, which is evident from the URL I sent you
already.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
On Thu, 12 Nov 2020 at 22:40, Bruce Momjian <bruce@momjian.us> wrote:
Because at a certain point the number of _old_ names in the docs
obscures exactly how to operate the current software. We have tried
keeping stuff around, and we are very bad at removing stuff.
This is a good point, but does not attempt to explain why pages should
disappear entirely from /docs/current/. As I said in my previous comment,
there are lots of ways of doing this right. For example, we could have
pages that would disappear instead be replaced by a short page that
explains the page is removed and points to the current documentation of the
equivalent or replacement features; these hypothetical "useful 404" (or,
more correctly, "useful 410") pages don't even necessarily have to be
listed in the table of contents. In fact, serving them with a 410 HTTP
status code would be a reasonable thing to do.
On Thu, Nov 12, 2020 at 10:41:49PM -0500, Bruce Momjian wrote:
On Fri, Nov 13, 2020 at 11:37:16AM +0800, Craig Ringer wrote:
I have a draft patch that adds them and various related index cross-referencing
in my tree to submit after the recovery.conf docs patch. Let me know if you
think that might be worthwhile, 'cos I won't invest time in it if it's going to
get reflexively blocked too.So you are saying you don't think you are getting sufficient thought
into your proposal, and getting just a reflex? Just because we don't
agree with you don't mean we didn't think about it. In fact, we have
thought about it a lot, which is evident from the URL I sent you
already.
What would be interesting, I think you were suggesting this, is a
separate doc chapter that had a list of all the renames, what version
they were renamed in, and a link from their to the new name in the docs.
This could be easily created by reading the old release notes. Anyone
looking for old names would automatically be sent to that page in the
docs. This would give us a definitive list, and make the list out of
the main flow of the docs.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
On Fri, Nov 13, 2020 at 11:50 AM Bruce Momjian <bruce@momjian.us> wrote:
So you are saying you don't think you are getting sufficient thought
into your proposal, and getting just a reflex? Just because we don't
agree with you don't mean we didn't think about it. In fact, we have
thought about it a lot, which is evident from the URL I sent you
already.
I am mostly trying to say that I don't think the issues I raised were
actually addressed in the proposed alternatives. I put in a fair bit of
effort to clearly set out the problem that this is meant to solve, and was
frustrated to perceive the response as "yeah, nah, lets just do this other
thing that only addresses one part of the original issue." It wasn't clear
why my proposal appeared to be being rejected. Perhaps I didn't fully grasp
the context of the linked discussion.
Please review the docs on standbys with a "new user" hat on. It's confusing
( though the new front-matter and definitions in the HA chapter help) even
without upgrade considerations. See how long it takes you to determine the
answer to the question "what exactly puts a server into 'standby mode' " ?
This proposal was intended to address one part of that, stemming directly
from my own challenges with the docs when I as an experienced PostgreSQL
user and contributor went to adapt some tests to Pg 12 and 13. I knew we'd
removed recovery.conf, but for the life of me I couldn't remember how to
put the server in standby mode in 12 or 13 at the time (I've been working
with 11 too much lately)... and it took ages to actually find that in the
docs.
I can be pretty dense sometimes, but if it sent me for a loop it's going to
confuse others a great deal. Two things that would've helped me would've
been some cross references to the old configuration terms, and a
non-vanishing documentation URL for newer versions. Hence this proposal.
What would be interesting, I think you were suggesting this, is a
separate doc chapter that had a list of all the renames, what version
they were renamed in, and a link from their to the new name in the docs.
Right, that is exactly what I am suggesting we add, as an appendix so it's
way out of the way of the main flow of the docs. Per the original patch and
the illustrative screenshots. I called it something like "removed and
renamed features and settings" or something in the proposed patch.
Alternatives would be welcomed, I don't like the name much.
This could be easily created by reading the old release notes. Anyone
looking for old names would automatically be sent to that page in the
docs. This would give us a definitive list, and make the list out of
the main flow of the docs.
Exactly. Plus a few <indexterm>s where appropriate. That's pretty much all
I'm after.
On Fri, Nov 13, 2020 at 01:27:34PM +0800, Craig Ringer wrote:
On Fri, Nov 13, 2020 at 11:50 AM Bruce Momjian <bruce@momjian.us> wrote:
�So you are saying you don't think you are getting sufficient thought
into your proposal, and getting just a reflex?� Just because we don't
agree with you don't mean we didn't think about it.� In fact, we have
thought about it a lot, which is evident from the URL I sent you
already.I am mostly trying to say that I don't think the issues I raised were actually
addressed in the proposed alternatives. I put in a fair bit of effort to
clearly set out the problem that this is meant to solve, and was frustrated to
perceive the response as "yeah, nah, lets just do this other thing that only
addresses one part of the original issue." It wasn't clear why my proposal
appeared to be being rejected. Perhaps I didn't fully grasp the context of the
linked discussion.
I think the big problem, and I have seen this repeatedly, is showing up
with a patch without discussing whether people actually want the
feature. I know it is a doc issue, but our TODO list has the order as:
Desirability -> Design -> Implement -> Test -> Review -> Commit
and there is a reason for that. When you appear with a patch, you are
already far down the steps, and you have to back up to explain why it is
useful.
Clearly we have need for documenting these renamings somewhere. We were
going to go with a simple URL redirect and a "tip" for
default/pre-installed roles, but I like the idea of doing something more
wholistic that covers all of our recent renaming cases. Let's get
buy-in from that, and then someone can work on a patch.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
On Fri, Nov 13, 2020 at 10:42 AM Bruce Momjian <bruce@momjian.us> wrote:
I think the big problem, and I have seen this repeatedly, is showing up
with a patch without discussing whether people actually want the
feature. I know it is a doc issue, but our TODO list has the order as:Desirability -> Design -> Implement -> Test -> Review -> Commit
and there is a reason for that. When you appear with a patch, you are
already far down the steps, and you have to back up to explain why it is
useful.
That process is designed to prevent people from being exposed to wasted
effort and hard feelings. The choice to follow it individually, instead of
collectively, doesn't diminish the value of the end result.
I generally agree with Craig's proposed solution here. It doesn't add any
cognitive load to new users as they will not see the obsolete features
appendix in the normal course of their reading.
To the particular point regarding renaming features - this situation is not
an instance of a rename but rather a feature removal. To blindly apply the
reasoning and decision made for renaming to removal is not reasonable.
From that observation (and the commentary below) extends the conclusion
that this appendix shouldn't include renaming.
On the point of renaming, my suggestion would be to have the documentation
directory provide a file of all renaming for which redirects should be
performed. pgweb would source that file and actually establish the
redirects on the main website. Comments in the file can describe to a
curious user why the name change was needed. Though that honestly seems a
bit overkill; for rename, the content as a whole still exists and a comment
therein can talk about the renaming. Users of the public website would
still get the benefit of redirects, and there isn't any practical reason
for people building documentation from source to want to establish such
redirects even if they were provided the data in the form of the
aforementioned file.
I believe there is probably room for more discussion regarding the value of
providing a limited view of history in the publicly facing documentation
but that seems outside the scope of this patch.
David J.
On Sun, Nov 15, 2020 at 1:49 PM David G. Johnston <
david.g.johnston@gmail.com> wrote:
On Fri, Nov 13, 2020 at 10:42 AM Bruce Momjian <bruce@momjian.us> wrote:
I think the big problem, and I have seen this repeatedly, is showing up
with a patch without discussing whether people actually want the
feature. I know it is a doc issue, but our TODO list has the order as:Desirability -> Design -> Implement -> Test -> Review -> Commit
and there is a reason for that. When you appear with a patch, you are
already far down the steps, and you have to back up to explain why it is
useful.That process is designed to prevent people from being exposed to wasted
effort and hard feelings. The choice to follow it individually, instead of
collectively, doesn't diminish the value of the end result.
Frankly, it's also kind of a catch-22. Because often proposals for changes
or discussion get ignored until there's a patch, or the response is along
the lines of "show us a patch so we can try it and get a solid idea of what
this will do."
For major engineering changes, yes, discuss first. For small stuff, if you
don't want to get ignored, open with a patch.
On the point of renaming, my suggestion would be to have the documentation
directory provide a file of all renaming for which redirects should be
performed. pgweb would source that file and actually establish the
redirects on the main website. Comments in the file can describe to a
curious user why the name change was needed. Though that honestly seems a
bit overkill; for rename, the content as a whole still exists and a comment
therein can talk about the renaming. Users of the public website would
still get the benefit of redirects, and there isn't any practical reason
for people building documentation from source to want to establish such
redirects even if they were provided the data in the form of the
aforementioned file.
Agreed, there's no need to keep heading redirects in the source-built docs.
So if we're happy to maintain that on the website, in a way that makes
/current/ links work *and* following links from a /11/ docs page that has
vanished in pg12 to the right new place via the version navigation links,
that's sufficient for topic-heading renames.
We should, however, carry information about removals and renames in the
source-built docs to the extent that we have appropriate "see also" index
entries and useful information somewhere in the docs for people who are
upgrading. It just doesn't have to retain the same subject heading.
On Sat, Nov 14, 2020 at 1:42 AM Bruce Momjian <bruce@momjian.us> wrote:
Clearly we have need for documenting these renamings somewhere. We were
going to go with a simple URL redirect and a "tip" for
default/pre-installed roles, but I like the idea of doing something more
wholistic that covers all of our recent renaming cases. Let's get
buy-in from that, and then someone can work on a patch.
Is there anything further I can do to address this specific documentation
issue?
Can I get you to consider the user experience arising from the current docs
- try using the docs to find out how to set up a standby?
I'm not prepared to expand the scope of this to do a major review of all
past renamings and changes without a very clear agreement about how that
should be implemented in the docs and how that will address all the
relevant UX issues - vanishing terms from indexes and docs without
x-refs/see-alsos, vanishing URLs endpoints for public links, vanishing
next-version links in www docs.
I didn't raise this for discussion before I submitted a patch because I
thought it was such an obvious no-brainer that a simple patch to address an
obviously confusing aspect of the docs after the recovery.conf removal
would be uncontroversial. Anyway, as I've noted, these things often get
ignored until there is a patch to argue about.
Can we please just address this docs issue? If you don't like my solution
can you please supply a patch that you feel addresses the problem? Or
clearly state that you don't think there is a problem, and do so in a way
that actually addresses the specific points I have raised about what's
wrong with the status quo?
Greetings,
* Craig Ringer (craig.ringer@enterprisedb.com) wrote:
On Sat, Nov 14, 2020 at 1:42 AM Bruce Momjian <bruce@momjian.us> wrote:
Clearly we have need for documenting these renamings somewhere. We were
going to go with a simple URL redirect and a "tip" for
default/pre-installed roles, but I like the idea of doing something more
wholistic that covers all of our recent renaming cases. Let's get
buy-in from that, and then someone can work on a patch.Is there anything further I can do to address this specific documentation
issue?Can I get you to consider the user experience arising from the current docs
- try using the docs to find out how to set up a standby?
For my 2c, at least, I'm in favor of making some kind of change here to
make things better for users. I tried to figure out a way using the
features we have easily available in pgweb, but I tend to agree with
Craig that those just aren't enough for the more recent set of changes
that we've made.
I'm not prepared to expand the scope of this to do a major review of all
past renamings and changes without a very clear agreement about how that
should be implemented in the docs and how that will address all the
relevant UX issues - vanishing terms from indexes and docs without
x-refs/see-alsos, vanishing URLs endpoints for public links, vanishing
next-version links in www docs.
The past renamings haven't really been as much of an issue since the
redirects and such, imv anyway, have been sufficient to deal with them.
Can we please just address this docs issue? If you don't like my solution
can you please supply a patch that you feel addresses the problem? Or
clearly state that you don't think there is a problem, and do so in a way
that actually addresses the specific points I have raised about what's
wrong with the status quo?
While I understand not wanting to go back through and check for all
renamings, it seems like we should probably at least list out the ones
we know about pretty easily, if we're going to create a new section
specifically for those cases..? Or do we think the current approach
works well enough for those other cases but just not for this one?
Think I listed this elsewhere but not seeing it on the thread so I'll
include it here anyway. These are the current doc aliases:
catalog-pg-replication-slots.html <-> view-pg-replication-slots.html
pgxlogdump.html <-> pgwaldump.html
app-pgresetxlog.html <-> app-pgresetwal.html
legalnotice.html <-> LEGALNOTICE.html
app-pgreceivexlog.html <-> app-pgreceivewal.html
As relates to the specific patch, I don't think the comments line up
quite right (we can prevent a 404 from happening through other means,
but the point of the patch is really to give a deeper explanation of
what happened). Also- wrt pg_basebackup, isn't that expected to support
older versions, and so we should document the behavior against older
versions..?
Thanks,
Stephen
On Mon, Nov 30, 2020 at 10:11:04AM +0800, Craig Ringer wrote:
Can we please just address this docs issue? If you don't like my solution can
you please supply a patch that you feel addresses the problem? Or clearly state
that you don't think there is a problem, and do so in a way that actually
addresses the specific points I have raised about what's wrong with the status
quo?
If we know there are X problems, and we fix one of them one way, then
later fix the rest another way, we have to undo the first fix. If you
don't want to fix all X, then let's wait until someone does want to fix
them all.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
On Mon, Nov 30, 2020 at 11:25 AM Bruce Momjian <bruce@momjian.us> wrote:
On Mon, Nov 30, 2020 at 10:11:04AM +0800, Craig Ringer wrote:
Can we please just address this docs issue? If you don't like my
solution can
you please supply a patch that you feel addresses the problem? Or
clearly state
that you don't think there is a problem, and do so in a way that actually
addresses the specific points I have raised about what's wrong with thestatus
quo?
If we know there are X problems, and we fix one of them one way, then
later fix the rest another way, we have to undo the first fix. If you
don't want to fix all X, then let's wait until someone does want to fix
them all.
IMO there is only the original problem with an acceptable solution
presented that can be committed without downside. If that has to be undone
because someone else in the future decides on a different solution that
happens to touch this too, fine, it can be changed again.
David J.
On Mon, Nov 30, 2020 at 11:31:35AM -0700, David G. Johnston wrote:
On Mon, Nov 30, 2020 at 11:25 AM Bruce Momjian <bruce@momjian.us> wrote:
On Mon, Nov 30, 2020 at 10:11:04AM +0800, Craig Ringer wrote:
Can we please just address this docs issue? If you don't like my solution
can
you please supply a patch that you feel addresses the problem? Or clearly
state
that you don't think there is a problem, and do so in a way that actually
addresses the specific points I have raised about what's wrong with thestatus
quo?
If we know there are X problems, and we fix one of them one way, then
later fix the rest another way, we have to undo the first fix.� If you
don't want to fix all X, then let's wait until someone does want to fix
them all.IMO there is only the original problem with an acceptable solution presented
that can be committed without downside.� If that has to be undone because
someone else in the future decides on a different solution that happens to
touch this too, fine, it can be changed again.
The downside is you end up with X-1 dummy sections just to allow for
references to old syntax, and you then have to find them all and remove
them when you implement the proper solution. I have no intention of
applying such an X-1 fix.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
On Mon, Nov 30, 2020 at 11:42 AM Bruce Momjian <bruce@momjian.us> wrote:
The downside is you end up with X-1 dummy sections just to allow for
references to old syntax, and you then have to find them all and remove
them when you implement the proper solution. I have no intention of
applying such an X-1 fix.
X = 2; seems like a strong objection for such a minor issue. The status
quo seems worse than that.
David J.
Greetings,
* David G. Johnston (david.g.johnston@gmail.com) wrote:
On Mon, Nov 30, 2020 at 11:42 AM Bruce Momjian <bruce@momjian.us> wrote:
The downside is you end up with X-1 dummy sections just to allow for
references to old syntax, and you then have to find them all and remove
them when you implement the proper solution. I have no intention of
applying such an X-1 fix.X = 2; seems like a strong objection for such a minor issue. The status
quo seems worse than that.
I've been thinking about this and I think I'm on Craig and David's side-
having something cleaner, and clearer, than just http redirects and such
would be good for these cases and I don't think we are going to end up
with so many of them that it ends up becoming an issue.
Thanks,
Stephen
On Wed, Dec 2, 2020 at 02:47:13PM -0500, Stephen Frost wrote:
Greetings,
* David G. Johnston (david.g.johnston@gmail.com) wrote:
On Mon, Nov 30, 2020 at 11:42 AM Bruce Momjian <bruce@momjian.us> wrote:
The downside is you end up with X-1 dummy sections just to allow for
references to old syntax, and you then have to find them all and remove
them when you implement the proper solution. I have no intention of
applying such an X-1 fix.X = 2; seems like a strong objection for such a minor issue. The status
quo seems worse than that.I've been thinking about this and I think I'm on Craig and David's side-
having something cleaner, and clearer, than just http redirects and such
would be good for these cases and I don't think we are going to end up
with so many of them that it ends up becoming an issue.
We were not going to use just redirects --- we were going to create a
page that had all the renames listed, with links to the new names.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
Greetings,
* Bruce Momjian (bruce@momjian.us) wrote:
On Wed, Dec 2, 2020 at 02:47:13PM -0500, Stephen Frost wrote:
* David G. Johnston (david.g.johnston@gmail.com) wrote:
On Mon, Nov 30, 2020 at 11:42 AM Bruce Momjian <bruce@momjian.us> wrote:
The downside is you end up with X-1 dummy sections just to allow for
references to old syntax, and you then have to find them all and remove
them when you implement the proper solution. I have no intention of
applying such an X-1 fix.X = 2; seems like a strong objection for such a minor issue. The status
quo seems worse than that.I've been thinking about this and I think I'm on Craig and David's side-
having something cleaner, and clearer, than just http redirects and such
would be good for these cases and I don't think we are going to end up
with so many of them that it ends up becoming an issue.We were not going to use just redirects --- we were going to create a
page that had all the renames listed, with links to the new names.
Maybe I'm the one who is confused here, but I thought there was
objection to adding a new section/page which covers these topics (which
is what Craig's original patch does)...? If there isn't an objection to
that then it seems like we should move forward with it.
If I'm following correctly, maybe there was some idea that we should
have more things added to this section than just the recovery.conf bits,
and perhaps we should, but that could certainly be done later. To be
clear though, I don't think we need to do this in all cases- the
existing flow for pg_xlogdump -> pg_waldump works pretty well. Maybe we
add in a note here too if someone wants to but I don't think it's
strictly necessary for the 'simple' rename cases.
I also feel like that could be done once the section gets added, if
someone wants to.
Was there something else that I'm missing here in terms of what the
concern is regarding Craig's patch..?
Thanks,
Stephen
On Wed, Dec 2, 2020 at 05:57:01PM -0500, Stephen Frost wrote:
* Bruce Momjian (bruce@momjian.us) wrote:
We were not going to use just redirects --- we were going to create a
page that had all the renames listed, with links to the new names.Maybe I'm the one who is confused here, but I thought there was
objection to adding a new section/page which covers these topics (which
is what Craig's original patch does)...? If there isn't an objection to
that then it seems like we should move forward with it.If I'm following correctly, maybe there was some idea that we should
have more things added to this section than just the recovery.conf bits,
and perhaps we should, but that could certainly be done later. To be
clear though, I don't think we need to do this in all cases- the
existing flow for pg_xlogdump -> pg_waldump works pretty well. Maybe we
add in a note here too if someone wants to but I don't think it's
strictly necessary for the 'simple' rename cases.I also feel like that could be done once the section gets added, if
someone wants to.Was there something else that I'm missing here in terms of what the
concern is regarding Craig's patch..?
I think the ideal solution is to create a section for all the rename
cases and do all the redirects to that page. The page would list the
old and new name for each item, and would link to the section for each
new item.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
On Wed, Dec 2, 2020 at 5:26 PM Bruce Momjian <bruce@momjian.us> wrote:
I think the ideal solution is to create a section for all the rename
cases and do all the redirects to that page. The page would list the
old and new name for each item, and would link to the section for each
new item.
Nothing prevents us from doing that for simple renames. For me, this
situation is not a simple rename and the proposed solution is appropriate
for what it is - changing the implementation details of an existing
feature. We can do both - though the simple rename page doesn't seem
particularly appealing at first glance.
David J.
On Wed, 2 Dec 2020 at 19:33, David G. Johnston <david.g.johnston@gmail.com>
wrote:
On Wed, Dec 2, 2020 at 5:26 PM Bruce Momjian <bruce@momjian.us> wrote:
I think the ideal solution is to create a section for all the rename
cases and do all the redirects to that page. The page would list the
old and new name for each item, and would link to the section for each
new item.Nothing prevents us from doing that for simple renames. For me, this
situation is not a simple rename and the proposed solution is appropriate
for what it is - changing the implementation details of an existing
feature. We can do both - though the simple rename page doesn't seem
particularly appealing at first glance.
I for one do not like following a bookmark or link and then being
redirected to a generic page that doesn't relate to the specific link I was
following. What is being proposed here is not as bad as the usual, where
all the old links simply turn into redirects to the homepage, but it's
still disorienting. I would much rather each removed page be moved to an
appendix (without renaming) and edited to briefly explain what happened to
the page and provide links to the appropriate up-to-date page or pages.
On Wed, Dec 2, 2020 at 08:07:47PM -0500, Isaac Morland wrote:
On Wed, 2 Dec 2020 at 19:33, David G. Johnston <david.g.johnston@gmail.com>
wrote:On Wed, Dec 2, 2020 at 5:26 PM Bruce Momjian <bruce@momjian.us> wrote:
I think the ideal solution is to create a section for all the rename
cases and do all the redirects to that page.� The page would list the
old and new name for each item, and would link to the section for each
new item.Nothing prevents us from doing that for simple renames.� For me, this
situation is not a simple rename and the proposed solution is appropriate
for what it is - changing the implementation�details of an existing
feature.� We can do both - though the simple rename page doesn't seem
particularly appealing at first glance.I for one do not like following a bookmark or link and then being redirected to
a generic page that doesn't relate to the specific link I was following. What
is being proposed here is not as bad as the usual, where all the old links
simply turn into redirects to the homepage, but it's still disorienting. I
would much rather each removed page be moved to an appendix (without renaming)
and edited to briefly explain what happened to the page and provide links to
the appropriate up-to-date page or pages.
Yes, that is pretty much the same thing I was suggesting, except that
each rename has its own _original_ URL link, which I think is also
acceptable. My desire is for these items to all exist in one place, and
an appendix of them seems fine.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
Greetings,
* Bruce Momjian (bruce@momjian.us) wrote:
On Wed, Dec 2, 2020 at 08:07:47PM -0500, Isaac Morland wrote:
On Wed, 2 Dec 2020 at 19:33, David G. Johnston <david.g.johnston@gmail.com>
wrote:On Wed, Dec 2, 2020 at 5:26 PM Bruce Momjian <bruce@momjian.us> wrote:
I think the ideal solution is to create a section for all the rename
cases and do all the redirects to that page. The page would list the
old and new name for each item, and would link to the section for each
new item.Nothing prevents us from doing that for simple renames. For me, this
situation is not a simple rename and the proposed solution is appropriate
for what it is - changing the implementation details of an existing
feature. We can do both - though the simple rename page doesn't seem
particularly appealing at first glance.I for one do not like following a bookmark or link and then being redirected to
a generic page that doesn't relate to the specific link I was following. What
is being proposed here is not as bad as the usual, where all the old links
simply turn into redirects to the homepage, but it's still disorienting. I
would much rather each removed page be moved to an appendix (without renaming)
and edited to briefly explain what happened to the page and provide links to
the appropriate up-to-date page or pages.Yes, that is pretty much the same thing I was suggesting, except that
each rename has its own _original_ URL link, which I think is also
acceptable. My desire is for these items to all exist in one place, and
an appendix of them seems fine.
Alright, so, to try and move this forward I'll list out (again) the
renames that we have in pgweb:
catalog-pg-replication-slots.html <-> view-pg-replication-slots.html
pgxlogdump.html <-> pgwaldump.html
app-pgresetxlog.html <-> app-pgresetwal.html
app-pgreceivexlog.html <-> app-pgreceivewal.html
(excluding the 'legal notice' one)
Bruce, are you saying that we need to take Craig's patch and then add to
it entries for all of the above, effectively removing the need for the
web page aliases and redirects? If that was done, would that be
sufficient to get this committed? Are there other things that people
can think of off-hand that we should include, I think Craig might have
mentioned something else earlier on..? I don't think we should require
that someone troll through everything that ever existed, just to be
clear, as we can always add to this later if other things come up. If
that's the expectation though, then someone needs to say so, in which
case I'll assume it's status quo unless/until someone steps up to do
that.
Obviously, I'd then have to adjust the patch that I proposed for default
roles, or move forward with it as-is, depending on what we end up doing
here. I dislike what feels like a state of limbo for this right now
though.
Thanks,
Stephen
On Fri, Dec 4, 2020 at 12:00 PM Stephen Frost <sfrost@snowman.net> wrote:
Obviously, I'd then have to adjust the patch that I proposed for default
roles, or move forward with it as-is, depending on what we end up doing
here. I dislike what feels like a state of limbo for this right now
though.
We have a committer + 1 in favor of status quo - or at least requiring that
a non-existing solution be created to move things forward. (Bruce, Daniel)
We have a committer + 3 that seem to agree that the proposed patch is
acceptable as presented. (Stephen, Craig, Isaac, David J.)
Anyone wish to update the above observation?
Stephen, are you will to commit this with the support of the community
members who have spoken up here?
David J.
Greetings,
* David G. Johnston (david.g.johnston@gmail.com) wrote:
On Fri, Dec 4, 2020 at 12:00 PM Stephen Frost <sfrost@snowman.net> wrote:
Obviously, I'd then have to adjust the patch that I proposed for default
roles, or move forward with it as-is, depending on what we end up doing
here. I dislike what feels like a state of limbo for this right now
though.We have a committer + 1 in favor of status quo - or at least requiring that
a non-existing solution be created to move things forward. (Bruce, Daniel)
We have a committer + 3 that seem to agree that the proposed patch is
acceptable as presented. (Stephen, Craig, Isaac, David J.)
Anyone wish to update the above observation?Stephen, are you will to commit this with the support of the community
members who have spoken up here?
What I was hoping to achieve is consensus on a reasonably well bounded
solution. I'm not going to push something that others are objecting to,
but if we can agree on the idea and what's needed for it to be
acceptable then I'm willing to work towards that, provided it doesn't
require going back 10 versions and looking at every single change.
Thanks,
Stephen
On Fri, Dec 4, 2020 at 02:00:23PM -0500, Stephen Frost wrote:
* Bruce Momjian (bruce@momjian.us) wrote:
Yes, that is pretty much the same thing I was suggesting, except that
each rename has its own _original_ URL link, which I think is also
acceptable. My desire is for these items to all exist in one place, and
an appendix of them seems fine.Alright, so, to try and move this forward I'll list out (again) the
renames that we have in pgweb:catalog-pg-replication-slots.html <-> view-pg-replication-slots.html
pgxlogdump.html <-> pgwaldump.html
app-pgresetxlog.html <-> app-pgresetwal.html
app-pgreceivexlog.html <-> app-pgreceivewal.html(excluding the 'legal notice' one)
Bruce, are you saying that we need to take Craig's patch and then add to
it entries for all of the above, effectively removing the need for the
web page aliases and redirects? If that was done, would that be
Yes, I think putting the compatibility section headings in our main
documentation flow will make it too hard to read and cause unnecessary
complexity, but if we have a separate section for them, adding the
section headings seems fine. This way, we don't have to add a redirect
every time we add a new entry.
sufficient to get this committed? Are there other things that people
can think of off-hand that we should include, I think Craig might have
mentioned something else earlier on..? I don't think we should require
that someone troll through everything that ever existed, just to be
clear, as we can always add to this later if other things come up. If
that's the expectation though, then someone needs to say so, in which
case I'll assume it's status quo unless/until someone steps up to do
that.
Agreed. I just wanted something that could scale going forward, and be
easily identified as compatibility, so maybe one day we can remove them.
However, if they are in a separate section, we might never do that.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
Greetings,
* Bruce Momjian (bruce@momjian.us) wrote:
On Fri, Dec 4, 2020 at 02:00:23PM -0500, Stephen Frost wrote:
* Bruce Momjian (bruce@momjian.us) wrote:
Yes, that is pretty much the same thing I was suggesting, except that
each rename has its own _original_ URL link, which I think is also
acceptable. My desire is for these items to all exist in one place, and
an appendix of them seems fine.Alright, so, to try and move this forward I'll list out (again) the
renames that we have in pgweb:catalog-pg-replication-slots.html <-> view-pg-replication-slots.html
pgxlogdump.html <-> pgwaldump.html
app-pgresetxlog.html <-> app-pgresetwal.html
app-pgreceivexlog.html <-> app-pgreceivewal.html(excluding the 'legal notice' one)
Bruce, are you saying that we need to take Craig's patch and then add to
it entries for all of the above, effectively removing the need for the
web page aliases and redirects? If that was done, would that beYes, I think putting the compatibility section headings in our main
documentation flow will make it too hard to read and cause unnecessary
complexity, but if we have a separate section for them, adding the
section headings seems fine. This way, we don't have to add a redirect
every time we add a new entry.
Alright, how does this look? The new entries are all under the
'obsolete' section to keep it out of the main line, but should work to
'fix' the links that currently 404 and provide a bit of a 'softer'
landing for the other cases that currently just forcibly redirect using
the website doc alias capability.
I ended up not actually doing this for the catalog -> view change of
pg_replication_slots simply because I don't really think folks will
misunderstand or be confused by that redirect since it's still the same
relation. If others disagree though, we could certainly change that
too.
sufficient to get this committed? Are there other things that people
can think of off-hand that we should include, I think Craig might have
mentioned something else earlier on..? I don't think we should require
that someone troll through everything that ever existed, just to be
clear, as we can always add to this later if other things come up. If
that's the expectation though, then someone needs to say so, in which
case I'll assume it's status quo unless/until someone steps up to do
that.Agreed. I just wanted something that could scale going forward, and be
easily identified as compatibility, so maybe one day we can remove them.
However, if they are in a separate section, we might never do that.
Sure, seems like this approach addresses that.
If we have agreement from folks on this then I'll commit it and then
rework the change from default roles to predefined roles to use this
approach and then we can move forward with that too.
Thanks,
Stephen
Attachments:
doc-rename-cleanup.patchtext/x-diff; charset=us-asciiDownload
From 978f52f1f33fcde55db9fd8ff3fb60897cdf019c Mon Sep 17 00:00:00 2001
From: Stephen Frost <sfrost@snowman.net>
Date: Wed, 13 Jan 2021 13:31:55 -0500
Subject: [PATCH] Introduce obsolete appendix to link old terms to new docs
Add a new docs section for obsolete topics. In it, add in sections for
recovery.conf, pg_receivexlog, pg_resetxlog, and pg_xlogdump, with
appropriate explanations of what's happened and where to find the
updated documentation for each.
This way when someone running PostgreSQL 12+ searches for
"recovery.conf" or "pg_xlogdump" or similar and finds the /11/ (or
/9.6/) documentation for it, the website docs will have a "latest"
link that explains where it went as well as specific language that
talks about what happened.
This also helps people following /current/ web links from articles,
blogs, etc, who would currently get a 404 for some of these cases or
just a forced redirect without any explanation in other cases.
Appropriate index terms are added to direct searchers to the right
place too.
Author: Craig Ringer, Stephen Frost
Discussion: https://postgr.es/m/CAGRY4nyA=jmBNa4LVwgGO1GyO-RnFmfkesddpT_uO+3=mot8DA@mail.gmail.com
Reviewed-By: Bruce Momjian
---
.../sgml/appendix-obsolete-pgreceivexlog.sgml | 26 ++++++++
.../sgml/appendix-obsolete-pgresetxlog.sgml | 26 ++++++++
.../sgml/appendix-obsolete-pgxlogdump.sgml | 26 ++++++++
.../appendix-obsolete-recovery-config.sgml | 61 +++++++++++++++++++
doc/src/sgml/appendix-obsolete.sgml | 22 +++++++
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, 189 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..72989ce06e
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml
@@ -0,0 +1,26 @@
+<!-- doc/src/sgml/obsolete-pgxlogdump.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="app-pgreceivexlog" xreflabel="pg_receivexlog">
+ <title>The <filename>pg_receivexlog</filename> command</title>
+
+ <indexterm>
+ <primary>obsolete</primary>
+ <secondary>pg_receivexlog</secondary>
+ </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..d79be8eb44
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml
@@ -0,0 +1,26 @@
+<!-- doc/src/sgml/obsolete-pgresetxlog.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="app-pgresetxlog" xreflabel="pg_resetxlog">
+ <title>The <filename>pg_resetxlog</filename> command</title>
+
+ <indexterm>
+ <primary>obsolete</primary>
+ <secondary>pg_resetxlog</secondary>
+ </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..1deb1d31c4
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml
@@ -0,0 +1,26 @@
+<!-- doc/src/sgml/obsolete-pgxlogdump.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="pgxlogdump" xreflabel="pg_xlogdump">
+ <title>The <filename>pg_xlogdump</filename> command</title>
+
+ <indexterm>
+ <primary>obsolete</primary>
+ <secondary>pg_xlogdump</secondary>
+ </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..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..ace7ca9d3b
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete.sgml
@@ -0,0 +1,22 @@
+<!-- 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;
+ &obsolete-pgxlogdump;
+ &obsolete-pgresetxlog;
+ &obsolete-pgreceivexlog;
+
+</appendix>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 82864bbb24..6c4c0d202b 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -4259,7 +4259,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..03f2065cc4 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -185,3 +185,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 efc382cb8d..c948aa9e7c 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
@@ -2084,7 +2093,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 5754ad5aa6..908597c548 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.25.1
On Thu, 14 Jan 2021 at 03:44, Stephen Frost <sfrost@snowman.net> wrote:
Alright, how does this look? The new entries are all under the
'obsolete' section to keep it out of the main line, but should work to
'fix' the links that currently 404 and provide a bit of a 'softer'
landing for the other cases that currently just forcibly redirect using
the website doc alias capability.
Thanks for expanding the change to other high profile obsoleted or renamed
features and tools.
One minor point. I'm not sure this is quite the best way to spell the index
entries:
+ <indexterm>
+ <primary>obsolete</primary>
+ <secondary>pg_receivexlog</secondary>
+ </indexterm>as it will produce an index term "obsolete" with a list of various
components under it. While that concentrates them nicely, it means people
won't actually find them if they're using the index alphabetically.
I'd slightly prefer
+ <indexterm>
+ <primary>pg_receivexlog</primary>
+ <seealso>pg_receivewal</secondary>
+ </indexterm>even though that bulks the index up a little, because then people are a bit
more likely to find it.
Your extended and revised patch retains the above style for
+ <indexterm>
+ <primary>trigger_file</primary>
+ <seealso>promote_trigger_file</seealso>
+ </indexterm>
...
+ <indexterm>
+ <primary>standby_mode</primary>
+ <seealso>standby.signal</seealso>
+ </indexterm>so if you intend to change it, that entry needs changing too.
I ended up not actually doing this for the catalog -> view change of
pg_replication_slots simply because I don't really think folks will
misunderstand or be confused by that redirect since it's still the same
relation. If others disagree though, we could certainly change that
too.
I agree with you.
Greetings,
* Craig Ringer (craig.ringer@enterprisedb.com) wrote:
On Thu, 14 Jan 2021 at 03:44, Stephen Frost <sfrost@snowman.net> wrote:
Alright, how does this look? The new entries are all under the
'obsolete' section to keep it out of the main line, but should work to
'fix' the links that currently 404 and provide a bit of a 'softer'
landing for the other cases that currently just forcibly redirect using
the website doc alias capability.Thanks for expanding the change to other high profile obsoleted or renamed
features and tools.
Thanks for taking the time to review it and comment on it!
One minor point. I'm not sure this is quite the best way to spell the index
entries:+ <indexterm> + <primary>obsolete</primary> + <secondary>pg_receivexlog</secondary> + </indexterm>as it will produce an index term "obsolete" with a list of various
components under it. While that concentrates them nicely, it means people
won't actually find them if they're using the index alphabetically.
Ah, yeah, that's definitely a good point and one that I hadn't really
spent much time thinking about.
I'd slightly prefer
+ <indexterm> + <primary>pg_receivexlog</primary> + <seealso>pg_receivewal</secondary> + </indexterm>even though that bulks the index up a little, because then people are a bit
more likely to find it.
Yup, makes sense, updated patch attached which makes that change.
I ended up not actually doing this for the catalog -> view change of
pg_replication_slots simply because I don't really think folks will
misunderstand or be confused by that redirect since it's still the same
relation. If others disagree though, we could certainly change that
too.I agree with you.
Ok, great.
How does the attached look then?
Bruce, did you want to review or comment on this as to if it addresses
your concerns appropriately? Would be great to get this in as there's
the follow-on for default roles.
Thanks!
Stephen
Greetings,
* Stephen Frost (sfrost@snowman.net) wrote:
* Craig Ringer (craig.ringer@enterprisedb.com) wrote:
On Thu, 14 Jan 2021 at 03:44, Stephen Frost <sfrost@snowman.net> wrote:
Alright, how does this look? The new entries are all under the
'obsolete' section to keep it out of the main line, but should work to
'fix' the links that currently 404 and provide a bit of a 'softer'
landing for the other cases that currently just forcibly redirect using
the website doc alias capability.Thanks for expanding the change to other high profile obsoleted or renamed
features and tools.Thanks for taking the time to review it and comment on it!
One minor point. I'm not sure this is quite the best way to spell the index
entries:+ <indexterm> + <primary>obsolete</primary> + <secondary>pg_receivexlog</secondary> + </indexterm>as it will produce an index term "obsolete" with a list of various
components under it. While that concentrates them nicely, it means people
won't actually find them if they're using the index alphabetically.Ah, yeah, that's definitely a good point and one that I hadn't really
spent much time thinking about.I'd slightly prefer
+ <indexterm> + <primary>pg_receivexlog</primary> + <seealso>pg_receivewal</secondary> + </indexterm>even though that bulks the index up a little, because then people are a bit
more likely to find it.Yup, makes sense, updated patch attached which makes that change.
I ended up not actually doing this for the catalog -> view change of
pg_replication_slots simply because I don't really think folks will
misunderstand or be confused by that redirect since it's still the same
relation. If others disagree though, we could certainly change that
too.I agree with you.
Ok, great.
How does the attached look then?
Bruce, did you want to review or comment on this as to if it addresses
your concerns appropriately? Would be great to get this in as there's
the follow-on for default roles.
... really attached now, sorry about that. :)
Thanks,
Stephen
Attachments:
doc-rename-cleanup_v2.patchtext/x-diff; charset=us-asciiDownload
diff --git a/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml
new file mode 100644
index 0000000000..391eb5dcb2
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml
@@ -0,0 +1,26 @@
+<!-- doc/src/sgml/obsolete-pgxlogdump.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="app-pgreceivexlog" xreflabel="pg_receivexlog">
+ <title>The <filename>pg_receivexlog</filename> command</title>
+
+ <indexterm>
+ <primary>pg_receivexlog</primary>
+ <seealso>pg_receivewal</seealso>
+ </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..44452b5627
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml
@@ -0,0 +1,26 @@
+<!-- doc/src/sgml/obsolete-pgresetxlog.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="app-pgresetxlog" xreflabel="pg_resetxlog">
+ <title>The <filename>pg_resetxlog</filename> command</title>
+
+ <indexterm>
+ <primary>pg_resetxlog</primary>
+ <seealso>pg_resetwal</seealso>
+ </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..325316b4e6
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml
@@ -0,0 +1,26 @@
+<!-- doc/src/sgml/obsolete-pgxlogdump.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="pgxlogdump" xreflabel="pg_xlogdump">
+ <title>The <filename>pg_xlogdump</filename> command</title>
+
+ <indexterm>
+ <primary>pg_xlogdump</primary>
+ <seealso>pg_waldump</seealso>
+ </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..3f858e5cb0
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-recovery-config.sgml
@@ -0,0 +1,60 @@
+<!-- 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><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>
+ <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..ace7ca9d3b
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete.sgml
@@ -0,0 +1,22 @@
+<!-- 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;
+ &obsolete-pgxlogdump;
+ &obsolete-pgresetxlog;
+ &obsolete-pgreceivexlog;
+
+</appendix>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 82864bbb24..6c4c0d202b 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -4259,7 +4259,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..03f2065cc4 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -185,3 +185,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 dc263e4106..1733c7c7a1 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
@@ -2084,7 +2093,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 5754ad5aa6..908597c548 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
On Wed, 20 Jan 2021 at 02:45, Stephen Frost <sfrost@snowman.net> wrote:
Greetings,
* Stephen Frost (sfrost@snowman.net) wrote:
* Craig Ringer (craig.ringer@enterprisedb.com) wrote:
On Thu, 14 Jan 2021 at 03:44, Stephen Frost <sfrost@snowman.net>
wrote:
Alright, how does this look? The new entries are all under the
'obsolete' section to keep it out of the main line, but should workto
'fix' the links that currently 404 and provide a bit of a 'softer'
landing for the other cases that currently just forcibly redirectusing
the website doc alias capability.
Thanks for expanding the change to other high profile obsoleted or
renamed
features and tools.
Thanks for taking the time to review it and comment on it!
One minor point. I'm not sure this is quite the best way to spell the
index
entries:
+ <indexterm> + <primary>obsolete</primary> + <secondary>pg_receivexlog</secondary> + </indexterm>as it will produce an index term "obsolete" with a list of various
components under it. While that concentrates them nicely, it meanspeople
won't actually find them if they're using the index alphabetically.
Ah, yeah, that's definitely a good point and one that I hadn't really
spent much time thinking about.I'd slightly prefer
+ <indexterm> + <primary>pg_receivexlog</primary> + <seealso>pg_receivewal</secondary> + </indexterm>even though that bulks the index up a little, because then people are
a bit
more likely to find it.
Yup, makes sense, updated patch attached which makes that change.
I ended up not actually doing this for the catalog -> view change of
pg_replication_slots simply because I don't really think folks will
misunderstand or be confused by that redirect since it's still thesame
relation. If others disagree though, we could certainly change that
too.I agree with you.
Ok, great.
How does the attached look then?
Pretty good to me. Thanks so much for your help and support with this.
Index entries render as e.g.
pg_xlogdump, The pg_xlogdump command
(see also pg_waldump)
wheras with the obsolete subhead they would render as something like:
obsolete, Obsolete or renamed features, settings and files
pg_xlogdump, The pg_xlogdump command
The see also spelling is much easier to find in the index but doesn't make
it as obvious that it's obsoleted/replaced.
A look at the doxygen docs suggest we should use <see> not <seealso> for
these.
A quick
sed -i -e 's/<seealso>/<see>/g' -e 's/<\/seealso>/<\/see>/g'
doc/src/sgml/appendix-obsolete*
causes them to render much better:
pg_receivexlog, The pg_receivexlog command (see pg_receivewal)
It might be worth changing the <title/>s too, so I've done so in the
attached. The terms now render as:
pg_receivexlog, pg_receivexlog renamed to pg_recievewal (see
pg_receivewal)
which is good enough in my opinion. The duplication is messy but an
expected artifact of index generation. I don't see any docbook <indexterm>
attribute that lets you suppress insertion of the <title> of the section
containing the <indexterm>, and it's not worth fiddling to try to eliminate
it with structural hacks.
The attached changes the titles, changes <seealso> to <see>, and also
updates the comments in the obsolete entries SGML docs to specify that the
id must be unchanged + give a recommended index term format.
Attachments:
v3-0001-Add-a-docs-section-for-obsoleted-and-renamed-func.patchtext/x-patch; charset=US-ASCII; name=v3-0001-Add-a-docs-section-for-obsoleted-and-renamed-func.patchDownload
From c11e0f079c07c669abac0f00ae3f1ebdfc18eae7 Mon Sep 17 00:00:00 2001
From: Craig Ringer <craig.ringer@2ndquadrant.com>
Date: Thu, 21 Jan 2021 10:01:29 +0800
Subject: [PATCH v3] 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
---
.../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 82864bbb24..6c4c0d202b 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -4259,7 +4259,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..03f2065cc4 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -185,3 +185,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 dc263e4106..1733c7c7a1 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
@@ -2084,7 +2093,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 5754ad5aa6..908597c548 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.29.2
Greetings,
* Craig Ringer (craig.ringer@enterprisedb.com) wrote:
Pretty good to me. Thanks so much for your help and support with this.
Thanks for helping me move it forward!
Index entries render as e.g.
pg_xlogdump, The pg_xlogdump command
(see also pg_waldump)wheras with the obsolete subhead they would render as something like:
obsolete, Obsolete or renamed features, settings and files
pg_xlogdump, The pg_xlogdump commandThe see also spelling is much easier to find in the index but doesn't make
it as obvious that it's obsoleted/replaced.A look at the doxygen docs suggest we should use <see> not <seealso> for
these.A quick
sed -i -e 's/<seealso>/<see>/g' -e 's/<\/seealso>/<\/see>/g'
doc/src/sgml/appendix-obsolete*causes them to render much better:
pg_receivexlog, The pg_receivexlog command (see pg_receivewal)
It might be worth changing the <title/>s too, so I've done so in the
attached. The terms now render as:pg_receivexlog, pg_receivexlog renamed to pg_recievewal (see
pg_receivewal)which is good enough in my opinion. The duplication is messy but an
expected artifact of index generation. I don't see any docbook <indexterm>
attribute that lets you suppress insertion of the <title> of the section
containing the <indexterm>, and it's not worth fiddling to try to eliminate
it with structural hacks.
Nice, yes, that does look better.
The attached changes the titles, changes <seealso> to <see>, and also
updates the comments in the obsolete entries SGML docs to specify that the
id must be unchanged + give a recommended index term format.
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).
Thanks!
Stephen
Attachments:
v4-0001-Add-a-docs-section-for-obsoleted-and-renamed-func.patchtext/x-diff; charset=us-asciiDownload
From 000cd577d6dbb9d6d6c571e2302657f1252e6a56 Mon Sep 17 00:00:00 2001
From: Stephen Frost <sfrost@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
---
.../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 5679b40dd5..f6ff58c78a 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -4306,7 +4306,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
Greetings,
* Stephen Frost (sfrost@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
Attachments:
doc-rename-cleanup_v4.patchtext/x-diff; charset=us-asciiDownload
From 87e551a82f1bef202e040b3ddd1acc9ffb31bf8a Mon Sep 17 00:00:00 2001
From: Stephen Frost <sfrost@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
doc-rename-cleanup_v4_v10.patchtext/x-diff; charset=us-asciiDownload
From 08021ddc7366091b443d6d07226ca718f87471a8 Mon Sep 17 00:00:00 2001
From: Stephen Frost <sfrost@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
doc-rename-cleanup_v4_v11.patchtext/x-diff; charset=us-asciiDownload
From 1b71bf79d6bc8a0ddac9097636fafd94708fa765 Mon Sep 17 00:00:00 2001
From: Stephen Frost <sfrost@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
doc-rename-cleanup_v4_v12.patchtext/x-diff; charset=us-asciiDownload
From 74a438d99fd10ada87f259d68251f648e98cb03e Mon Sep 17 00:00:00 2001
From: Stephen Frost <sfrost@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
doc-rename-cleanup_v4_v13.patchtext/x-diff; charset=us-asciiDownload
From d155726ac4cea4427bd6b5c67452d4dfdf38dc51 Mon Sep 17 00:00:00 2001
From: Stephen Frost <sfrost@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
On Sun, Mar 28, 2021, at 2:22 PM, Stephen Frost wrote:
Unless there's anything further, will commit these soon.
I briefly looked at this patch and have a few comments.
+<sect1 id="app-pgreceivexlog" xreflabel="pg_receivexlog">
+ <title><command>pg_receivexlog</command> renamed to <command>pg_recievewal</command></title>s/pg_recievewal/pg_receivewal/
+<appendix id="appendix-obsolete">
+ <title>Obsolete or renamed features, settings and files</title>Section titles are capitalized so it should be "Obsolete or Renamed Features,
Settings and Files". I find this section name too descriptive. I didn't follow
this thread but maybe we might use a generic name that is also shorter than it
such as "Incompatible or Obsolete Features".
+ <primary>trigger_file</primary>
+ <see>promote_trigger_file</see>
+ </indexterm>
+ setting has been renamed to
+ <xref linkend="guc-promote-trigger-file"/>
+ </para>There should be a period after the <xref>.
--
Euler Taveira
EDB https://www.enterprisedb.com/
Greetings,
* Euler Taveira (euler@eulerto.com) wrote:
On Sun, Mar 28, 2021, at 2:22 PM, Stephen Frost wrote:
Unless there's anything further, will commit these soon.
I briefly looked at this patch and have a few comments.
+<sect1 id="app-pgreceivexlog" xreflabel="pg_receivexlog"> + <title><command>pg_receivexlog</command> renamed to <command>pg_recievewal</command></title>s/pg_recievewal/pg_receivewal/
Hah! Good catch. Fixed.
+<appendix id="appendix-obsolete"> + <title>Obsolete or renamed features, settings and files</title>Section titles are capitalized so it should be "Obsolete or Renamed Features,
Settings and Files". I find this section name too descriptive. I didn't follow
this thread but maybe we might use a generic name that is also shorter than it
such as "Incompatible or Obsolete Features".
Not sure how others feel, but 'incompatible' doesn't seem quite right to
me- we renamed some things between major versions but they're as
compatible as they were before. Having it be shorter does make sense to
me, so I updated the patch with "Obsolete or Renamed Features" instead.
I also reworded the section underneath a bit to mention renaming and to
include a comment about features, settings, and file names.
+ <primary>trigger_file</primary> + <see>promote_trigger_file</see> + </indexterm> + setting has been renamed to + <xref linkend="guc-promote-trigger-file"/> + </para>There should be a period after the <xref>.
Good catch, fixed.
Updated patches attached.
Thanks!
Stephen
Attachments:
doc-rename-cleanup_v5.patchtext/x-diff; charset=us-asciiDownload
From 26144f5d9d5f340e0b0fabcc1937c571d9567d2e Mon Sep 17 00:00:00 2001
From: Stephen Frost <sfrost@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
Reviewed-by: Euler Taveira
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 | 41 +++++++++++++
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, 199 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..f74d0ae832
--- /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_receivewal</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..77c4289531
--- /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..ffd7d40263
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete.sgml
@@ -0,0 +1,41 @@
+<!-- doc/src/sgml/obsolete.sgml -->
+
+<appendix id="appendix-obsolete">
+ <title>Obsolete or Renamed Features</title>
+
+ <para>
+ Functionality is sometimes removed from PostgreSQL, feature, setting
+ and file names sometimes change, or documentation moves to different
+ places. This section directs users coming from old versions of the
+ documentation or from external links to the appropriate new location
+ for the information they need.
+ </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
doc-rename-cleanup_v5_v10.patchtext/x-diff; charset=us-asciiDownload
From 3b427f860b36037a43203eab89c382c6f0297331 Mon Sep 17 00:00:00 2001
From: Stephen Frost <sfrost@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
Reviewed-by: Euler Taveira
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 | 40 +++++++++++++++++++
doc/src/sgml/filelist.sgml | 6 +++
doc/src/sgml/postgres.sgml | 1 +
6 files changed, 119 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..4a293b6490
--- /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_receivewal</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..548297e2d3
--- /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</title>
+
+ <para>
+ Functionality is sometimes removed from PostgreSQL, feature, setting
+ and file names sometimes change, or documentation moves to different
+ places. This section directs users coming from old versions of the
+ documentation or from external links to the appropriate new location
+ for the information they need.
+ </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
doc-rename-cleanup_v5_v11.patchtext/x-diff; charset=us-asciiDownload
From 0586ca5121f8fe3352d9dbd4f548aa0a829448b2 Mon Sep 17 00:00:00 2001
From: Stephen Frost <sfrost@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
Reviewed-by: Euler Taveira
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 | 40 +++++++++++++++++++
doc/src/sgml/filelist.sgml | 6 +++
doc/src/sgml/postgres.sgml | 1 +
6 files changed, 119 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..f74d0ae832
--- /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_receivewal</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..548297e2d3
--- /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</title>
+
+ <para>
+ Functionality is sometimes removed from PostgreSQL, feature, setting
+ and file names sometimes change, or documentation moves to different
+ places. This section directs users coming from old versions of the
+ documentation or from external links to the appropriate new location
+ for the information they need.
+ </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
doc-rename-cleanup_v5_v12.patchtext/x-diff; charset=us-asciiDownload
From a6ac0585e07ba306ab05b5e3dd19dc02db0f8659 Mon Sep 17 00:00:00 2001
From: Stephen Frost <sfrost@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
Reviewed-by: Euler Taveira
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 | 41 +++++++++++++
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, 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..f74d0ae832
--- /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_receivewal</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..77c4289531
--- /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..ffd7d40263
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete.sgml
@@ -0,0 +1,41 @@
+<!-- doc/src/sgml/obsolete.sgml -->
+
+<appendix id="appendix-obsolete">
+ <title>Obsolete or Renamed Features</title>
+
+ <para>
+ Functionality is sometimes removed from PostgreSQL, feature, setting
+ and file names sometimes change, or documentation moves to different
+ places. This section directs users coming from old versions of the
+ documentation or from external links to the appropriate new location
+ for the information they need.
+ </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
doc-rename-cleanup_v5_v13.patchtext/x-diff; charset=us-asciiDownload
From cfdb973830390858333c805aa8a08dcdb255f619 Mon Sep 17 00:00:00 2001
From: Stephen Frost <sfrost@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
Reviewed-by: Euler Taveira
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 | 41 +++++++++++++
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, 199 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..f74d0ae832
--- /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_receivewal</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..77c4289531
--- /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..ffd7d40263
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete.sgml
@@ -0,0 +1,41 @@
+<!-- doc/src/sgml/obsolete.sgml -->
+
+<appendix id="appendix-obsolete">
+ <title>Obsolete or Renamed Features</title>
+
+ <para>
+ Functionality is sometimes removed from PostgreSQL, feature, setting
+ and file names sometimes change, or documentation moves to different
+ places. This section directs users coming from old versions of the
+ documentation or from external links to the appropriate new location
+ for the information they need.
+ </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