Skip to content

PBM-1649 Documented the ability to clean up outdated backups from external storages #330

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nastena1606 wants to merge 3 commits into
base: main
Choose a base branch
from
Open

PBM-1649 Documented the ability to clean up outdated backups from external storages #330

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
be883af
PBM-1649 Documented the ability to clean up outdated backups from ext…
nastena1606 Dec 29, 2025
0f6ac17
Update docs/features/multi-storage.md
nastena1606 Dec 29, 2025
e56b5b9
Update docs/features/multi-storage.md
nastena1606 Dec 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 31 additions & 8 deletions docs/features/multi-storage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,25 +105,48 @@

## Delete backups

You can delete backups from an external storage only by name.
You can delete backups from an external storage by name or by specifying a time threshold with the `--profile` flag. To delete backups older than a specified time from an external storage, you must run PBM version 2.13.0 and newer.

Run the `pbm delete` command and pass the backup name:
=== "Delete by backup name"

```bash
pbm delete-backup 2024-06-25T10:54:55Z
```
Run the `pbm delete-backup` command and pass the backup name:

```bash
pbm delete-backup 2024-06-25T10:54:55Z
```

=== "Delete backups older than specified time"

Starting with version [2.13.0](../release-notes/2.13.0.md), you can delete backups that are older than a specified time from external storages. Use the `--older-than` flag to set the retention period, and include the `--profile` flag to define the target storage.
The `--profile` flag works only with the `--older-than` flag. If you pass it with the backup name, PBM fails the delete operation and reports an error.

You can use either the `pbm delete-backup` command to include only backups, or `pbm cleanup` command to also include point-in-time recovery oplog slices:

Example of the `pbm delete-backup` command:

```bash
pbm delete-backup --older-than 30d --profile=minio -y
```

Example of the `pbm cleanup` command:

```bash
pbm cleanup --older-than 30d --profile=minio -y
```

When you omit the `--profile` flag, PBM deletes outdated data on the default (main) storage and automatically updates the metadata without requiring a manual resync.

## Implementation specifics

1. You can make backups of any type except snapshot-based ones on the external storage.
2. To start point-in-time recovery oplog slicing, you must make a backup on the main storage. A backup from an external storage is not considered a valid base backup for oplog slicing.
3. PBM saves point-in-time recovery oplog ranges only on the main storage. Backups are saved on the storage that you define when starting a backup.
4. Backup process on the external storage doesn’t stop point-in-time recovery oplog slicing on the main storage. Thus, PBM saves oplog chunks related to such backups on both the main and the external storages
4. Backup process on the external storage doesn't stop point-in-time recovery oplog slicing on the main storage. Thus, PBM saves oplog chunks related to such backups on both the main and the external storages

Check warning on line 144 in docs/features/multi-storage.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/features/multi-storage.md#L144 

[Vale.Spelling] Did you really mean 'storages'?
Raw output 
{"message": "[Vale.Spelling] Did you really mean 'storages'?", "location": {"path": "docs/features/multi-storage.md", "range": {"start": {"line": 144, "column": 201}}}, "severity": "WARNING"}
Copy link

@jcechace jcechace Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although this didn't change, I think it is related to

https://perconadev.atlassian.net/browse/PBM-1665

@boris-ilijic should we somehow rephrase it?

Copy link
Member

@boris-ilijic boris-ilijic Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, currently we do not have step 4. implemented and everything is described within the upper ticket. Let's wait for refinement and agree how should we handle this. Documentation can wait IMO, but if you prefer to update it within this PR I am fine with it.

5. The whole incremental chain must be stored on the same storage. To change the storage for incremental backups, you must start a new backup chain with the incremental base backup on the new storage.
6. To restore from a backup on external storage, `pbm-agents` must have read permissions on it.
7. To make a point-in-time recovery, you must specify the backup name via the `--base-snapshot` flag. Without it, PBM searches for the base backup on the main storage.
8. You can delete backups from external storages only by name using the `pbm delete-backup <backup-name>` command.
9. You can delete backups older than the specified time using the `pbm delete-backup --older-than <time>` or `pbm cleanup --older-than <time>` commands only from the **main** storage.
8. You can delete backups from external storages by name using the `pbm delete-backup <backup-name>` command.

Check warning on line 148 in docs/features/multi-storage.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/features/multi-storage.md#L148 

[Vale.Spelling] Did you really mean 'storages'?
Raw output 
{"message": "[Vale.Spelling] Did you really mean 'storages'?", "location": {"path": "docs/features/multi-storage.md", "range": {"start": {"line": 148, "column": 41}}}, "severity": "WARNING"}
9. Starting with version 2.13.0, you can delete backups older than the specified time from external storages using the `pbm delete-backup --older-than <time> --profile=<profile-name>` or `pbm cleanup --older-than <time> --profile=<profile-name>` commands. Without the `--profile=<profile-name>` flag, PBM deletes data on the main storage. When you run cleanup on the main storage, PBM automatically updates the metadata without requiring a manual resync.

Check warning on line 149 in docs/features/multi-storage.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/features/multi-storage.md#L149 

[Vale.Spelling] Did you really mean 'storages'?
Raw output 
{"message": "[Vale.Spelling] Did you really mean 'storages'?", "location": {"path": "docs/features/multi-storage.md", "range": {"start": {"line": 149, "column": 101}}}, "severity": "WARNING"}
2 changes: 2 additions & 0 deletions docs/reference/pbm-commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@ The command accepts the following flags:
| Flag | Description |
| ------------------------ | ------------------------- |
| `--older-than=TIMESTAMP` | Deletes backups older than date / time specified in the format:<br> - `%Y-%M-%DT%H:%M:%S` (e.g. 2020-04-20T13:13:20), <br> - `%Y-%M-%D` (e.g. 2020-04-20), <br> - `XXd` (e.g. 30d). Only days are supported|
| `--profile=PROFILE_NAME` | Specifies the configuration profile for the storage to clean up. If not specified, cleanup runs on the main storage. Available starting with version 2.13.0|
| `-w`, `--wait` | Wait for the cleanup to finish. The flag blocks the shell session|
| `--wait-time` | The time to wait for PBM to report the status of the command execution. Use this flag together with the `--wait` flag. You can specify the duration in minutes or hours (e.g. 5m, 1h). <br><br>When not set, PBM waits till the command executes. <br><br>If it takes longer than the defined waiting time to execute the command, PBM prints the `Operation is in progress. Check pbm status and logs` error message and unblocks the shell session. The `pbm-agent` continues to execute the command enabling you to track its progress via the `pbm status` command. Available starting with version 2.6.0.|
| `-y`, `--yes` | Cleans up the data storage without asking for a user's confirmation|
Expand Down Expand Up @@ -167,6 +168,7 @@ The command accepts the following flags:
| Flag | Description |
| ------------------------ | ----------------------- |
| `--older-than=TIMESTAMP` | Deletes backups older than date / time specified in the format:<br> - `%Y-%M-%DT%H:%M:%S` (e.g. 2023-04-20T13:13:20) or <br> - `%Y-%M-%D` (e.g. 2023-04-20)|
| `--profile=PROFILE_NAME` | Specifies the configuration profile for the storage from which to delete backups. If not specified, deletion runs on the main storage. Available starting with version 2.13.0|
| `--type=TYPE` | Deletes backups of the specified type. Must be used together with the `-older-than` flag. Available starting with version 2.4.0|
| `--force` | Forcibly deletes backups without asking for user's confirmation. Deprecated. Use the `--yes` flag instead. |
| `-y`, `--yes` | Deletes backups without asking for user's confirmation |
Expand Down
39 changes: 29 additions & 10 deletions docs/usage/delete-backup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,14 @@
pbm cleanup --older-than=`%Y-%M-%D --yes
```

Starting with version 2.13.0, you can clean up backups from [external storages](../features/multi-storage.md) by specifying the `--profile` flag:

Check warning on line 23 in docs/usage/delete-backup.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/usage/delete-backup.md#L23 

[Vale.Spelling] Did you really mean 'storages'?
Raw output 
{"message": "[Vale.Spelling] Did you really mean 'storages'?", "location": {"path": "docs/usage/delete-backup.md", "range": {"start": {"line": 23, "column": 71}}}, "severity": "WARNING"}

```bash
pbm cleanup --older-than 30d --profile=minio --yes
```

When you run cleanup on the main storage, PBM automatically updates the metadata without requiring a manual resync.

### Behavior

The timestamp you specify is considered to be the time to which you would wish to restore. Therefore, PBM doesn’t delete all backup snapshots and oplog slices that could be used to restore to this time.
Expand Down Expand Up @@ -137,7 +145,7 @@

### Behavior

You can delete either a specified backup snapshot or all backup snapshots older than the specified time. Starting with version 2.0.0, you can also delete [selective backups](../features/selective-backup.md).
You can delete either a specified backup snapshot or all backup snapshots older than the specified time. Starting with version 2.0.0, you can also delete [selective backups](../features/selective-backup.md). Starting with version 2.13.0, you can delete backup snapshots older than the specified time from external storages.

Check warning on line 148 in docs/usage/delete-backup.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/usage/delete-backup.md#L148 

[Vale.Spelling] Did you really mean 'storages'?
Raw output 
{"message": "[Vale.Spelling] Did you really mean 'storages'?", "location": {"path": "docs/usage/delete-backup.md", "range": {"start": {"line": 148, "column": 315}}}, "severity": "WARNING"}

=== "Specified backup"

Expand All @@ -149,7 +157,9 @@

=== "Backups older than the specified time"

To delete backups that were created before the specified time, pass the `--older-than` flag to the `pbm delete-backup` command. Specify the timestamp as an argument for `pbm delete-backup` in the following format:
To delete backups that were created before the specified time, pass the `--older-than` flag to the `pbm delete-backup` command. Include the `--profile` flag to delete backups from an [external storage](../features/multi-storage.md).

Specify the timestamp as an argument for `pbm delete-backup` in the following format:

* `%Y-%M-%DT%H:%M:%S` (for example, 2021-04-20T13:13:20Z) or
* `%Y-%M-%D` (2021-04-20).
Expand Down Expand Up @@ -185,6 +195,14 @@
2021-04-21T02:16:33Z
```

To delete backups created before the specified time from external storages, use the `--older-than` and the `--profile` flags:

```bash
pbm delete-backup --older-than 30d --profile=minio --yes
```

Read more about deleting backups from external storages in the [Delete backups from external storages](../features/multi-storage.md#delete-backups) section.


=== "Specific types of backups"

Expand Down Expand Up @@ -212,8 +230,8 @@

You wish to delete all physical backups that are older than 10:00 a.m.

```
$ pbm delete-backup --older-than="2024-02-26T10:00:00" -t physical -y
```bash
pbm delete-backup --older-than="2024-02-26T10:00:00" -t physical -y
```

There are two physical backup snapshots, but only `2024-02-26T09:56:18Z 961.68MB <physical> [restore_to_time: 2024-02-26T09:56:20Z]` snapshot passes in the specified timestamp. Therefore, PBM deletes this one only:
Expand All @@ -240,20 +258,21 @@
2024-02-26T08:43:48Z - 2024-02-26T10:17:21Z
```

To delete backups of the specified type from an external storage, add the `--profile` flag:

```bash
pbm delete-backup --older-than="2024-02-26T10:00:00" -t physical --profile=minio -y
```


By default, the ``pbm delete-backup`` command asks for your confirmation to proceed with the deletion. To bypass it, add the `-y` or
`--yes` flag.

```bash
pbm delete-backup --yes 2023-04-20T13:45:59Z
```

!!! admonition ""

For Percona Backup for MongoDB 1.5.0 and earlier versions, when you delete a backup, all oplog slices that relate to this backup are deleted too. For example, you delete a backup snapshot `2020-07-24T18:13:09` while there is another snapshot `2020-08-05T04:27:55` created after it. The **pbm-agent** deletes only oplog slices that relate to `2020-07-24T18:13:09`.

The same applies if you delete backups older than the specified time.

Note that when point-in-time recovery is enabled, the most recent backup snapshot and oplog slices that relate to it are not deleted.

## Delete oplog slices

Expand Down
11 changes: 10 additions & 1 deletion docs/usage/schedule-backup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,8 +92,17 @@
/usr/bin/pbm cleanup -y --older-than 30d --wait
```

This command deletes backups and oplog slices that are older than 30 days. You can change the period by specifying a desired interval for the `--older-than` flag.
This command deletes backups and oplog slices that are older than 30 days. PBM automatically updates the metadata without requiring a manual resync, simplifying automation workflows.

You can change the period by specifying a desired interval for the `--older-than` flag.

Starting with version 2.13.0, you can also clean up backups from [external storages](../features/multi-storage.md) by specifying both the `--older-than` and the `--profile` flags:

Check warning on line 99 in docs/usage/schedule-backup.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/usage/schedule-backup.md#L99 

[Vale.Spelling] Did you really mean 'storages'?
Raw output 
{"message": "[Vale.Spelling] Did you really mean 'storages'?", "location": {"path": "docs/usage/schedule-backup.md", "range": {"start": {"line": 99, "column": 76}}}, "severity": "WARNING"}

```bash
/usr/bin/pbm cleanup -y --older-than 30d --profile=minio --wait
```

This approach streamlines your retention policy across multiple storages and reduces operational overhead, eliminating the need for custom cleanup scripts.

Check warning on line 105 in docs/usage/schedule-backup.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/usage/schedule-backup.md#L105 

[Vale.Spelling] Did you really mean 'storages'?
Raw output 
{"message": "[Vale.Spelling] Did you really mean 'storages'?", "location": {"path": "docs/usage/schedule-backup.md", "range": {"start": {"line": 105, "column": 65}}}, "severity": "WARNING"}

!!! admonition ""

Expand Down