PBM-1427 Documented how to clone collections (#225)

* PBM-1427 Documented how to clone collections modified: docs/features/selective-backup.md modified: docs/reference/pbm-commands.md modified: docs/usage/restore.md * Added PITR for cloned collections --------- Co-authored-by: Boris Ilijic <[email protected]>
percona · Dec 12, 2024 · 3d406df · 3d406df
1 parent d17b1f9
commit 3d406df
Show file tree

Hide file tree

Showing 3 changed files with 49 additions and 0 deletions.
diff --git a/docs/features/selective-backup.md b/docs/features/selective-backup.md
@@ -74,6 +74,32 @@ Consider these specifics of selective restore with users and roles:
 * Users and roles must be created in custom databases. For security considerations, users created in `admin`, `config` and `local` databases cannot be a part of a selective restore.
 * If users and roles exist in a database during the restore, they will be overwritten from the backup.
 
+## Restore a collection under a different name
+
+!!! admonition "Version added: [2.8.0](../release-notes/2.8.0.md)"
+
+You can restore a specific collection under a different name alongside the current collection up to a certain point in time. This is useful when you troubleshoot database issues and need to compare the data in both collections to identify what caused the database to misbehave. When you can see and edit the changes explicitly, you gain insight into your data and have confident control over it. As a result, your troubleshooting efforts significantly reduce.
+
+To see how it works, imagine the following use case:
+
+You have noticed that your e-commerce app returns incorrect or incomplete results on orders. You remember that everything was working fine yesterday, so it's likely that recent changes to the database caused the issue. 
+
+You have a backup and the oplog ranges that fully cover the previous day, 2024-11-15.
+
+To find out the issue, you can restore the `orders` collection under a different name up to the specified time alongside the current `orders` collection and compare them. You decide to restore to 14:00.
+
+```{.bash data-prompt="$"}
+$ pbm restore --time=2024-11-15T14:00:00 --ns-from=goods.orders --ns-to=goods.orders_prev
+```
+
+The `orders_prev` collection has the same data and indexes as the `orders` collection. It also has applied the same oplog operations as the `orders` collection allowing you to see exactly what has changed.
+
+Let's say you discover that the `status` field now includes an extra `date` field. These changes went unnoticed, and the app's code was not updated to handle them, leading to incorrect results. Now that you've identified the issue you can take necessary actions to fix it.
+
+!!! note 
+
+    In version 2.8.0, you can restore a single non-sharded collection in a replica set under a different name. The support for sharded and time series collections is planned for the future releases.
+
 
 [Make a backup](../usage/start-backup.md){ .md-button .md-button }
 [Restore a backup](../usage/restore.md){ .md-button .md-button }
diff --git a/docs/reference/pbm-commands.md b/docs/reference/pbm-commands.md
@@ -801,6 +801,8 @@ The command accepts the following flags:
 | `--with-users-and-roles` | Restores users and roles created in custom databases during selective restore. Use this flag with the `--ns` flag. Available starting with version 2.5.0.| 
 | `-c`, `--config`     | The path to the `mongod.conf` file |
 | `--num-parallel-collections`| Sets the number of collections to process in parallel during a specific logical restore. When undefined, `pbm-agent` processes the number of parallel collections defined for the `restore.numParallelCollections` configuration parameter. If that is undefined,  the default number of collections is the half of the number of logical CPUs. Available starting with version 2.7.0.|
+| `--ns-from`="database.collection" |Specifies the name of the collection you want to restore under a new name. It indicates the collection present in the backup that you are targeting for restoration. Available starting with version 2.8.0.|
+| `--ns-to`="database.collection" | Specifies the new name for the collection you are restoring from the original one. Available starting with version 2.8.0.|
 
 ??? "Restore output"
 

diff --git a/docs/usage/restore.md b/docs/usage/restore.md
@@ -297,6 +297,27 @@ To restore a backup, use the [`pbm restore`](../reference/pbm-commands.md#pbm-re
     $ pbm restore <backup_name> --ns <database.*> --with-users-and-roles
     ```
 
+    ### Restore a collection under a different name
+
+    You can restore a specific collection under a different name alongside the current collection. This is useful when you troubleshoot database issues and need to compare the data in both collections to identify the root of the issue.
+
+    Note that in version 2.8.0 you can restore a single collection and this collection must be unsharded. 
+
+    To restore a collection, pass the collection name from the backup for the `--ns-from` flag and the new name for the `--ns-to` flag:
+
+    ```{.bash data-prompt="$"}
+    $ pbm restore <backup_name> --ns-from <database.collection> --ns-to <database.collection_new>
+    ```
+
+    The new collection has the same data and indexes as the source collection. You must provide a unique name for the collection you restore, otherwise the restore fails.
+
+    You can restore a collection under a new name up to the specified time. Instead of the backup name, specify the timestamp, the source collection name and the new name as follows:
+
+    ```{.bash data-prompt="$"}
+    $ pbm restore --time=<timestamp> --ns-from <database.collection> --ns-to <database.collection_new>
+    ```
+
+
 === ":simple-databricks: Incremental"
 
     Restore flow from an incremental backup is the same as the restore from a full physical backup: specify the backup name for the `pbm restore` command: