Skip to content

Commit

Permalink
Change docs to clarify which type of backup it's talking about
Browse files Browse the repository at this point in the history
Change mentions of "incremental backup" in the docs to explicitly tell
which type of backup it's talking about i.e. block-level or file-level.

References: BAR-283

Signed-off-by: Gustavo William <gustavo.oliveira@enterprisedb.com>
  • Loading branch information
gustabowill committed Aug 22, 2024
1 parent 2ec4c5c commit 17c088a
Show file tree
Hide file tree
Showing 2 changed files with 14 additions and 14 deletions.
18 changes: 9 additions & 9 deletions doc/manual/43-backup-commands.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,17 +82,17 @@ barman keep <server_name> <backup_id> [--target TARGET, --status, --release]
```

> **NOTE:**
> To ensure the integrity of your backup system, incremental backups
> To ensure the integrity of your backup system, block-level incremental backups
> cannot use the keep annotation in Barman. This restriction is due to
> the way incremental backups depend on each other. Using the keep
> annotation with incremental backups could result in orphaned backups,
> the way block-level incremental backups depend on each other. Using the keep
> annotation on such backups could result in orphaned backups,
> which means that certain backups might exist without their necessary
> parent backups.
>
> In simpler terms, if you were allowed to apply the keep annotation to
> an incremental backup, there would be a risk that parts of the backup
> a block-level incremental backup, there would be a risk that parts of the backup
> chain would be retained without their required predecessors. This
> situation could create backups that would be no longer useful or
> situation could create backups that would be no longer be useful or
> complete, as they would be missing the essential parent backups needed
> to restore them properly.
Expand Down Expand Up @@ -374,9 +374,9 @@ 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
### Recovering block-level incremental backups

If a backup is incremental, `barman recover` is able to combine the chain
If a backup is a block-level 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:
Expand All @@ -393,10 +393,10 @@ to the one requested for the recovery. This is a multi-step process:
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
When recovering from a block-level 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
you do neither of these things and attempt to recover such backup
then Barman fails rather than trying to guess a suitable location.

> **IMPORTANT:**
Expand Down
10 changes: 5 additions & 5 deletions doc/manual/50-feature-details.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,9 +112,9 @@ To be able to perform a block-level incremental backup in Barman you must:
- Have `summarize_wal` enabled.
- Have `postgres` as your backup method.

> **NOTE:** Compressed backups are not **yet** eligible for incremental backups in Barman.
> **NOTE:** Compressed backups are not **yet** eligible for block-level incremental backups in Barman.
> **IMPORTANT:** If you decide to enable `data_checksums` between incremental backups,
> **IMPORTANT:** If you decide to enable `data_checksums` between block-level incremental backups,
> it is adivised to take a new full-backup as divergent checkum configurations can potentially
> lead to issues during recovery.
Expand Down Expand Up @@ -594,12 +594,12 @@ Retention policy based on recovery window
>
> How It Works
>
> When the retention policy is applied, Barman ignores incremental backups
> When the retention policy is applied, Barman ignores block-level incremental backups
> and focuses only on the status of the full backups.
>
> If the full backup is marked as KEEP:FULL, KEEP:STANDALONE, or VALID,
> the status VALID is marked to all dependent incremental backups.
> If the full backup is marked as OBSOLETE, then all incremental backups
> the status VALID is marked to all dependent block-level incremental backups.
> If the full backup is marked as OBSOLETE, then all block-level incremental backups
> that depend on it will also be marked as OBSOLETE and removed.
#### Scope
Expand Down

0 comments on commit 17c088a

Please sign in to comment.