From a3d0f810ea5440fc248e5d678cb980cddb3de56f Mon Sep 17 00:00:00 2001 From: Andre Date: Wed, 7 Aug 2024 05:40:36 -0300 Subject: [PATCH] Document changes in `barman recover` with incremental backups This commit is adding an explanation on how the recover from an incremental backup works using pg_combinebackup and a later copy/move dependending on the final destination (remote or local). Also explains about the use of the local_staging_path for this operation. A detailed NOTE was added to the manual where there is a documentation about Backup commands and recover. Also, the new field called local_staging_path was added to the barman.1.d recover command documentation and a GUC file for the field was added. References: BAR-252 Signed-off-by: Andre --- doc/barman.1.d/50-recover.md | 8 +++++++ doc/barman.5.d/50-local_staging_path.md | 8 +++++++ doc/manual/43-backup-commands.en.md | 31 +++++++++++++++++++++++++ 3 files changed, 47 insertions(+) create mode 100644 doc/barman.5.d/50-local_staging_path.md diff --git a/doc/barman.1.d/50-recover.md b/doc/barman.1.d/50-recover.md index 965d55eea..9ef3ae907 100644 --- a/doc/barman.1.d/50-recover.md +++ b/doc/barman.1.d/50-recover.md @@ -106,6 +106,14 @@ recover *\[OPTIONS\]* *SERVER_NAME* *BACKUP_ID* *DESTINATION_DIRECTORY* This option is *required* when recovering from compressed backups and has no effect otherwise. + --local-staging-path *STAGING_PATH* + : A path to a location on the barman host where the chain of backups will + be combined before being copied to the destination directory. Contents + created inside the staging path are removed at the + end of the recovery process. This option is *required* when recovering + from incremental backups (backup_method=postgres) and has no effect + otherwise. + --recovery-conf-filename *RECOVERY_CONF_FILENAME* : The name of the file where Barman should write the PostgreSQL recovery options when recovering backups for PostgreSQL versions 12 and later. diff --git a/doc/barman.5.d/50-local_staging_path.md b/doc/barman.5.d/50-local_staging_path.md new file mode 100644 index 000000000..f17ba36b0 --- /dev/null +++ b/doc/barman.5.d/50-local_staging_path.md @@ -0,0 +1,8 @@ +local_staging_path +: A path to a location on the local host where incremental backups will + be combined during the recovery. This location must have enough + available space to temporarily hold the new synthetic backup. This + option is *required* when recovering from an incremental backup and + has no effect otherwise. + + Scope: Global/Server/Model. diff --git a/doc/manual/43-backup-commands.en.md b/doc/manual/43-backup-commands.en.md index ec8247764..e00358984 100644 --- a/doc/manual/43-backup-commands.en.md +++ b/doc/manual/43-backup-commands.en.md @@ -354,6 +354,37 @@ the `--recovery-staging-path` option with the `barman recover` command. If you do neither of these things and attempt to recover a compressed backup then Barman will fail rather than try to guess a suitable location. +### Recovering incremental backups + +If a backup is incremental, `barman recover` is able to combine the chain +of backups on recovery through `pg_combinebackup`. +A chain of backups is the tree branch that goes from the full backup +to the one requested for the recovery. This is a multi-step process: + +1. The chain of backups is combined into a new synthetic backup. A + folder named with the ID of the incremental backup being recovered is + created inside a given staging directory on the local server using + `pg_combinebackup`. For any type of recover (local or remote), the + synthetic backup is created locally in the barman server. +2. If it's a remote recover, the content is copied to the final destination + using Rsync. Otherwise, when it's a local recover, the content is just + moved to the final destination. +3. The folder named with the ID of the incremental backup being recovered, which + was created inside the provided staging directory, is removed at the end of the + recovery process. + +When recovering from an incremental backup, you *must* therefore +either set `local_staging_path` in the global/server config *or* use +the `--local-staging-path` option with the `barman recover` command. If +you do neither of these things and attempt to recover an incremental backup +then Barman fails rather than trying to guess a suitable location. + +> **IMPORTANT:** +> If any of the backups in the chain were taken with checksums +> disabled, but the final backup was taken with checksums enabled, the +> resulting directory may contain pages with invalid checksums. +> [Follow up the `limitations` section in pg_basebackup documentation](https://www.postgresql.org/docs/17/app-pgcombinebackup.html). + ## `show-backup` You can retrieve all the available information for a particular backup of