PBM-1141 Documented deleted backup by type

docs/reference/pbm-commands.md

@@ -147,7 +147,7 @@ The command accepts the following flags:
 
 ## pbm delete-backup
 
-Deletes the specified backup snapshot or all backup snapshots that are older than the specified time. The command deletes backups that are not running regardless of the remote backup storage being used.
+Deletes the specified backup snapshot or all backup snapshots that are older than the specified time with the option to filter by specific type. The command deletes backups that are not running regardless of the remote backup storage being used.
 
 The following is the command syntax:
 
@@ -159,9 +159,11 @@ 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) or <br> - `%Y-%M-%D` (e.g. 2020-04-20)|
-| `--force`                | Forcibly deletes backups without asking for user's confirmation  |
-| `--yes`                  | Deletes backups without asking for user's confirmation |
+| `--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)|
+| `--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 |
+| `--dry-run`              | Prints the list of backup snapshots to be deleted without deleting them. You can use the flag to check what exactly will be deleted. Available starting with version 2.4.0. | 
 
 ## pbm delete-pitr
 
@@ -177,11 +179,13 @@ The command accepts the following flags:
 
 | Flag                     | Description               |
 | ------------------------ | ------------------------- |
-| `-a`, `--all`            | Deletes all oplog         |
+| `-a`, `--all`            | Deletes all oplog slices. Deprecated. Use the `--older-than flag instead`  |
 | `--older-than=TIMESTAMP` | Deletes oplog slices older than date / time specified in the format: <br> - `%Y-%M-%DT%H:%M:%S` (e.g. 2020-04-20T13:13:20) or <br> - `%Y-%M-%D` (e.g. 2020-04-20) <br><br> When you specify a timestamp, Percona Backup for MongoDB rounds it down to align with the completion time of the closest backup snapshot and deletes oplog slices that precede this time. Thus, extra slices remain. This is done to ensure oplog continuity. To illustrate, the PITR time range is `2021-08-11T11:16:21 - 2021-08-12T08:55:25` and backup snapshots are: <br><br> `2021-08-12T08:49:46Z 13.49MB [restore_to_time: 2021-08-12T08:50:06]` <br> `2021-08-11T11:36:17Z 7.37MB [restore_to_time: 2021-08-11T11:36:38]`<br> <br> Say you specify the timestamp `2021-08-11T19:16:21`. The closest backup is `2021-08-11T11:36:17Z 7.37KB [restore_to_time: 2021-08-11T11:36:38]`. PBM rounds down the timestamp to `2021-08-11T11:36:38` and deletes all slices that precede this time. As a result, your PITR time range is `2021-08-11T11:36:38 - 2021-08-12T09:00:25`. <br><br> **NOTE**: Percona Backup for MongoDB doesn’t delete the oplog slices that follow the most recent backup. This is done to ensure point in time recovery from that backup snapshot. For example, if the snapshot is `2021-07-20T07:05:23Z [restore_to_time: 2021-07-21T07:05:44]` and you specify the timestamp `2021-07-20T07:05:45`, Percona Backup for MongoDB deletes only slices that were made before `2021-07-20T07:05:23Z`.|
-| `--force`                | Forcibly deletes oplog slices without asking a user’s confirmation  |
+| `--force`                | Forcibly deletes oplog slices without asking a user’s confirmation. Deprecated. Use the `-y`/`--yes` flag instead.  |
 | `-o`, `--out=json`       | Shows the output as either the plain text (default) or a JSON object. Supported values: `text`, `json`.   |
 | `--yes`                  | Deletes backups without asking for user's confirmation |
+| `--dry-run`              | Prints the list of oplog slices to be deleted without deleting them. You can use the flag to check what exactly will be deleted. Available starting with version 2.4.0. | 
+| `-w`, `--wait`          | Wait for the deletion operation to complete. |
 
 ## pbm describe-backup
 

docs/usage/delete-backup.md

@@ -93,28 +93,40 @@ Here's how the cleanup works:
 
 1. You can only delete a backup that is not running (has the “done” or the “error” state). To check the backup state, run the [`pbm status`](../reference/pbm-commands.md#pbm-status) command.
 
-2. To ensure oplog continuity for [point-in-time restore](pitr-tutorial.md), the `pbm delete-backup` command deletes any backup(s) except the following:
+2. You can only delete the whole incremental backup chain, not a single increment. When you specify the increment name of the timestamp for a single increment, the backup deletion fails. 
 
-    * A backup snapshot that can serve as the base for any point-in-time recovery and has point-in-time recovery time ranges deriving from it. To delete such a backup, first [delete the oplog slices](#delete-oplog-slices) that are created  after the `restore-to time` value for this backup.
+3. To ensure oplog continuity for [point-in-time restore](pitr-tutorial.md), the `pbm delete-backup` command deletes any backup(s) except the following:
 
-    * The most recent backup if point-in-time recovery is enabled and there are no oplog slices following this backup yet.
+    === "Version 2.4.0 and higher"
 
-    To illustrate this, let’s take the following `pbm list` output:
+        The most recent backup snapshot (logical, physical, base incremental) that can serve as the base for point-in-time recovery, if it is enabled. 
 
-    ```{.bash .no-copy}
-    Backup snapshots:
-      2022-10-05T14:13:50Z <logical> [restore_to_time: 2022-10-05T14:13:55Z]
-      2022-10-06T14:52:42Z <logical> [restore_to_time: 2022-10-06T14:52:47Z]
-      2022-10-07T14:57:17Z <logical> [restore_to_time: 2022-10-07T14:57:22Z]
 
-    PITR <on>:
-      2022-10-05T14:13:56Z - 2022-10-05T18:52:21Z
-    ```
+    === "Version 2.3.1 and earlier"
+
+        * A backup snapshot that can serve as the base for any point-in-time recovery and has point-in-time recovery time ranges deriving from it. To delete such a backup, first [delete the oplog slices](#delete-oplog-slices) that are created  after the `restore-to time` value for this backup.    
+
+        * The most recent backup if point-in-time recovery is enabled and there are no oplog slices following this backup yet.    
+
+        To illustrate this, let’s take the following `pbm list` output:    
+
+        ```{.bash .no-copy}
+        Backup snapshots:
+          2022-10-05T14:13:50Z <logical> [restore_to_time: 2022-10-05T14:13:55Z]
+          2022-10-06T14:52:42Z <logical> [restore_to_time: 2022-10-06T14:52:47Z]
+          2022-10-07T14:57:17Z <logical> [restore_to_time: 2022-10-07T14:57:22Z]    
+
+        PITR <on>:
+          2022-10-05T14:13:56Z - 2022-10-05T18:52:21Z
+        ```    
+
+        You can delete a backup `2022-10-06T14:52:42Z` since it has no point-in-time oplog slices. You cannot delete the following backups:    
 
-    You can delete a backup `2022-10-06T14:52:42Z` since it has no point-in-time oplog slices. You cannot delete the following backups:
+        - `2022-10-05T14:13:50Z` because it is the base for recovery to any point in time from the PITR time range `2022-10-05T14:13:56Z - 2022-10-05T18:52:21Z`
+        - `2022-10-07T14:57:17Z` because PITR is enabled and there are no oplog slices following it yet.
+
+4. Starting with version 2.0.4, you can delete any backup snapshot (except the most recent one with point-in-time recovery enabled) regardless the point-in-time recovery slices deriving from it. Such slices are then marked as "no base backup" in the `pbm status` output. 
 
-    - `2022-10-05T14:13:50Z` because it is the base for recovery to any point in time from the PITR time range `2022-10-05T14:13:56Z - 2022-10-05T18:52:21Z`
-    - `2022-10-07T14:57:17Z` because PITR is enabled and there are no oplog slices following it yet.
 
 ### Behavior
 
@@ -166,11 +178,64 @@ You can delete either a specified backup snapshot or all backup snapshots older
       2021-04-21T02:16:33Z
     ```
 
-By default, the ``pbm delete-backup`` command asks for your confirmation to proceed with the deletion. To bypass it, add the `-f` or
- `--force` flag.
+
+=== "Specific types of backups"
+
+    To delete backups of a specific type that were created before the specified time, run the `pbm delete backup` with the `--type` and the `--older-than` flags. PBM deletes all backups that don't serve as the base for restore to the specified timestamp.
+
+    Note that you must specify both flags to delete backups of the desired type.
+
+
+    #### Example
+
+    You have the following list of backups:
+
+    ```{.text .no-copy}
+    Backups:
+      Snapshots:
+        2024-02-26T10:11:05Z 905.92MB <physical> [restore_to_time: 2024-02-26T10:11:07Z]
+        2024-02-26T10:06:57Z 86.99MB <logical> [restore_to_time: 2024-02-26T10:07:00Z]
+        2024-02-26T10:03:24Z 234.12MB <incremental> [restore_to_time: 2024-02-26T10:03:26Z]
+        2024-02-26T10:00:16Z 910.27MB <incremental, base> [restore_to_time: 2024-02-26T10:00:18Z]
+        2024-02-26T09:56:18Z 961.68MB <physical> [restore_to_time: 2024-02-26T09:56:20Z]
+        2024-02-26T08:43:44Z 86.83MB <logical> [restore_to_time: 2024-02-26T08:43:47Z]
+      PITR chunks [8.25MB]:
+        2024-02-26T08:43:48Z - 2024-02-26T10:17:21Z
+    ```
+
+    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
+    ```
+
+    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:
+
+    ```{.text .no-copy}
+    Snapshots:
+     - "2024-02-26T09:56:18Z" [size: 961.68MB type: <physical>, restore time: 2024-02-26T09:56:20Z]
+    Waiting for delete to be done .[done]
+    ```
+
+    The resulting list of backups looks like this:
+
+    ```{.text .no-copy}
+    Backups:
+      Snapshots:
+        2024-02-26T10:11:05Z 905.92MB <physical> [restore_to_time: 2024-02-26T10:11:07Z]
+        2024-02-26T10:06:57Z 86.99MB <logical> [restore_to_time: 2024-02-26T10:07:00Z]
+        2024-02-26T10:03:24Z 234.12MB <incremental> [restore_to_time: 2024-02-26T10:03:26Z]
+        2024-02-26T10:00:16Z 910.27MB <incremental, base> [restore_to_time: 2024-02-26T10:00:18Z]
+        2024-02-26T08:43:44Z 86.83MB <logical> [restore_to_time: 2024-02-26T08:43:47Z]
+      PITR chunks [8.73MB]:
+        2024-02-26T08:43:48Z - 2024-02-26T10:17:21Z
+    ```
+
+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 data-prompt="$"}
- $ pbm delete-backup --force 2021-04-20T13:45:59Z
+ $ pbm delete-backup --yes 2023-04-20T13:45:59Z
  ```
 
 !!! admonition ""

docs/usage/schedule-backup.md

@@ -84,7 +84,9 @@ Previous backups are not automatically removed from the backup storage. You need
 
 !!! admonition "Version added: [2.1.0](../release-notes/2.1.0.md)"
 
-Starting with version 2.1.0, you can use the `pbm cleanup --older-than` command to delete outdated backup snapshots and point-in-time recovery oplog slices. You can configure a `cron` task to automate storage cleanup by specifying the following command in the `crontab` file:
+Starting with version 2.1.0, you can use the [`pbm cleanup --older-than`](../reference/pbm-commands.md#pbm-cleanup) command to delete outdated backup snapshots and point-in-time recovery oplog slices. Learn more about how PBM deletes outdated data in the [Clean up outdated data](delete-backup.md#clean-up-outdated-data) section.
+
+You can configure a `cron` task to automate storage cleanup by specifying the following command in the `crontab` file:
 
 ```{.bash data-prompt="$"}
 $ $ /usr/bin/pbm cleanup -y --older-than 30d --wait

mkdocs-base.yml

@@ -175,7 +175,7 @@ nav:
         - install/backup-storage.md
         - install/start-pbm-agent.md
   - Backup and restore:
-      - Via the command line:
+#      - Via the command line:
         - Make a backup : "usage/start-backup.md"
         - Restore a backup: usage/restore.md
         - Make a point-in-time restore: usage/pitr-tutorial.md
@@ -187,7 +187,7 @@ nav:
         - usage/restore-progress.md
         - usage/oplog-replay.md 
         - usage/logs.md 
-      - Via web interface:
+#      - Via web interface:
         - Backup management via PMM: pmm.md 
   - Administer PBM:
       - 'Overview': manage/overview.md