Greetings, * Stephen Frost (sfr...@snowman.net) wrote: > * Craig Ringer (craig.rin...@enterprisedb.com) wrote: > > On Thu, 14 Jan 2021 at 03:44, Stephen Frost <sfr...@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
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
signature.asc
Description: PGP signature
