From 018fba4ce0a52baed604ce34d4279253067e4491 Mon Sep 17 00:00:00 2001 From: Allison Moore Date: Fri, 30 Sep 2016 14:26:29 -0400 Subject: [PATCH] DOCS-8118: add new namespace options to mongorestore --- .../extracts-mongorestore-ns-pattern.yaml | 64 +++++++++++++ source/includes/options-mongorestore.yaml | 88 ++++++++++++++++++ source/reference/program/mongorestore.txt | 89 ++++++++++++++++++- 3 files changed, 240 insertions(+), 1 deletion(-) create mode 100644 source/includes/extracts-mongorestore-ns-pattern.yaml diff --git a/source/includes/extracts-mongorestore-ns-pattern.yaml b/source/includes/extracts-mongorestore-ns-pattern.yaml new file mode 100644 index 00000000000..7c3280d036a --- /dev/null +++ b/source/includes/extracts-mongorestore-ns-pattern.yaml @@ -0,0 +1,64 @@ +ref: _ns-pattern-simple +content: | + {{role}} accepts a *namespace pattern* as its argument. The namespace + pattern permits {{role}} to refer to any namespace that matches the + specified pattern. {{program}} matches the smallest valid occurence + of the namespace pattern. + + Use asterisks (``*``) as wild cards. Escape all literal asterisks + and backslashes with a backslash. :ref:`example-basic-wildcard-usage` + provides an example of using asterisks as wild cards. +--- +ref: ns-pattern-simple-include +inherit: + ref: _ns-pattern-simple + file: extracts-mongorestore-ns-pattern.yaml +replacement: + role: ":option:`--nsInclude`" + program: ":program:`mongorestore`" +--- +ref: ns-pattern-simple-exclude +inherit: + ref: _ns-pattern-simple + file: extracts-mongorestore-ns-pattern.yaml +replacement: + role: ":option:`--nsExclude`" + program: ":program:`mongorestore`" +--- +ref: _ns-pattern-complex +content: | + {{role}} accepts a *namespace pattern* as its argument. The namespace + pattern permits {{role}} to refer to any namespace that matches the + specified pattern. {{program}} matches the smallest valid occurence + of the namespace pattern. + + For simple replacements, use asterisks (``*``) as wild cards. + Escape all literal asterisks and backslashes with a backslash. + Replacements correspond linearly to matches: each asterisk in + ``--nsFrom`` must correspond to an asterisk in ``--nsTo``, and the + first asterisk in ``--nsFrom`` matches the first asterisk in ``nsTo``. + + For more complex replacements, use dollar signs to delimit a "wild + card" variable to use in the replacement. + :ref:`example-complex-wildcard-usage` provides an example of complex + replacements with dollar sign-delimited wild cards. + + Unlike replacements with asterisks, replacements with dollar + sign-delimited wild cards do **not** need to be linear. +--- +ref: ns-pattern-complex-from +inherit: + ref: _ns-pattern-complex + file: extracts-mongorestore-ns-pattern.yaml +replacement: + role: ":option:`--nsFrom`" + program: ":program:`mongorestore`" +--- +ref: ns-pattern-complex-to +inherit: + ref: _ns-pattern-complex + file: extracts-mongorestore-ns-pattern.yaml +replacement: + role: ":option:`--nsTo`" + program: ":program:`mongorestore`" +... \ No newline at end of file diff --git a/source/includes/options-mongorestore.yaml b/source/includes/options-mongorestore.yaml index 3327d8851e5..af367da2427 100644 --- a/source/includes/options-mongorestore.yaml +++ b/source/includes/options-mongorestore.yaml @@ -415,4 +415,92 @@ inherit: file: options-shared.yaml replacement: verb: "insert" +--- +program: mongorestore +name: nsExclude +directive: option +args: +pre: | + .. versionadded:: 3.4 + +description: | + Excludes the specified :term:`namespaces ` from the + restore operation. +post: | + .. include:: /includes/extracts/ns-pattern-simple-exclude.rst +optional: true +--- +program: mongorestore +name: nsInclude +directive: option +args: +pre: | + .. versionadded:: 3.4 + +description: | + Includes only the specified :term:`namespaces ` in the + restore operation. + By enabling you to specify multiple collections to restore, + {{role}} offers a superset of the functionality of the + :option:`--collection` option. +optional: true +post: | + .. include:: /includes/extracts/ns-pattern-simple-include.rst +--- +program: mongorestore +name: nsFrom +directive: option +args: +pre: | + .. versionadded:: 3.4 + +description: | + Use with :option:`--nsTo` to rename a :term:`namespace` during the + restore operation. {{role}} specifies the collection in the + dump file, while :option:`--nsTo` specifies the name that should be + used in the restored database. +optional: true +post: | + .. include:: /includes/extracts/ns-pattern-complex-from.rst +--- +program: mongorestore +name: nsTo +directive: option +args: +pre: | + .. versionadded:: 3.4 + +description: | + Use with :option:`--nsFrom` to rename a :term:`namespace` during the + restore operation. {{role}} specifies the new collection + name to use in the restored database, while + :option:`--nsFrom` specifies the name in the dump file. +optional: true +post: | + .. include:: /includes/extracts/ns-pattern-complex-to.rst +--- +program: mongorestore +name: oplogFile +directive: option +args: +pre: | + .. versionadded:: 3.4 + +description: | + Specifies the path to the oplog file containing oplog data for the + restore. +optional: true +--- +program: mongorestore +name: dryRun +directive: option +args: null +pre: | + .. versionadded:: 3.4 + +description: | + Runs {{program}} without actually importing any data, returning the + {{program}} summary information. Use with ``--verbose`` to produce + more detailed summary information. +optional: true ... diff --git a/source/reference/program/mongorestore.txt b/source/reference/program/mongorestore.txt index a507e18b5ed..0f229b07e02 100644 --- a/source/reference/program/mongorestore.txt +++ b/source/reference/program/mongorestore.txt @@ -129,14 +129,26 @@ Options .. include:: /includes/option/option-mongorestore-collection.rst +.. include:: /includes/option/option-mongorestore-nsExclude.rst + +.. include:: /includes/option/option-mongorestore-nsInclude.rst + +.. include:: /includes/option/option-mongorestore-nsFrom.rst + +.. include:: /includes/option/option-mongorestore-nsTo.rst + .. include:: /includes/option/option-mongorestore-objcheck.rst .. include:: /includes/option/option-mongorestore-drop.rst +.. include:: /includes/option/option-mongorestore-dryRun.rst + .. include:: /includes/option/option-mongorestore-oplogReplay.rst .. include:: /includes/option/option-mongorestore-oplogLimit.rst +.. include:: /includes/option/option-mongorestore-oplogFile.rst + .. include:: /includes/option/option-mongorestore-keepIndexVersion.rst .. include:: /includes/option/option-mongorestore-noIndexRestore.rst @@ -177,7 +189,7 @@ Consider the following example: .. code-block:: sh - mongorestore --collection people --db accounts dump/accounts/people.bson + mongorestore --collection people --db accounts dump/ Here, :program:`mongorestore` reads the database dump in the ``dump/`` sub-directory of the current directory, and restores *only* the @@ -185,6 +197,81 @@ documents in the collection named ``people`` from the database named ``accounts``. :program:`mongorestore` restores data to the instance running on the localhost interface on port ``27017``. +.. versionadded:: 3.4 + +You may alternatively use :option:`--nsInclude` to specify the +canonical name of the collection that you wish to restore rather than +:option:`--collection`. :option:`--nsInclude` enables you to specify +the :term:`namespace` of one or more collections that you +wish to include in the restore operation. The following example +restores the ``people`` collection from the ``accounts`` database +in the ``dump/`` sub-directory of the current directory: + +.. code-block:: sh + + mongorestore --nsInclude accounts.people dump/ + +.. _example-basic-wildcard-usage: + +Restore Collections Using Wild Cards +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 3.4 + +:option:`--nsInclude` and :option:`--nsExclude` support specifying +the :term:`namespaces ` you wish to include or exclude from a restore operation +using asterisks as *wild cards*. + +The following example restores the documents in the ``dump/`` +sub-directory of the current directory that match the specified +namespace pattern. The :option:`--nsInclude` statement specifies to +only restore documents in the ``transactions`` database while +:option:`--nsExclude` instructs :program:`mongorestore` to exclude +collections whose names end with ``_dev``. :program:`mongorestore` +restores data to the :program:`mongod` instance running on the +localhost interface on port ``27017``. + +.. code-block:: sh + + mongorestore --nsInclude 'transactions.*' --nsExclude 'transactions.*_dev' dump/ + +.. _example-complex-wildcard-usage: + +Change Collections' Namespaces during Restore +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 3.4 + +MongoDB 3.4 added the :option:`--nsFrom` and :option:`--nsTo` options, +which enable you to change the namespace of a collection that you are +restoring. :option:`--nsFrom` and :option:`--nsTo` support using +asterisks as wild cards *and* support using dollar signs to delimit +"wild card" variables to use in the replacement. + +Consider a database ``data`` that you have exported to a ``dump/`` +directory using :program:`mongodump`. The ``data`` database contains the following +collections: + +- ``sales_customer1`` +- ``sales_customer2`` +- ``sales_customer3`` +- ``users_customer1`` +- ``users_customer2`` +- ``users_customer3`` + +Using :option:`--nsFrom` and :option:`--nsTo`, you can restore the data +into different namespaces. The following operation + +- restores the ``sales_`` collections in the ``data`` database to + ```` collections in the ``sales`` database, and + +- restores the ``users_`` collections to ```` + collections in the ``users`` database. + +.. code-block:: sh + + mongorestore --nsInclude 'data.*' --nsFrom 'data.$prefix$_$customer$' --nsTo '$customer$.$prefix$' + Restore with Access Control ~~~~~~~~~~~~~~~~~~~~~~~~~~~