Thread

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

   Benoit Lobréau <benoit.lobreau@dalibo.com> — 2025-01-22T08:54:19Z

   Hi,
   
   Initially, I shared your perspective, but I wasn’t entirely on board 
   with the subdivision you proposed. The more I thought about it and tried 
   to reshape it, the less convinced I became.
   
   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.
   
   What I find most problematic about the current state of the 
   documentation is that this solution is buried in the "Tips and Examples" 
   section. As a result, it’s easy to miss when skimming through the docs 
   since the list of sub sections displayed at the top of the page and in 
   "Chapter 25. Backup and Restore" stops 3 level deep.
   
   What if we just move the "Standalone Hot Backups" up one level and 
   rename the level 2 section ? Something like this ?
   
   25.3. Continuous Archiving, backups and Point-in-Time Recovery (PITR)
   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
   25.3.7. Timelines
   25.3.8. Tips and Examples
   25.3.9. Caveats
   
   -- 
   Benoit Lobréau
   Consultant
   http://dalibo.com
   
   
   
   
   

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

   David G. Johnston <david.g.johnston@gmail.com> — 2025-01-23T03:18:40Z

   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.
   

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

   Benoit Lobréau <benoit.lobreau@dalibo.com> — 2025-01-23T10:21:10Z

   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:
   
   https://www.postgresql.org/message-id/flat/CAKFQuwaS6DtSde4TWpk133mfaQbgh8d%2BPkk0kDN%3D6jf6qEWbvQ%40mail.gmail.com
   
   -- 
   Benoit Lobréau
   Consultant
   http://dalibo.com