diff --git a/_resourcepdf/overrides/main.html b/_resourcepdf/overrides/main.html index cdc4c8a4..7d7031a5 100644 --- a/_resourcepdf/overrides/main.html +++ b/_resourcepdf/overrides/main.html @@ -1,103 +1,104 @@ -{# -MkDocs template for builds with Material Theme to customize docs layout -by adding marketing-requested elements -#} - -{# Import the theme's layout. #} -{% extends "base.html" %} +{# Custom layout extending Material Theme base #} +{% extends "base.html" %} {% block scripts %} - -{{ super() }} + + {{ super() }} {% endblock %} - {% block extrahead %} - {{ super() }} - {% set title = config.site_name %} - {% if page and page.meta and page.meta.title %} - {% set title = title ~ " - " ~ page.meta.title %} - {% elif page and page.title and not page.is_homepage %} - {% set title = title ~ " - " ~ page.title %} - {% endif %} - - - - - - - - - {% endblock %} - - - {% block site_nav %} - {% if nav %} - {% if page.meta and page.meta.hide %} - {% set hidden = "hidden" if "navigation" in page.meta.hide %} - {% endif %} - - {% endif %} - {% if "toc.integrate" not in features %} - {% if page.meta and page.meta.hide %} - {% set hidden = "hidden" if "toc" in page.meta.hide %} - {% endif %} - - {% endif %} - {% endblock %} +{% block extrahead %} + {{ super() }} + {% set title = config.site_name %} + {% if page and page.meta and page.meta.title %} + {% set title = title ~ " - " ~ page.meta.title %} + {% elif page and page.title and not page.is_homepage %} + {% set title = title ~ " - " ~ page.title %} + {% endif %} + + + + +{% endblock %} - {% block content%} +{% block site_nav %} + {% if nav %} + {% if page.meta and page.meta.hide %} + {% set hidden = "hidden" if "navigation" in page.meta.hide %} + {% endif %} +
+
+
+ {% include "partials/nav.html" %} +
+ +
+
+
+ {% endif %} - {{ super() }} + {% if "toc.integrate" not in features %} + {% if page.meta and page.meta.hide %} + {% set hidden = "hidden" if "toc" in page.meta.hide %} + {% endif %} +
+
+
+ {% include "partials/rating.html" %} +
+
+ {% include "partials/edit.html" %} +
+
+ {% include "partials/banner.html" %} +
+
+ {% include "partials/toc.html" %} +
+
+
+ {% endif %} +{% endblock %} - +{% block content %} + {{ super() }} - + - {% endblock %} + +{% endblock %} diff --git a/docs/usage/backup-selective.md b/docs/usage/backup-selective.md index 3ad9b659..ed65cd1f 100644 --- a/docs/usage/backup-selective.md +++ b/docs/usage/backup-selective.md @@ -26,6 +26,50 @@ During the backup process, Percona Backup for MongoDB stores data in the new mul Multi-format is the default data format for both full and selective backups since it allows selective restore. Note, however, that you can make only full restores from backups made with earlier versions of Percona Backup for MongoDB. +## Selective backup with users and roles + +### Overview + +Percona Backup for MongoDB enables you to perform selective backups of databases and collections. Also, you can choose to include **users and roles defined** in the database in your selective backup, ensuring that access control is restored along with the data. + +To back up a specific namespace and include users and roles, run the following command: + + +```sh +pbm backup --ns="mydb.*" --with-users-and-roles +``` + +where: + +`--ns="mydb.*"` **→** specifies the namespace (all collections in `mydb`). + +`--with-users-and-roles` **→** includes all users and custom roles defined in `mydb` in the backup. + +??? info "What happens under the hood?" + - Percona Backup for MongoDB captures all collections within `mydb`. + - Percona Backup for MongoDB filters the users and roles for entities where the `db` field matches `mydb`. + - Global administrative roles or users defined in other databases are excluded. + + +**Example** + +```sh +pbm backup --ns="invoices.*" --with-users-and-roles +``` + +This command backs up all collections in the **invoices** database, along with its users and roles. + +### Use cases + +=== "Partial migration of a database" + As applications scale, migrating a specific database from a shared cluster to a dedicated cluster becomes necessary. Using the `--with-users-and-roles` flag ensures that the destination cluster inherits the application-specific users and custom roles immediately, thereby preventing errors post-migration. + + +=== "Staging environment" + To reproduce production issues or validate security patches, you need a staging environment that mirrors production exactly. + + By backing up `mydb` together with its users and roles, the copy reflects not only the data but also the access-control model. This enables accurate reproduction of permission-related behavior such as read/write restrictions, role grants, and user privileges. + ## Next steps diff --git a/docs/usage/restore-selective.md b/docs/usage/restore-selective.md index 8450f9db..17baf8d0 100644 --- a/docs/usage/restore-selective.md +++ b/docs/usage/restore-selective.md @@ -32,6 +32,62 @@ To restore a [custom database with users and roles](../features/selective-backup pbm restore --ns --with-users-and-roles ``` +### Selective restore with users and roles + +#### Overview + +Percona Backup for MongoDB allows you to perform selective restore of databases and collections. Additionally, you can choose to include **users and roles defined** in the database in your selective backup, ensuring that access control is restored along with the data. + +!!! warning + - The `--with-users-and-roles` flag applies only to users and roles defined within the database being backed up or restored. Global users and roles defined at the cluster level **are not included**. + - If applications rely on roles or privileges that span multiple databases, a selective restore of a single database may not fully reestablish access control. Always verify dependencies before restore. + - Restoring users and roles will overwrite existing definitions in the target database. Review current role configurations before restore to avoid accidental loss of custom changes. + +To restore a specific namespace and include users and roles, run the following command: + +```sh +pbm restore --ns="mydb.*" --with-users-and-roles +``` + +where: + +`--ns="mydb.*"` **→** Restores only the collections belonging to mydb. + +`--with-users-and-roles` → Restores the database-defined users and roles alongside the data. + +`` **→** The identifier of the backup to restore from (as shown in Percona Backup for MongoDB backup listings and logs). + +**Namespace requirements** + +The `--with-users-and-roles` flag requires a collection wildcard in the namespace. + +For example, `--ns="test.*"` is valid, but `--ns="test.col"` is not valid. + +Use `--with-users-and-roles` only with selective restore (i.e., when you specify `--ns`). If you are not using `--ns`, you are not performing a selective restore, and this option is not required. + +??? info "What happens under the hood?" + - Percona Backup for MongoDB restores the selected collections within `mydb` from the specified backup. + - Percona Backup for MongoDB restores roles where the db field matches `mydb`. + - Percona Backup for MongoDB restores users where the db field matches `mydb`, including their role assignments within `mydb`. + +**Example** + +```sh +pbm restore --ns="invoices.*" --with-users-and-roles 2025-03-10T10:44:52Z +``` + +This command restores all collections in the `invoices` database, along with the users and roles defined in `invoices`, from the backup `2025-03-10T10:44:52Z`. + +#### Use cases + +=== "Partial restore after data loss" + A service using `mydb` experienced accidental deletes or corruption, while other databases in the cluster remain unaffected. Selective restore limits recovery to only the required database. + +=== "Roll back access control changes" + A recent modification to custom roles in `mydb` introduced permission failures. Applications that rely on those roles can no longer perform required operations. + + To ensure complete recovery, you need to restore not only the data but also the users and roles tied to the database’s access controls. + ### 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. diff --git a/mkdocs-base.yml b/mkdocs-base.yml index 6b39dc6b..d88c9dcc 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -4,7 +4,7 @@ site_name: Percona Backup for MongoDB site_description: documentation site_author: Percona LLC copyright: > - Percona LLC and/or its affiliates © 2025 + Percona LLC and/or its affiliates © 2026 — Cookie Preferences repo_name: percona/pbm-docs repo_url: https://github.com/percona/pbm-docs