pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedMissing information on '-X' in section 26.3.6.1.
5+ messages / 3 participants
[nested] [flat]
* Missing information on '-X' in section 26.3.6.1.
@ 2024-01-22 18:20 PG Doc comments form <noreply@postgresql.org>
2024-01-23 20:43 ` Re: Missing information on '-X' in section 26.3.6.1. David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 5+ messages in thread
From: PG Doc comments form @ 2024-01-22 18:20 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: lukas.langenegger@hexabit.ch
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/16/continuous-archiving.html
Description:
Hi!
I'm reading through the documentation and so far I have to say this is the
best documentation I have ever encountered, thank you!
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.
Thank you and have a nice day!
Lukas
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Missing information on '-X' in section 26.3.6.1.
2024-01-22 18:20 Missing information on '-X' in section 26.3.6.1. PG Doc comments form <noreply@postgresql.org>
@ 2024-01-23 20:43 ` David G. Johnston <david.g.johnston@gmail.com>
2024-01-24 09:19 ` Re: Missing information on '-X' in section 26.3.6.1. Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 5+ messages in thread
From: David G. Johnston @ 2024-01-23 20:43 UTC (permalink / raw)
To: lukas.langenegger@hexabit.ch; pgsql-docs@lists.postgresql.org
On Tue, Jan 23, 2024 at 1:30 PM PG Doc comments form <noreply@postgresql.org>
wrote:
> The following documentation comment has been logged on the website:
>
> Page: 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.
David J.
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Missing information on '-X' in section 26.3.6.1.
2024-01-22 18:20 Missing information on '-X' in section 26.3.6.1. PG Doc comments form <noreply@postgresql.org>
2024-01-23 20:43 ` Re: Missing information on '-X' in section 26.3.6.1. David G. Johnston <david.g.johnston@gmail.com>
@ 2024-01-24 09:19 ` Daniel Gustafsson <daniel@yesql.se>
2024-02-02 19:41 ` Re: Missing information on '-X' in section 26.3.6.1. David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 5+ messages in thread
From: Daniel Gustafsson @ 2024-01-24 09:19 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: lukas.langenegger@hexabit.ch; pgsql-docs@lists.postgresql.org
> On 23 Jan 2024, at 21:43, David G. Johnston <david.g.johnston@gmail.com> wrote:
>
> On Tue, Jan 23, 2024 at 1:30 PM PG Doc comments form <noreply@postgresql.org <mailto:noreply@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.
--
Daniel Gustafsson
Attachments:
[application/octet-stream] pg_basebackup_X.diff (962B, ../../0E92E952-1F69-4646-A649-B6F3EFAACA90@yesql.se/2-pg_basebackup_X.diff)
download | inline diff:
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index b3468eea3c..fcefb212e1 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1458,9 +1458,10 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
<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
+ tool. If you include the <literal>-X</literal> parameter
+ (with either <literal>fetch</literal> or <literal>stream</literal>)
+ 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>
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Missing information on '-X' in section 26.3.6.1.
2024-01-22 18:20 Missing information on '-X' in section 26.3.6.1. PG Doc comments form <noreply@postgresql.org>
2024-01-23 20:43 ` Re: Missing information on '-X' in section 26.3.6.1. David G. Johnston <david.g.johnston@gmail.com>
2024-01-24 09:19 ` Re: Missing information on '-X' in section 26.3.6.1. Daniel Gustafsson <daniel@yesql.se>
@ 2024-02-02 19:41 ` David G. Johnston <david.g.johnston@gmail.com>
2024-06-28 21:01 ` Re: Missing information on '-X' in section 26.3.6.1. David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 5+ messages in thread
From: David G. Johnston @ 2024-02-02 19:41 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: lukas.langenegger@hexabit.ch; pgsql-docs@lists.postgresql.org
On Wed, Jan 24, 2024 at 2:19 AM Daniel Gustafsson <daniel@yesql.se> wrote:
> > On 23 Jan 2024, at 21:43, David G. Johnston <david.g.johnston@gmail.com>
> wrote:
> >
> > On Tue, Jan 23, 2024 at 1:30 PM PG Doc comments form <
> noreply@postgresql.org <mailto:noreply@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.
Attachments:
[text/x-patch] v1-0001-docs-move-standalone-pg_basebackup-docs-to-file-syst.patch (3.5K, ../../CAKFQuwZ=WxdWJ6O66yQ9dnWTLO12p7h3HpfhowCj+0U_bNrzdg@mail.gmail.com/3-v1-0001-docs-move-standalone-pg_basebackup-docs-to-file-syst.patch)
download | inline diff:
From 0512ec27c52401b9ed7b468e7b68ff9ebec1584e Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johnston@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
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Missing information on '-X' in section 26.3.6.1.
2024-01-22 18:20 Missing information on '-X' in section 26.3.6.1. PG Doc comments form <noreply@postgresql.org>
2024-01-23 20:43 ` Re: Missing information on '-X' in section 26.3.6.1. David G. Johnston <david.g.johnston@gmail.com>
2024-01-24 09:19 ` Re: Missing information on '-X' in section 26.3.6.1. Daniel Gustafsson <daniel@yesql.se>
2024-02-02 19:41 ` Re: Missing information on '-X' in section 26.3.6.1. David G. Johnston <david.g.johnston@gmail.com>
@ 2024-06-28 21:01 ` David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 0 replies; 5+ messages in thread
From: David G. Johnston @ 2024-06-28 21:01 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: lukas.langenegger@hexabit.ch; pgsql-docs@lists.postgresql.org
On Fri, Feb 2, 2024 at 12:41 PM David G. Johnston <
david.g.johnston@gmail.com> wrote:
>
> 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.
>
>
Created a new -hackers thread for my patch and added it to the commitfest
for July.
https://www.postgresql.org/message-id/CAKFQuwaS6DtSde4TWpk133mfaQbgh8d%2BPkk0kDN%3D6jf6qEWbvQ%40mail...
David J.
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2024-06-28 21:01 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2024-01-22 18:20 Missing information on '-X' in section 26.3.6.1. PG Doc comments form <noreply@postgresql.org>
2024-01-23 20:43 ` David G. Johnston <david.g.johnston@gmail.com>
2024-01-24 09:19 ` Daniel Gustafsson <daniel@yesql.se>
2024-02-02 19:41 ` David G. Johnston <david.g.johnston@gmail.com>
2024-06-28 21:01 ` David G. Johnston <david.g.johnston@gmail.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox