Greetings, * Bruce Momjian (br...@momjian.us) wrote: > On Fri, Dec 4, 2020 at 02:00:23PM -0500, Stephen Frost wrote: > > * Bruce Momjian (br...@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.
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
From 978f52f1f33fcde55db9fd8ff3fb60897cdf019c Mon Sep 17 00:00:00 2001 From: Stephen Frost <sfr...@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=mot...@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
signature.asc
Description: PGP signature
