On Wed, Jan 24, 2024 at 2:19 AM Daniel Gustafsson <dan...@yesql.se> wrote:
> > On 23 Jan 2024, at 21:43, David G. Johnston <david.g.johns...@gmail.com>
> wrote:
> >
> > On Tue, Jan 23, 2024 at 1:30 PM PG Doc comments form <
> nore...@postgresql.org <mailto:nore...@postgresql.org>> wrote:
> > The following documentation comment has been logged on the website:
> >
> > Page: https://www.postgresql.org/docs/16/continuous-archiving.html <
> https://www.postgresql.org/docs/16/continuous-archiving.html>
> > Description:
> >
> > I noticed, that in section 26.3.6.1. it's not specified, what the -X
> > parameter should be set to (stream or fetch, or whether it even
> matters). I
> > could continue with trial and error, but it confused me a bit.
> >
> > The -X parameter is documented to have a default; but since both fetch
> and stream are documented to give you the same end result it doesn't
> matter. Of course you cannot specify the none method.
>
> Agreed. Still, it doesn't hurt to spell out what we take for granted but a
> newcomer have to figure out in order to make the documentation easy to
> follow
> for new users. Something like the attached would be enough I think.
>
>
So I once again find a larger issue here, mostly unrelated to the complaint
at hand.
This entire paragraph is in the Continuous Archiving & PITR section but the
entire standalone concept is in opposition to that. It is also in a "Tips"
section but doesn't really read as a tip.
Thinking on it further, and as the tip talks about, what we are really
doing here is describing a standalone physical file system backup in
contrast to a pg_dump backup. We already have a chapter that does this -
the previous one named "File System Level Backup".
The attached patch moves this paragraph there. I distilled the paragraph
down to its essence, but am open to being a bit more wordy, and consider
more how this fits into the existing content of that page. I'm only really
married to two things - mentioning the -X argument to pg_basebackup here is
a bad idea and the content does not fit in the existing Tip area of
continuous archiving section.
David J.
From 0512ec27c52401b9ed7b468e7b68ff9ebec1584e Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johns...@gmail.com>
Date: Fri, 2 Feb 2024 12:32:51 -0700
Subject: [PATCH] docs: move standalone pg_basebackup docs to file system
section
---
doc/src/sgml/backup.sgml | 47 ++++++++++++++++++++--------------------
1 file changed, 24 insertions(+), 23 deletions(-)
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index b3468eea3c..1c5e48d6da 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -351,6 +351,29 @@ pg_dump -j <replaceable class="parameter">num</replaceable> -F d -f <replaceable
<sect1 id="backup-file">
<title>File System Level Backup</title>
+ <para>
+ In constrast to the logical backup that pg_dump performs there is
+ also the option to perform a physical backup.
+ <productname>PostgreSQL</productname> provides a tool,
+ <literal>pg_basebackup</literal>, that can produce a similar standalone
+ backup to the one produced by pg_dump, though the restoration point
+ of the physical backup is as of when the backup ended instead of when
+ it began. You may also choose to roll your own solution using the tools
+ available in your operating system. This section describes both options.
+ </para>
+
+ <sect2 id="backup-standalone-pgbasebackup">
+ <title>Built-In Standalone Backups</title>
+ <para>
+ If all you want is a simple standalone backup of your cluster at some point in time
+ (specifically at roughly the moment the backup ended) you can just save the archive
+ produced by the <xref linkend="app-pgbasebackup"/> command. It handles, by default,
+ saving the write-ahead log (WAL) files produced during the backup to the archive.
+ </para>
+ </sect2>
+
+ <sect2 id="backup-standalone-custom">
+ <title>Custom Physical Backups</title>
<para>
An alternative backup strategy is to directly copy the files that
<productname>PostgreSQL</productname> uses to store the data in the database;
@@ -462,6 +485,7 @@ tar -cf backup.tar /usr/local/pgsql/data
the contents of indexes for example, just the commands to recreate
them.) However, taking a file system backup might be faster.
</para>
+ </sect2>
</sect1>
<sect1 id="continuous-archiving">
@@ -1442,29 +1466,6 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
<para>
Some tips for configuring continuous archiving are given here.
</para>
-
- <sect3 id="backup-standalone">
- <title>Standalone Hot Backups</title>
-
- <para>
- It is possible to use <productname>PostgreSQL</productname>'s backup facilities to
- produce standalone hot backups. These are backups that cannot be used
- for point-in-time recovery, yet are typically much faster to backup and
- restore than <application>pg_dump</application> dumps. (They are also much larger
- than <application>pg_dump</application> dumps, so in some cases the speed advantage
- might be negated.)
- </para>
-
- <para>
- As with base backups, the easiest way to produce a standalone
- hot backup is to use the <xref linkend="app-pgbasebackup"/>
- tool. If you include the <literal>-X</literal> parameter when calling
- it, all the write-ahead log required to use the backup will be
- included in the backup automatically, and no special action is
- required to restore the backup.
- </para>
- </sect3>
-
<sect3 id="compressed-archive-logs">
<title>Compressed Archive Logs</title>
--
2.34.1
