From 5765688e5e3ad347c9d792e7ff09032f17e64192 Mon Sep 17 00:00:00 2001 From: Dave Cuthbert Date: Tue, 6 Apr 2021 14:40:17 -0400 Subject: [PATCH] DOCSP-15480 direct to mongosh docs from legacy landing page --- source/mongo.txt | 428 +-------------------- source/release-notes/5.0-compatibility.txt | 14 + source/release-notes/5.0.txt | 74 ++-- 3 files changed, 70 insertions(+), 446 deletions(-) diff --git a/source/mongo.txt b/source/mongo.txt index 412eb604bea..c24fc05ce4c 100644 --- a/source/mongo.txt +++ b/source/mongo.txt @@ -4,417 +4,26 @@ The ``mongo`` Shell .. default-domain:: mongodb -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -The :binary:`~bin.mongo` shell is an interactive JavaScript interface to -MongoDB. You can use the :binary:`~bin.mongo` shell to query and update -data as well as perform administrative operations. - -.. include:: /includes/fact-mongosh-callout.rst - -Download the ``mongo`` Shell ----------------------------- - -.. include:: /includes/fact-download-mongo-shell.rst - -Start the ``mongo`` Shell and Connect to MongoDB ------------------------------------------------- - -Once you have downloaded the :binary:`~bin.mongo` shell, you can use it -to connect to your running MongoDB server. - .. note:: - .. include:: /includes/extracts/4.2-changes-mongoshell-emulation.rst - -Prerequisites -~~~~~~~~~~~~~ - -- The MongoDB server must be installed and running before you can - connect to it from the :binary:`~bin.mongo` shell. Follow the steps in - the :doc:`installation tutorial for your platform ` - to install and start the MongoDB server if required. - -- Once you have verified that the :binary:`~bin.mongod` server is - running, open a terminal window (or a command prompt for Windows) and - go to your ```` directory: - - .. code-block:: bash - - cd - - .. tip:: - - Adding your ```` to the ``PATH`` - environment variable allows you to type ``mongo`` directly instead - of having to first go to the ```` - directory or specify the full path to the binary. Alternatively, you - can copy the ``mongo`` shell to a location on your filesystem that - is already present in your ``PATH``, such as ``/usr/bin`` on Linux. - -macOS Security Verification -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*For macOS users:* - -.. include:: /includes/extracts/macos-prevent-launch-mongo.rst - -Local MongoDB Instance on Default Port -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can run :binary:`~bin.mongo` shell without any command-line options -to connect to a :doc:`MongoDB ` instance -running on your **localhost** with **default port** 27017: - -.. code-block:: bash - - mongo - -Local MongoDB Instance on a Non-default Port -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To explicitly specify the port, include the :option:`--port ` command-line option. For example, to connect to a MongoDB -instance running on localhost with a non-default port 28015: - -.. code-block:: bash - - mongo --port 28015 - -MongoDB Instance on a Remote Host -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To explicitly specify the hostname and/or port, - -- You can specify a :doc:`connection string - `. For example, to connect to a MongoDB - instance running on a remote host machine: - - .. code-block:: bash - - mongo "mongodb://mongodb0.example.com:28015" - -- You can use the command-line option :option:`--host \:\ - `. For example, to connect to a MongoDB instance - running on a remote host machine: - - .. code-block:: bash - - mongo --host mongodb0.example.com:28015 - -- You can use the :option:`--host \ ` and - :option:`--port \ ` command-line options. For - example, to connect to a MongoDB instance running on a remote host - machine: - - .. code-block:: bash - - mongo --host mongodb0.example.com --port 28015 - -MongoDB Instance with Authentication -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To connect to a MongoDB instance requires authentication: - -- You can specify the username, authentication database, and optionally - the password in the :doc:`connection string - `. For example, to connect and - authenticate to a remote MongoDB instance as user ``alice``: - - .. note:: - - If you do not specify the password in the connection string, the - shell will prompt for the password. - - .. code-block:: bash - - mongo "mongodb://alice@mongodb0.examples.com:28015/?authSource=admin" - -- You can use the :option:`--username \ ` and - :option:`--password `, - :option:`--authenticationDatabase \ ` command-line options. For example, to - connect and authenticate to a remote MongoDB instance as user - ``alice``: - - .. note:: - - If you specify ``--password`` without the user's password, the - shell will prompt for the password. - - .. code-block:: bash - - mongo --username alice --password --authenticationDatabase admin --host mongodb0.examples.com --port 28015 - -Connect to a MongoDB Replica Set -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To connect to a replica set: - -- You can specify the replica set name and members in the - :doc:`connection string `. - - .. code-block:: bash - - mongo "mongodb://mongodb0.example.com.local:27017,mongodb1.example.com.local:27017,mongodb2.example.com.local:27017/?replicaSet=replA" - -- If using the :ref:`connections-dns-seedlist`, you can specify the - connection string: - - .. code-block:: bash - - mongo "mongodb+srv://server.example.com/" - - .. note:: - - Use of the ``+srv`` connection string modifier automatically sets - the ssl option to true for the connection. - -- You can specify the replica set name and members from the - :option:`--host \/\:\,\:\,... ` - command-line option. For example, to connect to replica set named - ``replA``: - - .. code-block:: bash - - mongo --host replA/mongodb0.example.com.local:27017,mongodb1.example.com.local:27017,mongodb2.example.com.local:27017 - -TLS/SSL Connection -~~~~~~~~~~~~~~~~~~ - -For TLS/SSL connections, - -- You can specify the ``ssl=true`` option in the - :doc:`connection string `. - - .. code-block:: bash - - mongo "mongodb://mongodb0.example.com.local:27017,mongodb1.example.com.local:27017,mongodb2.example.com.local:27017/?replicaSet=replA&ssl=true" - -- If using the :ref:`connections-dns-seedlist`, you can include the - ``+srv`` connection string modifier: + The ``mongo`` shell has been deprecated in MongoDB v5.0. The + replacement is :mongosh:`mongosh `. - .. code-block:: bash + Older ``mongo`` shell documentation is included with the + corresponding documentation for that ``MongoDB`` release. - mongo "mongodb+srv://server.example.com/" + *Quick Links to prior versions* - .. note:: - - Use of the ``+srv`` connection string modifier automatically sets - the ssl option to true for the connection. + - :v4.4:`mongo shell v4.4 ` + - :v4.2:`mongo shell v4.2 ` + - :v4.0:`mongo shell v4.0 ` -- You can specify :option:`--ssl ` command-line option. - For example, to connect to replica set named ``replA``: - - .. code-block:: bash - - mongo --ssl --host replA/mongodb0.example.com.local:27017,mongodb1.example.com.local:27017,mongodb2.example.com.local:27017 - - -.. seealso:: - - For more information on the options used in the connection examples - as well as other options, see :doc:`mongo reference - ` and :ref:`examples of starting up mongo - `. - -.. _mongo-shell-executing-queries: - -Working with the ``mongo`` Shell --------------------------------- - -To display the database you are using, type ``db``: - -.. code-block:: bash - - db - -The operation should return ``test``, which is the default database. - -To switch databases, issue the ``use `` helper, as in the -following example: - -.. code-block:: javascript - - use - -See also :method:`db.getSiblingDB()` method to access a -different database from the current database without switching your -current database context (i.e. ``db``). - -To list the databases available to the user, use the helper ``show -dbs``. [#access]_ - -You can switch to non-existing databases. When you first store data in -the database, such as by creating a collection, MongoDB creates the -database. For example, the following creates both the database -``myNewDatabase`` and the :term:`collection` ``myCollection`` during -the :method:`~db.collection.insertOne()` operation: - -.. code-block:: javascript - - use myNewDatabase - db.myCollection.insertOne( { x: 1 } ); - -The :method:`db.myCollection.insertOne() ` is one -of the :doc:`methods available in the mongo shell `. - -- ``db`` refers to the current database. - -- ``myCollection`` is the name of the collection. - -If the :binary:`~bin.mongo` shell does not accept the name of a collection, -you can use the alternative :method:`db.getCollection()` syntax. -For instance, if a collection name contains a space or hyphen, starts -with a number, or conflicts with a built-in function: - -.. code-block:: javascript - - db.getCollection("3 test").find() - db.getCollection("3-test").find() - db.getCollection("stats").find() - -.. include:: /includes/fact-mongo-prompt-size.rst - -For more documentation of basic MongoDB operations in the -:binary:`~bin.mongo` shell, see: - -- :gettingstarted:`Getting Started Guide ` -- :doc:`/tutorial/insert-documents` -- :doc:`/tutorial/query-documents` -- :doc:`/tutorial/update-documents` -- :doc:`/tutorial/remove-documents` -- :doc:`/reference/method` - -.. [#access] - If the deployment runs with access control, the operation - returns different values based on user privileges. See - :ref:`listDatabases Behavior ` for details. - -Format Printed Results -~~~~~~~~~~~~~~~~~~~~~~ - -The :method:`db.collection.find()` method returns a :term:`cursor` to -the results; however, in the :binary:`~bin.mongo` shell, if the returned -cursor is not assigned to a variable using the ``var`` keyword, then -the cursor is automatically iterated up to 20 times to print up to the -first 20 documents that match the query. The :binary:`~bin.mongo` shell -will prompt ``Type it`` to iterate another 20 times. - -To format the printed result, you can add the ``.pretty()`` to the -operation, as in the following: - -.. code-block:: javascript - - db.myCollection.find().pretty() - -In addition, you can use the following explicit print methods in the -:binary:`~bin.mongo` shell: - -- ``print()`` to print without formatting - -- ``print(tojson())`` to print with :term:`JSON` formatting and - equivalent to ``printjson()`` - -- ``printjson()`` to print with :term:`JSON` formatting and equivalent - to ``print(tojson())`` - -For more information and examples on cursor handling in the -:binary:`~bin.mongo` shell, see :doc:`/tutorial/iterate-a-cursor`. See also -:ref:`mongo-shell-help-cursor` for list of cursor help in the -:binary:`~bin.mongo` shell. - -Multi-line Operations in the ``mongo`` Shell -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you end a line with an open parenthesis (``'('``), an open brace -(``'{'``), or an open bracket (``'['``), then the subsequent lines start -with ellipsis (``"..."``) until you enter the corresponding closing -parenthesis (``')'``), the closing brace (``'}'``) or the closing -bracket (``']'``). The :binary:`~bin.mongo` shell waits for the closing -parenthesis, closing brace, or the closing bracket before evaluating -the code, as in the following example: - -.. code-block:: javascript - - > if ( x > 0 ) { - ... count++; - ... print (x); - ... } - -You can exit the line continuation mode if you enter two blank -lines, as in the following example: - -.. code-block:: javascript - - > if (x > 0 - ... - ... - > - -Tab Completion and Other Keyboard Shortcuts -------------------------------------------- - -The :binary:`~bin.mongo` shell supports keyboard shortcuts. For example, - -- Use the up/down arrow keys to scroll through command history. See - :ref:`.dbshell ` documentation for more - information on the ``.dbshell`` file. - -- Use ```` to autocomplete or to list the completion - possibilities, as in the following example which uses ```` to - complete the method name starting with the letter ``'c'``: - - .. code-block:: javascript - - db.myCollection.c - - Because there are many collection methods starting with the letter - ``'c'``, the ```` will list the various methods that start with - ``'c'``. - -For a full list of the shortcuts, see :ref:`Shell Keyboard Shortcuts -` - - -``.mongorc.js`` File --------------------- - -When starting, :binary:`~bin.mongo` checks the user's :envvar:`HOME` -directory for a JavaScript file named :ref:`.mongorc.js -`. If found, :binary:`~bin.mongo` interprets the -content of :file:`.mongorc.js` before displaying the prompt for the -first time. If you use the shell to evaluate a JavaScript file or -expression, either by using the :option:`--eval ` -option on the command line or by specifying :ref:`a .js file to -mongo `, :binary:`~bin.mongo` will read the -``.mongorc.js`` file *after* the JavaScript has finished processing. -You can prevent ``.mongorc.js`` from being loaded by using the -:option:`--norc ` option. - -.. _mongo-shell-exit: - -Exit the Shell --------------- - -To exit the shell, type ``quit()`` or use the ```` shortcut. .. _compare-mongosh-mongo: Comparison of the ``mongo`` Shell and ``mongosh`` ------------------------------------------------- -.. note:: - - :mongosh:`mongosh ` is currently available as a - **Beta** release. The product, its features, and the corresponding - documentation may change during the Beta stage. - The new MongoDB Shell, :mongosh:`mongosh `, offers numerous advantages over the :binary:`~bin.mongo` shell, such as: @@ -424,14 +33,13 @@ advantages over the :binary:`~bin.mongo` shell, such as: - Improved logging. -During the beta stage, ``mongosh`` supports a subset of the -:binary:`~bin.mongo` shell methods. Achieving feature parity between -``mongosh`` and the ``mongo`` shell is an ongoing effort. +The ``mongosh`` currently supports a subset of the older +:binary:`~bin.mongo` shell methods. To maintain backwards +compatibility, the methods that the new ``mongosh`` supports use the +same syntax as the corresponding methods in the :binary:`~bin.mongo` +shell. -To maintain backwards compatibility, the methods that ``mongosh`` -supports use the same syntax as the corresponding methods in the -:binary:`~bin.mongo` shell. To see the complete list of methods -supported by ``mongosh``, see +The list of methods supported by ``mongosh`` is here: :mongosh:`MongoDB Shell Methods `. .. seealso:: @@ -440,11 +48,3 @@ supported by ``mongosh``, see - :binary:`~bin.mongo` Reference Page - :mongosh:`mongosh Documentation ` -.. toctree:: - :titlesonly: - - /tutorial/configure-mongo-shell - /tutorial/access-mongo-shell-help - /tutorial/write-scripts-for-the-mongo-shell - /core/shell-types - /reference/mongo-shell diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt index 784d24d0eec..482e239c77e 100644 --- a/source/release-notes/5.0-compatibility.txt +++ b/source/release-notes/5.0-compatibility.txt @@ -61,6 +61,15 @@ output the ``cache pressure percentage threshold`` and the ``current cache pressure percentage`` under ``wiredTiger.snapshot-window-settings``. +Shell Changes +------------- + +The ``mongo`` shell has been deprecated in MongoDB v5.0. The +replacement shell is :mongosh:`mongosh `. + +Shell packaging also changes in MongoDB v5.0. Refer to the +:mongosh:`installation instructions ` for further details. + Tools Changes ------------- @@ -141,6 +150,11 @@ General Changes Deprecations ~~~~~~~~~~~~ +- :binary:`~bin.mongo` + + The legacy ``mongo`` shell has been deprecated in MongoDB v5.0. The + replacement is :mongosh:`mongosh `. + - :method:`db.printSlaveReplicationInfo()` .. include:: /includes/deprecated-db.printSlaveReplicationInfo.rst diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index e27e042001b..10987160654 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -161,6 +161,15 @@ Starting in MongoDB 5.0, the :rsconf:`members[n]._id` field may be any integer value greater than or equal to ``0``. Previously, this value was limited to an integer between ``0`` and ``255`` inclusive. +.. _5.0-rel-notes-security: + +Security +-------- + +MongoDB 5.0 introduces the :parameter:`opensslCipherSuiteConfig` +parameter to enable configuration of the supported cipher suites OpenSSL +should permit when using TLS 1.3 encryption. + .. _5.0-rel-notes-sharded-clusters: Sharded Clusters @@ -186,14 +195,41 @@ for the ``"matchPrimaryNode"`` option. When set for a :binary:`~bin.mongod`, the instance follows the behavior specified for the ``"disabled"`` option. -.. _5.0-rel-notes-security: +.. _5.0-rel-notes-shell: -Security --------- +Shell Changes +------------- -MongoDB 5.0 introduces the :parameter:`opensslCipherSuiteConfig` -parameter to enable configuration of the supported cipher suites OpenSSL -should permit when using TLS 1.3 encryption. +New ``mongosh`` shell +~~~~~~~~~~~~~~~~~~~~~ + +The ``mongo`` shell has been deprecated in MongoDB v5.0. The +replacement shell is :mongosh:`mongosh `. The legacy ``mongo`` shell +will be removed in a future release. + +Shell packaging also changes in MongoDB v5.0. Refer to the +:mongosh:`installation instructions ` for further details. + +Shell Support for GCP and Azure KMS Providers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting in MongoDB 5.0 (and MongoDB 4.4.5), the Google Cloud Platform +KMS and Azure Key Vault are supported in both :mongosh:`mongosh ` +and the legacy :binary:`~bin.mongo` shell as +:ref:`Key Management Service (KMS) ` +providers for :doc:`/core/security-client-side-encryption`. + +Using a KMS, you can centrally and securely store Customer Master Keys +(CMKs), which are used to encrypt and decrypt data encryption keys as +part of the :ref:`client-side field level encryption workflow +`. + +In addition, a configured KMS allows for the use of +:ref:`field-level-encryption-automatic-decryption` of data fields when +used with MongoDB Enterprise. + +See :doc:`/core/security-client-side-encryption-key-management` for +configuration steps and considerations. .. _5.0-snapshot-reads: @@ -416,32 +452,6 @@ collections is lower than 0.5 GB. When the cumulative size of the The estimated size in bytes of a ``plan cache`` entry is available in the output of :pipeline:`$planCacheStats`. -.. _5.0-rel-notes-shell: - -Mongo Shell ------------ - -Shell Support for GCP and Azure KMS Providers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Starting in MongoDB 5.0 (and MongoDB 4.4.5), the :binary:`~bin.mongo` -shell adds support for using Google Cloud Platform KMS and Azure Key -Vault as :ref:`Key Management Service (KMS) -` providers for use with -:doc:`/core/security-client-side-encryption`. - -Using a KMS, you can centrally and securely store Customer Master Keys -(CMKs), which are used to encrypt and decrypt data encryption keys as -part of the :ref:`client-side field level encryption workflow -`. - -In addition, a configured KMS allows for the use of -:ref:`field-level-encryption-automatic-decryption` of data fields when -used with MongoDB Enterprise. - -See :doc:`/core/security-client-side-encryption-key-management` for -configuration steps and considerations. - .. _5.0-rel-notes-drivers: Drivers