PBM-1294 selective logical backup/restore with Users & Roles #337
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,103 +1,104 @@ | ||
| {# Custom layout extending Material Theme base #} | ||
| {% extends "base.html" %} | ||
|
|
||
| {% block scripts %} | ||
| <script src="https://cmp.osano.com/Azqe5vTyLOSbN3OuT/49ad85b5-0418-4794-ab81-7599dddd534c/osano.js"></script> | ||
| {{ 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 %} | ||
| <meta property="og:type" content="website" /> | ||
| <meta property="og:title" content="{{ title }}" /> | ||
| <meta property="og:image" content="https://docs.percona.com/percona-backup-mongodb/_images/mongodb.png" /> | ||
| <meta property="og:url" content="https://docs.percona.com/percona-backup-mongodb/" /> | ||
| {% endblock %} | ||
|
|
||
| {% block site_nav %} | ||
| {% if nav %} | ||
| {% if page.meta and page.meta.hide %} | ||
| {% set hidden = "hidden" if "navigation" in page.meta.hide %} | ||
| {% endif %} | ||
| <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" {{ hidden|default("") }}> | ||
| <div class="md-sidebar__scrollwrap"> | ||
| <div class="md-sidebar__inner"> | ||
| {% include "partials/nav.html" %} | ||
| <br> | ||
| <label class="md-nav__title" for="__drawer"> | ||
| <a href="https://learn.percona.com/download-percona-backup-for-mongodb-manual-2" | ||
| onclick="_gaq.push(['b._trackEvent', 'Percona Backup for MongoDB', 'Download', 'Download Manual Backup for MongoDB']);" | ||
| class="md-nav__link md-nav__link--active" | ||
| style="font-size: .7rem;"> | ||
| Download PDF | ||
| </a> | ||
| </label> | ||
| </div> | ||
| </div> | ||
| </div> | ||
| {% endif %} | ||
|
|
||
| {% if "toc.integrate" not in features %} | ||
| {% if page.meta and page.meta.hide %} | ||
| {% set hidden = "hidden" if "toc" in page.meta.hide %} | ||
| {% endif %} | ||
| <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" {{ hidden|default("") }}> | ||
| <div class="md-sidebar__scrollwrap"> | ||
| <div class="md-sidebar__inner"> | ||
| {% include "partials/rating.html" %} | ||
| </div> | ||
| <div class="md-sidebar__inner"> | ||
| {% include "partials/edit.html" %} | ||
| </div> | ||
| <div class="md-sidebar__inner"> | ||
| {% include "partials/banner.html" %} | ||
| </div> | ||
| <div class="md-sidebar__inner"> | ||
| {% include "partials/toc.html" %} | ||
| </div> | ||
| </div> | ||
| </div> | ||
| {% endif %} | ||
| {% endblock %} | ||
|
|
||
| {% block content %} | ||
| {{ super() }} | ||
|
|
||
| <script> | ||
| window.addEventListener('beforeprint', () => { | ||
| for (const detailEl of document.querySelectorAll('details')) { | ||
| if (detailEl.getAttribute('open') == null) { | ||
| detailEl.setAttribute('data-was-closed', 'true'); | ||
| } | ||
| detailEl.setAttribute('open', ''); | ||
| } | ||
| }); | ||
| window.addEventListener('afterprint', () => { | ||
| for (const detailEl of document.querySelectorAll('details')) { | ||
| if (detailEl.getAttribute('data-was-closed') != null) { | ||
| detailEl.removeAttribute('data-was-closed'); | ||
| detailEl.removeAttribute('open'); | ||
| } | ||
| } | ||
| }); | ||
| </script> | ||
|
|
||
| <script> | ||
| !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){ | ||
| function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]), | ||
| t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}} | ||
| (p=t.createElement("script")).type="text/javascript",p.async=!0, | ||
| p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r); | ||
| var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[], | ||
| u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e}, | ||
| u.people.toString=function(){return u.toString(1)+".people (stub)"}, | ||
| o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys onSessionId".split(" "), | ||
| n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]); | ||
| posthog.init('phc_7unoI9J6Fm0SMrfDp35xNOpCRTkOAibbffQwdGWbHnL',{api_host:'https://eu.posthog.com'}); | ||
| </script> | ||
| {% endblock %} |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -32,6 +32,62 @@ | |||||
| pbm restore <backup_name> --ns <database.*> --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. | ||||||
|
There was a problem hiding this comment. This is in the restore section, but it says 'include ... in your selective backup'. Suggest rewording to 'include ... in your selective restore' (or 'restore users and roles alongside the data') to avoid confusion.
Suggested change
|
||||||
|
|
||||||
| !!! 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. | ||||||
|
Check warning on line 44 in docs/usage/restore-selective.md
|
||||||
|
|
||||||
| To restore a specific namespace and include users and roles, run the following command: | ||||||
|
Check warning on line 46 in docs/usage/restore-selective.md
|
||||||
|
|
||||||
| ```sh | ||||||
| pbm restore --ns="mydb.*" --with-users-and-roles <backup-name> | ||||||
| ``` | ||||||
|
|
||||||
| where: | ||||||
|
|
||||||
| `--ns="mydb.*"` **→** Restores only the collections belonging to mydb. | ||||||
|
Check warning on line 54 in docs/usage/restore-selective.md
|
||||||
|
|
||||||
| `--with-users-and-roles` → Restores the database-defined users and roles alongside the data. | ||||||
|
|
||||||
| `<backup-name>` **→** The identifier of the backup to restore from (as shown in Percona Backup for MongoDB backup listings and logs). | ||||||
|
|
||||||
| **Namespace requirements** | ||||||
|
Check warning on line 60 in docs/usage/restore-selective.md
|
||||||
|
|
||||||
| The `--with-users-and-roles` flag requires a collection wildcard in the namespace. | ||||||
|
Check warning on line 62 in docs/usage/restore-selective.md
|
||||||
|
|
||||||
| 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. | ||||||
|
Check failure on line 66 in docs/usage/restore-selective.md
|
||||||
|
|
||||||
| ??? 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 | ||||||
rasika-chivate marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| ``` | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The restore page documents important constraints for
--with-users-and-roles(e.g., requiring a collection wildcard likemydb.*, excluding cluster/global users/roles, and overwrite behavior on restore). This backup page currently doesn’t call out the wildcard requirement or explicitly clarify the same scope limitation (db-scoped only). Suggest adding a short warning/note here for consistency so users don’t try--ns=\"db.collection\"or assume cluster-wide users/roles are included.