Merge branch 'master' into DOCSP-46093-rn-2.3.5-2.3.7

Author: mdb-ashley

snooty.toml

@@ -1,5 +1,5 @@
 name = "mongodb-shell"
-title = "MongoDB Shell"
+title = "mongosh"
 
 intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv" ]
 
@@ -12,12 +12,14 @@ toc_landing_pages = ["/install",
                      "/snippets",
                      "/configure-mongosh",
                      "/reference/configure-shell-settings",
-                     "/reference/ejson"
+                     "/reference/ejson",
+                     "/logs",
+                     "/logs/retention"
                     ]
 
 [constants]
 
-version = "2.3.2"
+version = "2.4.0"
 mdb-version = "8.0"
 pgp-version = "{+mdb-version+}"
 atlas = "MongoDB Atlas"

source/changelog.txt

@@ -4,6 +4,9 @@
 Release Notes
 =============
 
+.. meta::
+   :description: Explore the changelog for `mongosh`, detailing new features, bug fixes, and updates across various versions.
+
 .. default-domain:: mongodb
 
 .. contents:: On this page
@@ -12,6 +15,126 @@ Release Notes
    :depth: 1
    :class: singlecol
 
+
+=======
+v2.5.0
+------
+
+*Released April 9, 2025*
+
+New features released in this version:
+
+- :issue:`MONGOSH-1873` - Support new BSON vector types in mongosh
+- :issue:`MONGOSH-1649` - Add automerge information to sh.status()
+- :issue:`MONGOSH-1100` - Add Mongo bulkWrite API
+- :issue:`MONGOSH-1919` - Add sh.isConfigShardEnabled and listShards helpers
+
+`Full release notes available on JIRA 
+<https://jira.mongodb.org/issues/?jql=project%20%3D%20MONGOSH%20AND%20fixVersion%20%3D%202.5.0>`__.
+
+v2.4.2
+------
+
+*Released March 6, 2025*
+
+New feature released in this version:
+
+- :issue:`MONGOSH-1926` - Added the ``sh.moveRange`` helper method.
+
+`Full release notes available on JIRA 
+<https://jira.mongodb.org/issues/?jql=project%20%3D%20MONGOSH%20AND%20fixVersion%20%3D%202.4.2>`__.
+
+v2.4.0
+------
+*Released February 24, 2025*
+
+``mongosh`` now uses the following driver versions:
+
+- `Node.js driver 6.13.0 <https://github.com/mongodb/node-mongodb-native/releases/tag/v6.13.0>`__.
+- `Node.js BSON package 6.10.3 <https://github.com/mongodb/js-bson/releases/tag/v6.10.3>`__.
+
+New features released in this version:
+
+- :issue:`MONGOSH-2013` - Added a ``history()`` command, which returns an array of 
+  all previously run commands.
+  
+- :issue:`MONGOSH-1090` - Added a ``log.getPath()`` command, which returns the path
+  to the currently active log file.
+
+- :issue:`MONGOSH-1995` - Added help output for logging commands.
+
+- Added the following logging configuration options, which you can set directly
+  in the :ref:`configuration file <configure-settings-global>`, or by calling 
+  the :ref:`config api <configure-settings-api>`.
+
+  - :issue:`MONGOSH-1988` - Disable logging by setting ``disableLogging: true``.
+
+  - :issue:`MONGOSH-1983`, :issue:`MONGOSH-2012` - Specify a custom path for
+    :ref:`log files <mdb-shell-logs>` by setting ``logLocation``.
+
+  - :issue:`MONGOSH-1986` - Compress log files by setting 
+    ``logCompressionEnabled: true``.
+
+  - :issue:`MONGOSH-1984` - Limit the number of days to keep log files by
+    setting ``logRetentionDays`` (default 30).
+
+  - :issue:`MONGOSH-1985` - Limit the maximum size of the logs directory by
+    setting ``logRetentionGB`` (default uncapped).
+
+  - :issue:`MONGOSH-1987` - Limit the maximum number of log files by setting
+    ``logMaxFileCount`` (default 100).
+
+
+Bug Fixes:
+
+- :issue:`MONGOSH-1914` - Fixed an issue where multiple ``mongosh`` processes
+  could attempt to remove outdated log files at the same time, leading to one
+  process terminating with ``Error: ENOENT: no such file or directory``.
+
+- :issue:`MONGOSH-2002` - Improved error messaging when attempting to serialize
+  a cursor.
+
+`Full release notes available on JIRA 
+<https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=17381&version=42122>`__.
+
+
+v2.3.9
+------
+*Released February 5, 2025*
+
+.. important::
+   This release includes fixes for security issues. Upgrade to ``mongosh`` 
+   2.3.9 at your earliest convenience.
+
+- Upgrades Node.js version to 20.18.2. Node 20.18.2 resolves security issues. 
+  For more information, see the  `January 21, 2025 Node.js security release \
+  <https://nodejs.org/en/blog/release/v20.18.2>`__.
+
+- Stricter validation of user input to address 
+  `CVE-2025-1691 <https://nvd.nist.gov/vuln/detail/CVE-2025-1691>`__, 
+  `CVE-2025-1692 <https://nvd.nist.gov/vuln/detail/CVE-2025-1692>`__, 
+  and `CVE-2025-1693 <https://nvd.nist.gov/vuln/detail/CVE-2025-1693>`__.
+
+New features released in this version:
+
+- :issue:`MONGOSH-1989` - Added ability to log custom messages in scripts by 
+  calling ``log.[debug|info|warn|error|fatal]()``
+
+`Full release notes available on JIRA 
+<https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=17381&version=41759>`__.
+
+
+v2.3.8
+------
+
+*Released January 6, 2025*
+
+Contains internal enhancements and improvements.
+
+`Full release notes available on JIRA 
+<https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=17381&version=41730>`__.
+
+
 v2.3.7
 ------
 
@@ -34,6 +157,7 @@ Contains internal enhancements and improvements.
 `Full release notes available on JIRA
 <https://jira.mongodb.org/browse/MONGOSH-1922?jql=project%20%3D%20MONGOSH%20AND%20fixVersion%20%3D%202.3.6>`__.
 
+
 v2.3.5
 ------
 
@@ -48,6 +172,7 @@ Bug Fixes:
 `Full release notes available on JIRA
 <https://jira.mongodb.org/browse/MONGOSH-1922?jql=project%20%3D%20MONGOSH%20AND%20fixVersion%20%3D%202.3.5>`__.
 
+
 v2.3.4
 ------
 
@@ -491,7 +616,7 @@ v2.0.0
   - ``upgradeState``
 
   To obtain version information, see the :ref:`feature compatibility
-  version (fcv) <view-fcv>`.
+  version (FCV) <view-fcv>`.
 
 - Removes support for :ref:`Free Monitoring <free-monitoring-mongodb>`
   helper functions:

source/connect.txt

@@ -258,6 +258,17 @@ To connect to a replica set, you can either:
 - Explicitly specify the replica set name and members in the connection
   string.
 
+.. important::
+
+   When a replica set runs in Docker, it might expose only one 
+   MongoDB endpoint. In this case, the replica set is not discoverable, and specifying 
+   ``directConnection=false`` can prevent your application from connecting to it.
+   
+   In a test or development environment, you can connect to the replica set by specifying
+   ``directConnection=true`` in your connection URI. In a production environment, we
+   recommend configuring the cluster to make each MongoDB instance accessible outside of
+   the Docker virtual network.
+   
 Option 1: DNS Seedlist Format
 `````````````````````````````
 
@@ -345,17 +356,32 @@ To connect to a deployment using TLS, you can either:
 Connect to a Specific Database
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To connect to a specific database, specify a database in your
-:manual:`connection string URI path </reference/connection-string/>`. If
-you do not specify a database in your URI path, you connect to the
-``test`` database.
+To connect to a specific default database, specify a database in your
+:manual:`connection string URI path </reference/connection-string/>`.
+If unspecified by the connection string, the default database
+is the ``test`` database.
 
 For example, to connect to a database called ``qa`` on localhost, run the
 following command:
 
 .. code-block:: sh
 
-    mongosh "mongodb://localhost:27017/qa" 
+    mongosh "mongodb://localhost:27017/qa"
+
+You can specify the authentication database in your connection string
+using the :urioption:`authSource` connection option. If specified, the
+client uses this database to verify your user identity and credentials. 
+If :urioption:`authSource` is unspecified, it defaults to the default 
+database specified in the connection string. If both :urioption:`authSource` 
+and the default database are unspecified, 
+:urioption:`authSource` defaults to the ``admin`` database.
+
+The following connection string sets the default database to ``myDefaultDB``
+and the authentication database to ``admin``:
+
+.. code-block:: bash
+
+   mongodb://myDatabaseUser:D1fficultP%[email protected]:27017/myDefaultDB?authSource=admin
 
 Proxy Settings
 ~~~~~~~~~~~~~~

source/field-level-encryption.txt

@@ -4,6 +4,9 @@
 Client-Side Field Level Encryption
 ==================================
 
+.. meta::
+   :description: Configure client-side field level encryption in `mongosh` for MongoDB clusters using various KMS providers like AWS, Azure, GCP, or a local keyfile.
+
 .. default-domain:: mongodb
 
 .. contents:: On this page

source/includes/admonitions/note-redact-credentials-command-history.rst

@@ -1,5 +1,2 @@
-.. note::
-
-   The |mdb-shell| redacts credentials from the :ref:`command history
-   <mdb-shell-command-history>` and the :ref:`logs
-   <mdb-shell-view-logs>`.
+The |mdb-shell| redacts credentials from the :ref:`command history
+<mdb-shell-command-history>` and the :ref:`logs <mdb-shell-view-logs>`.

source/includes/fact-certificate-expiry-warning.rst

@@ -1,3 +1,3 @@
 Starting in version 4.4, :binary:`~bin.mongod` / :binary:`~bin.mongos`
-logs a warning on connection if the presented x.509 certificate expires
+logs a warning on connection if the presented X.509 certificate expires
 within ``30`` days of the ``mongod/mongos`` host system time.

source/includes/list-table-shell-properties.rst

@@ -7,6 +7,11 @@
      - Default
      - Description
 
+   * - ``disableLogging``
+     - boolean
+     - ``false``
+     - Specifies whether |mdb-shell| writes log entries.
+
    * - ``displayBatchSize``
      - integer
      - 20
@@ -52,16 +57,63 @@
      - The depth to which objects are printed. Setting ``inspectDepth``
        to ``Infinity`` (the javascript object) prints all nested
        objects to their full depth. 
+   
+   * - ``logCompressionEnabled``
+     - boolean
+     - false
+     - Specifies whether |mdb-shell| compresses log files. When this
+       value is ``true``, |mdb-shell| uses gzip to compress logs. See
+       :ref:`mongosh-log-compression`.
+
+   * - ``logLocation``
+     - string
+     - Depends on your operating system. See :ref:`mdb-shell-view-logs`.
+     - Directory where MongoDB Shell writes log files. Specify an
+       absolute filepath. See :ref:`mongosh-log-location`.
+
+   * - ``logMaxFileCount``
+     - integer or Infinity
+     - 100
+     - Maximum number of log files that the |mdb-shell| retains. After
+       the |mdb-shell| reaches the maximum log file count, it starts
+       deleting the oldest log files until the count is below the
+       threshold. See :ref:`mongosh-log-file-count`.
+
+   * - ``logRetentionDays``
+     - integer or Infinity
+     - 30
+     - Number of days that |mdb-shell| log files are retained. If this
+       value is set to ``Infinity``, log files are not deleted based on
+       age. To prevent log storage from growing too large, always
+       specify at least one log retention criterion. See
+       :ref:`mongosh-logs-retention`.
+
+   * - ``logRetentionGB``
+     - float or Infinity
+     - Unset
+     - Maximum amount of space in gigabytes used for |mdb-shell| logs.
+       If the combined size of |mdb-shell| logs exceeds this value, log
+       files are deleted starting with the oldest logs.
+
+       If this value is set to ``Infinity``, log files are not deleted
+       based on storage size. To prevent log storage from growing too
+       large, always specify at least one log retention criterion. See
+       :ref:`mongosh-logs-retention`.
 
    * - ``redactHistory``
      - string
      - ``remove``
-     - Controls what information is recorded in the shell history.
-       Must be one of:
+     - Controls what information is recorded in the ``mongosh`` command history.
+       You can access the ``mongosh`` command history via the up and down keys 
+       or Ctrl+R while inside the shell.
+
+       Must be one of the following values:
 
        - ``keep``: Retain all history.
-       - ``remove``: Remove lines which contain sensitive information.
-       - ``remove-redact``: Redact sensitive information.
+       - ``remove``: Remove lines that contain sensitive commands from the history. 
+         For example, ``remove`` removes calls to db.auth() or connect().
+       - ``remove-redact``: Remove lines that contain sensitive commands and redact 
+         specific strings in other history lines, such as file paths, email addresses, and URLs. 
 
    * - ``showStackTraces``
      - boolean

source/includes/log-file-location.rst

@@ -0,0 +1,16 @@
+Starting in |mdb-shell| 2.4.0, you can use the ``log.getPath()``
+command to view the current log file location. For example:
+
+.. code-block:: javascript
+
+   log.getPath()
+
+Example output:
+
+.. code-block:: javascript
+   :copyable: false
+
+   /Users/jane.doe/.mongodb/mongosh/c2961dbd6b73b052671d9df0_log
+
+The hexadecimal value in the path is the |mdb-shell| log identifier for
+the current session.

source/includes/log-retention-multiple-criteria.rst

@@ -0,0 +1,4 @@
+You can specify multiple criteria for log retention. For example, you
+can specify a maximum duration for log files of 60 days and a maximum
+log storage size of 2GB. Logs are deleted when any retention criterion
+is met, starting with the oldest logs.

source/includes/platform-limitations.rst

@@ -2,7 +2,3 @@
 - Red Hat Enterprise Linux (RHEL) 7, Amazon Linux 2, SUSE Linux
   Enterprise Server (SLES) 12, and Ubuntu 18.04 support is deprecated
   and might be removed in a later ``mongosh`` release.
-- If you must use ``Node.js`` 16 with ``mongosh``, install ``Node.js``
-  and then install ``mongosh`` through ``npm``. The ability to run
-  ``mongosh`` installed with ``npm`` and use ``Node.js`` 16 might be
-  removed during the lifetime of ``mongosh`` 2.x.

source/includes/specify-one-retention-criterion.rst

@@ -0,0 +1,4 @@
+.. important::
+
+   To prevent log storage from growing too large, always specify at
+   least one log retention criterion.

source/install/verify-signatures.txt

@@ -4,6 +4,9 @@
 Verify Integrity of MongoDB Shell Packages
 ==========================================
 
+.. meta::
+   :description: Verify the integrity of MongoDB Shell packages using digital signatures before installation.
+
 .. contents:: On this page
    :local:
    :backlinks: none