Re: Doc: Move standalone backup section, mention -X argument

On Wed, Jan 22, 2025 at 1:54 AM Benoit Lobréau <benoit.lobreau@dalibo.com>
wrote:

I don’t think pg_basebackup fits naturally under the "File System Level
Backup" section. I considered creating a "Standalone Physical Backup"
section with two subsections: FS-level backups and pg_basebackup, but
that didn’t feel right either.

Aside from the name choice this is what I propose, so can you elaborate on
what doesn't feel right? You cannot have both "Standalone Physical Backup"
and "File System Level Backup" co-exist so maybe that was it - not
realizing that your "new" section is just my proposal?

What I find most problematic about the current state of the
documentation is that this solution is buried in the "Tips and Examples"
section.

I'll agree with that too;

Making it a sect2 under File System Level Backup is also a solution to your
"buried" complaint.

What if we just move the "Standalone Hot Backups" up one level and
rename the level 2 section ?

My initial annoyance was having the following sentence in a section named,
in part, PITR.

"These are backups that cannot be used for point-in-time recovery."

Which suggests the advice is fundamentally misplaced when in PITR sect2.

David J.

On 1/23/25 4:18 AM, David G. Johnston wrote:

Aside from the name choice this is what I propose, so can you elaborate
on what doesn't feel right?  You cannot have both "Standalone Physical
Backup" and "File System Level Backup" co-exist so maybe that was it -
not realizing that your "new" section is just my proposal?

The current "File System Level Backup" section describes OS-centric,
mostly cold backups (part of the file system snapshot solutions can be
considered hotish).

On the other hand "Standalone Hot Backups" use PostgreSQL's backup API
and the WALs. They can be fetched using archiving which is described in
the "Continuous Archiving and (PITR)" section, or through streaming
(e.g., pg_basebackup -X stream or with pg_receivewal). Overall, I feel
these backups share more in common with what is described in section
"25.3" than in "25.2".

I also wasn't a fan of the following:

* That standalone hot backup with the backup API disappear in your proposal.

* Of the sentence "PostgreSQL provides a tool, pg_basebackup, that can
produce a similar standalone backup to the one produced by pg_dump,"
because I don't think they have much in common aside from being standalone.

My initial annoyance was having the following sentence in a section
named, in part, PITR.

"These are backups that cannot be used for point-in-time recovery."

Which suggests the advice is fundamentally misplaced when in PITR sect2.

Yes, I totally agree. I didn’t like that either and tried to address it
by renaming the section to:

25.3. Continuous Archiving, backups and Point-in-Time Recovery (PITR)

If that’s not sufficient, how about:

25.3. PostgreSQL level physical backups and recovery
25.3.1. Setting Up WAL Archiving
25.3.2. Making a Base Backup
25.3.3. Making an Incremental Backup
25.3.4. Making a Base Backup Using the Low Level API
25.3.5. Making a Standalone Hot Backup
25.3.6. Recovering Using a Continuous Archive Backup (PITR)
25.3.7. Timelines
25.3.8. Tips and Examples
25.3.9. Caveats

Note: As I mentioned to you privately, I made a mistake and broke the
thread. I’ve added the new thread to the commit fest. Here is a link to
the old one to help others follow the conversation:

/messages/by-id/CAKFQuwaS6DtSde4TWpk133mfaQbgh8d+Pkk0kDN=6jf6qEWbvQ@mail.gmail.com

--
Benoit Lobréau
Consultant
http://dalibo.com