Обсуждение: Doc: Move standalone backup section, mention -X argument
A documentation comment came in [1] causing me to review some of our backup documentation and I left the current content and location of the standalone backups was odd. I propose to move it to a better place, under file system backups.
Adding to commitfest.
David J.
Вложения
I compiled the patch and it worked without any problems.
I think the patch makes sense, because of the structure of the current
docs. It seems more logical to have this section in this part of the
documentation, where it is useful and not only described for another
chapter, because it won't even work with the current chapter it is
referenced in ("Continous Archiving and Point-in-Time Recovery
(PITR)").
I am still new to Postgres, so I can't tell whether it can be written
more detailed or not. But I really like it, that is in a more fitting
chapter in my opinion.
Regards,
Marlene Reiterer
Am Mo., 16. Sept. 2024 um 10:35 Uhr schrieb David G. Johnston
<david.g.johnston@gmail.com>:
>
> A documentation comment came in [1] causing me to review some of our backup documentation and I left the current
contentand location of the standalone backups was odd. I propose to move it to a better place, under file system
backups.
>
> Adding to commitfest.
>
> David J.
>
> [1] https://www.postgresql.org/message-id/CAKFQuwZ%3DWxdWJ6O66yQ9dnWTLO12p7h3HpfhowCj%2B0U_bNrzdg%40mail.gmail.com
>
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
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: https://www.postgresql.org/message-id/flat/CAKFQuwaS6DtSde4TWpk133mfaQbgh8d%2BPkk0kDN%3D6jf6qEWbvQ%40mail.gmail.com -- Benoit Lobréau Consultant http://dalibo.com
On 2024-Jun-28, David G. Johnston wrote: > A documentation comment came in [1] causing me to review some of our backup > documentation and I left the current content and location of the standalone > backups was odd. I propose to move it to a better place, under file system > backups. Even before this patch, these sections are all a bit incoherent, because we spend a lot of vertical space explaining WAL archiving before even mentioning how they would be used, with pg_basebackup mentioned halfway down the page. Your patch makes it a bit better, but I think it doesn't go far enough. Even after the patch, If the reader skips 25.2, then section 25.3 reads a bit incoherent until you're halfway down the (quite long) page and pg_basebackup is mentioned. I think it would be better to move 25.2 out of the way moving it to the end of the chapter, and do something like this 25.1. SQL Dump 25.1.1. Restoring the Dump 25.1.2. Using pg_dumpall 25.1.3. Handling Large Databases 25.2. Physical Backups Using Continuous Archiving David's text: "In constrast to logical backups ... " 25.2.1. Built-In Standalone Backups "If all you want is a standalone ..." 25.2.2. Setting Up WAL Archiving 25.2.3. Making a Base Backup 25.2.4. Making an Incremental Backup 25.2.5. Making a Base Backup Using the Low Level API 25.2.6. Recovering Using a Continuous Archive Backup 25.2.7. Timelines 25.2.8. Tips and Examples 25.2.9. Caveats 25.3. File System Level Backup Start current 25.2 with a few additional words: "An older and largely deprecated technique to take a backup is to directly copy the files ... " -- Álvaro Herrera Breisgau, Deutschland — https://www.EnterpriseDB.com/ "Nunca confiaré en un traidor. Ni siquiera si el traidor lo he creado yo" (Barón Vladimir Harkonnen)
On Monday, February 10, 2025, Álvaro Herrera <alvherre@alvh.no-ip.org> wrote:
On 2024-Jun-28, David G. Johnston wrote:
> A documentation comment came in [1] causing me to review some of our backup
> documentation and I left the current content and location of the standalone
> backups was odd. I propose to move it to a better place, under file system
> backups.
Even before this patch, these sections are all a bit incoherent, because
we spend a lot of vertical space explaining WAL archiving before even
mentioning how they would be used, with pg_basebackup mentioned halfway
down the page. Your patch makes it a bit better, but I think it doesn't
go far enough. Even after the patch, If the reader skips 25.2, then
section 25.3 reads a bit incoherent until you're halfway down the (quite
long) page and pg_basebackup is mentioned. I think it would be better
to move 25.2 out of the way moving it to the end of the chapter, and do
something like this
25.1. SQL Dump
25.1.1. Restoring the Dump
25.1.2. Using pg_dumpall
25.1.3. Handling Large Databases
25.2. Physical Backups Using Continuous Archiving
David's text: "In constrast to logical backups ... "
25.2.1. Built-In Standalone Backups
"If all you want is a standalone ..."
25.2.2. Setting Up WAL Archiving
25.2.3. Making a Base Backup
25.2.4. Making an Incremental Backup
25.2.5. Making a Base Backup Using the Low Level API
25.2.6. Recovering Using a Continuous Archive Backup
25.2.7. Timelines
25.2.8. Tips and Examples
25.2.9. Caveats
25.3. File System Level Backup
Start current 25.2 with a few additional words: "An older and largely
deprecated technique to take a backup is to directly copy the files ... "
Thanks. There is another comment floating about saying a similar thing. I’m good with giving a more comprehensive patch a go.
David J.
On Sat, 29 Jun 2024 at 02:27, David G. Johnston <david.g.johnston@gmail.com> wrote: > > A documentation comment came in [1] causing me to review some of our backup documentation and I left the current contentand location of the standalone backups was odd. I propose to move it to a better place, under file system backups. > > Adding to commitfest. I noticed that Alvaro's comment from [1] is not yet addressed, I have changed the status of commitfest entry to Waiting on Author, please address them and change the status back to Needs review. [1] - https://www.postgresql.org/message-id/202502101154.bmb536npfl5e%40alvherre.pgsql Regards, Vignesh
On 3/16/25 2:19 PM, vignesh C wrote: > I noticed that Alvaro's comment from [1] is not yet addressed, I have > changed the status of commitfest entry to Waiting on Author, please > address them and change the status back to Needs review. > [1] - https://www.postgresql.org/message-id/202502101154.bmb536npfl5e%40alvherre.pgsql > > Regards, > Vignesh Hi, You will find a patch for the proposed changes attached to this mail. The menu is now: 25.1. SQL Dump 25.1.1. Restoring the Dump 25.1.2. Using pg_dumpall 25.1.3. Handling Large Databases 25.2. Physical Backups Using Continuous Archiving 25.2.1. Built-In Standalone Backups 25.2.2. Setting Up WAL Archiving 25.2.3. Making a Base Backup 25.2.4. Making an Incremental Backup 25.2.5. Making a Base Backup Using the Low Level API 25.2.6. Recovering Using a Continuous Archive Backup 25.2.7. Timelines 25.2.8. Tips and Examples 25.2.9. Caveats 25.3. File System Level Backup I slightly modified section 25.2.1 and 25.3 as proposed. -- Benoit Lobréau Consultant http://dalibo.com