5.0.txt

=============================
Release Notes for MongoDB 5.0
=============================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: twocols

.. note::

   MongoDB 5.0 Released Jul 13, 2021

Minor Releases
--------------

.. _5.0.3-release-notes:

5.0.3 - Sep 21, 2021
~~~~~~~~~~~~~~~~~~~~

Issues fixed:

- :issue:`SERVER-57667`: Improve processing speed for resharding's
  collection cloning pipeline
- :issue:`SERVER-57630`: Enable SSL_OP_NO_RENEGOTIATION on Ubuntu 18.04
  when running against OpenSSL 1.1.1
- :issue:`WT-8005`: Fix a prepare commit bug that could leave the
  history store entry unresolved
- :issue:`WT-7995`: Fix the global visibility that it cannot go beyond
  checkpoint visibility
- :issue:`WT-7984`: Fix a bug that could cause a checkpoint to omit a
  page of data

- `All JIRA issues closed in 5.0.3
  <https://jira.mongodb.org/issues/?jql=project%20in%20(SERVER%2CTOOLS%2CWT)%20AND%20resolution%3D%27Fixed%27%20and%20fixversion%3D%275.0.3%27>`_

- :ref:`5.0.3-changelog`

.. _5.0.2-release-notes:

5.0.2 - Aug 4, 2021
~~~~~~~~~~~~~~~~~~~

Issues fixed:


- :issue:`SERVER-58936`: Unique index constraints may not be enforced
- :issue:`SERVER-57756`: Race between concurrent stepdowns and applying
  transaction oplog entry
- :issue:`SERVER-54729`: MongoDB Enterprise Debian/Ubuntu packages
  should depend on libsasl2-modules and libsasl2-modules-gssapi-mit
- :issue:`SERVER-47372`: config.cache collections can remain even after
  collection has been dropped
- :issue:`WT-6729`: Quiesce eviction prior running rollback to stable's
  active transaction check

- `All JIRA issues closed in 5.0.2
  <https://jira.mongodb.org/issues/?jql=project%20in%20(SERVER%2CTOOLS%2CWT)%20AND%20resolution%3D%27Fixed%27%20and%20fixversion%3D%275.0.2%27>`_

- :ref:`5.0.2-changelog`

.. _5.0.1-release-notes:

5.0.1 - Jul 22, 2021
~~~~~~~~~~~~~~~~~~~~

.. warning::

   MongoDB version 5.0.1 is not recommended for production use due to a
   critical issue, :issue:`SERVER-58936`, fixed in later versions.
   Use the latest available patch release version. 

Issues fixed:

- :issue:`SERVER-58489`: Collection creation stuck in an infinite
  writeConflictRetry loop when having a duplicate name as a view
- :issue:`SERVER-58171`: Changing time-series granularity does not
  update view definition

- `All JIRA issues closed in 5.0.1
  <https://jira.mongodb.org/issues/?jql=project%20in%20(SERVER%2CTOOLS%2CWT)%20AND%20resolution%3D%27Fixed%27%20and%20fixversion%3D%275.0.1%27>`_

- :ref:`5.0.1-changelog`

5.0.0 - Jul 13, 2021
~~~~~~~~~~~~~~~~~~~~

.. warning::

   MongoDB version 5.0.0 is not recommended for production use due to a
   critical issue, :issue:`SERVER-58936`, fixed in later versions.
   Use the latest available patch release version. 

The rest of this page provides the 5.0.0 release notes:

.. _5.0-rel-notes-agg:

Time Series Collections
-----------------------

MongoDB 5.0 introduces :ref:`time series collections
<manual-timeseries-collection>` which efficiently store sequences of
measurements over a period of time. Compared to normal collections,
storing time series data in time series collections improves query
efficiency and reduces disk usage for your data and indexes.

Aggregation
-----------

.. _5.0-rel-notes-new-agg-operators:

New Aggregation Operators
~~~~~~~~~~~~~~~~~~~~~~~~~

MongoDB 5.0 introduces the following aggregation operators:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Operator
     - Description

   * - :group:`$count`
     - :group:`$count (aggregation accumulator) <$count>`
       provides a count of all documents when used in the existing
       pipeline :pipeline:`$group (aggregation) <$group>` stage and the
       new MongoDB 5.0 :pipeline:`$setWindowFields` stage.

       .. note:: Disambiguation

          The :group:`$count (aggregation accumulator) <$count>` is
          distinct from the :pipeline:`$count (aggregation) <$count>`
          pipeline stage.

   * - :expression:`$dateAdd`
     - Increments a :doc:`Date </reference/method/Date>` object by a
       specified number of time units.

   * - :expression:`$dateDiff`
     - Returns the difference between two dates.

   * - :expression:`$dateSubtract`
     - Decrements a :doc:`Date </reference/method/Date>` object by a
       specified number of time units.

   * - :expression:`$dateTrunc`
     - Truncates a date.

   * - :expression:`$getField`
     - Returns the value of a specified field from a document. 
       You can use :expression:`$getField` to retrieve the value of 
       fields with names that contain periods (``.``) or start 
       with dollar signs (``$``).

   * - :expression:`$rand`
     - The :expression:`$rand` method generates a random float value
       between 0 and 1 each time it is called. The new
       :expression:`$sampleRate` operator is based on ``$rand``. (Also
       added to MongoDB 4.4.2)

   * - :expression:`$sampleRate`
     - Adds the :expression:`$sampleRate` method to probabilistically
       select documents from a pipeline at a given rate.

   * - :expression:`$setField`
     - Adds, updates, or removes a specified field in a document. 
       You can use :expression:`$setField` to add, update,
       or remove fields with names that contain periods (``.``) or 
       start with dollar signs (``$``).

   * - :expression:`$unsetField`
     - Removes a specified field in a document. An alias for
       :expression:`$setField` to remove fields with names that contain
       periods (``.``) or that start with dollar signs (``$``).

Window Operators
~~~~~~~~~~~~~~~~

MongoDB 5.0 introduces the :pipeline:`$setWindowFields` pipeline stage,
allowing you to perform operations on a specified span of documents in a
collection, known as a *window*. The operation returns the results based
on the chosen :ref:`window operator <setWindowFields-window-operators>`.

.. include:: /includes/setWindowFields-introduction-examples.rst

General Aggregation Improvements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``$expr`` Operator: Comparison Operators Use Indexes
````````````````````````````````````````````````````

Starting in MongoDB 5.0, the :expression:`$eq`, :expression:`$lt`,
:expression:`$lte`, :expression:`$gt`, and :expression:`$gte` operators
placed in an :query:`$expr` operator can use indexes to improve performance.

``$ifNull`` Expression Accepts Multiple Input Expressions
`````````````````````````````````````````````````````````

Starting in MongoDB 5.0, you can specify multiple input expressions for
the :expression:`$ifNull` expression before returning a replacement
expression.

``let`` Option for Aggregation
``````````````````````````````

Starting in MongoDB 5.0, the :dbcommand:`aggregate` command and
:method:`db.collection.aggregate()` helper method have a ``let`` option
to specify a list of variables that can be used elsewhere in the
aggregation pipeline. This allows you to improve command readability by
separating the variables from the query text.

``$lookup`` Stage: Concise Correlated Subqueries
````````````````````````````````````````````````

Starting in MongoDB 5.0, an aggregation pipeline :pipeline:`$lookup`
stage supports :ref:`concise correlated subqueries
<lookup-syntax-concise-correlated-subquery>` that improve joins between
collections.

``$lookup`` Stage: Uncorrelated Subqueries
``````````````````````````````````````````

.. include:: /includes/uncorrelated-subquery.rst

See :ref:`lookup-uncorrelated-subquery`.

.. _5.0-rel-notes-auditing:

Auditing
--------

MongDB 5.0 adds the ability to configure auditing filters at runtime.

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Operator
     - Description

   * - :parameter:`auditConfigPollingFrequencySecs`
     - Defines the polling interval for checking audit configuration

   * - :dbcommand:`getAuditConfig`
     - Retrieves audit configurations from :binary:`~bin.mongod` and
       :binary:`~bin.mongos`.

   * - :dbcommand:`setAuditConfig`
     - Sets new audit configurations for :binary:`~bin.mongod` and
       :binary:`~bin.mongos` instances at runtime.

Starting in MongoDB 5.0:

- :ref:`System event auditing <audit-message-format>` has:

  - An additional :ref:`uuid <audit-message-uuid>` field and other
    :ref:`audit message <audit-message-format>` enhancements.

  - New audit message types: :ref:`clientMetadata
    <audit-message-clientMetadata>`, :ref:`directAuthMutation
    <audit-message-directAuthMutation>`, :ref:`logout
    <audit-message-logout>`, and :ref:`startup <audit-message-startup>`.

  - Additional information and logging scenarios for these existing
    audit message types: :ref:`authCheck <audit-message-authCheck>`,
    :ref:`authenticate <audit-message-authenticate>`,
    :ref:`createCollection <audit-message-createCollection>`,
    :ref:`createIndex <audit-message-createIndex>`, and
    :ref:`dropCollection <audit-message-dropCollection>`.

- DDL operations auditing on :term:`secondaries <secondary>` has
  changes. See :ref:`auditing-audit-events-and-filter`.

.. _5.0-rel-notes-change-streams:

Change Streams
--------------

Change Events Output
~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, :ref:`change-events`
contain the field ``updateDescription.truncatedArrays`` to record array
truncations.

.. _5.0-rel-notes-indexes:

Indexes
-------

Partial Indexes Behavior Change
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/fact-5.0-multiple-partial-index.rst

Cannot Drop ``Ready`` Indexes During In-Progress Index Builds
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/fact-5.0-dropindexes-inprog.rst

Foreground Validation May Fix Multikey Metadata Inconsistencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When run on a MongoDB deployment, 
:method:`db.collection.validate()` attempts to fix
:ref:`multikey metadata inconsistencies <validate-standalone-inconsistencies>`
of standalone deployments. 

Removal of ``geoHaystack`` Index and the ``geoSearch`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/fact-5.0-geohaystack-removed.rst

New Error Messages
~~~~~~~~~~~~~~~~~~

The :method:`db.collection.createIndex()` and :method:`db.collection.createIndexes()`
operations have new error messages when options are specified incorrectly.

Interrupted Index Builds
~~~~~~~~~~~~~~~~~~~~~~~~

If a node in a replica set is cleanly shutdown or rolls back during an
index build, the index build progress is now
:ref:`saved to disk<index-operations-build-failure>`. When the server
restarts, index creation resumes from the saved position.

``reIndex`` Behavior Change
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, the :dbcommand:`reIndex` command and the
:method:`db.collection.reIndex()` shell method may only be run on
:term:`standalone` instances.

.. _5.0-rel-notes-removed-commands:

Removed Commands
----------------

Starting in MongoDB 5.0, these database commands and
:binary:`~bin.mongo` shell helper methods are removed:

.. list-table::
   :header-rows: 1

   * - Removed Command
     - Alternative

   * - :method:`db.collection.ensureIndex()`
     - :method:`db.collection.createIndex()`

   * - :method:`db.resetError()`
     - Not available

   * - :dbcommand:`resetError`
     - Not available

   * - :dbcommand:`shardConnPoolStats`
     - :dbcommand:`connPoolStats`

   * - :dbcommand:`unsetSharding`
     - Not available

   * - :dbcommand:`geoSearch`
     - :pipeline:`$geoNear` or one of the supported
       :ref:`geospatial query operators <geospatial-query-selectors>`

.. _5.0-rel-notes-repl-sets:

Replica Sets
------------

Non-transactional Reads on ``config.transactions``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/fact-5.0-non-transactional-config-reads.rst

``hello`` Command
~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0 (and 4.4.2, 4.2.10, 4.0.21, and 3.6.21), the
:dbcommand:`hello` command and the :method:`db.hello()` method were
introduced as replacements for the ``isMaster`` command
and the ``db.isMaster()`` method. The new topology metric
:serverstatus:`connections.exhaustHello` tracks this in
:serverstatus:`connections`.

Quiesce Period
~~~~~~~~~~~~~~

Starting in MongoDB 5.0, :binary:`~bin.mongod` and :binary:`~bin.mongos`
enter a :ref:`quiesce period <shutdown-cmd-quiesce-period>` to allow any
ongoing database operations to complete before shutting down.

Limit Removed for ``members[n]._id`` Values
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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.

``enableMajorityReadConcern`` Is Not Configurable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/fact-eMRC-always-true-in-5.0.rst

.. include:: /includes/fact-psa-performance-issues.rst

Enhanced Thread Pool Timeout Control
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, you can use the new
:parameter:`replWriterMinThreadCount` server parameter to configure the
timeout of idle threads in the thread pool for parallel execution of
replication operations. When :parameter:`replWriterMinThreadCount` is
configured with a value less than :parameter:`replWriterThreadCount`,
idle threads above :parameter:`replWriterMinThreadCount` are timed out.

Reconfiguring PSA Replica Sets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When reconfiguring primary-secondary-arbiter (PSA) replica sets or
changing to a PSA architecture, it is now in some cases required to
perform the reconfiguration in a two-step change. MongoDB 5.0 introduces
the :method:`rs.reconfigForPSASet()` method which performs both steps.
If you cannot use the helper method, follow the procedure in
:ref:`modify-psa-replica-set-safely`.

Limit Sync Source Re-evaluations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:parameter:`maxNumSyncSourceChangesPerHour` determines how many sync
source changes can happen per hour before the node temporarily stops
re-evaluating a sync source. This parameter will not prevent a node
from starting to sync from another node if it doesn't have a sync
source.

.. _5.0-rel-notes-security:

Security
--------

Support for Online Certificate Rotation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, you may now rotate the following TLS
certificates on demand without first needing to stop your running
:binary:`~bin.mongod` or :binary:`~bin.mongos` instance:

- :setting:`TLS Certificates <net.tls.certificateKeyFile>`
- :setting:`CRL (Certificate Revocation List) files <net.tls.CRLFile>`
  (on Linux and Windows platforms)
- :setting:`CA (Certificate Authority) files <net.tls.CAFile>`

To rotate these certificates, replace the certificate files on your
filesystem with updated versions, then use the
:dbcommand:`rotateCertificates` command or the
:method:`db.rotateCertificates()` shell method to trigger certificate
rotation.

Rotating certificates in this manner does not require downtime, and does
not drop any active remote connections.

See :ref:`certificate-rotation` for full details.

Support for Configuring TLS 1.3 Cipher Suites
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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:

ApplyOps Privilege Action
~~~~~~~~~~~~~~~~~~~~~~~~~

MongoDB 5.0 introduces the :authaction:`applyOps` 
privilege action which is inherited by :authrole:`dbAdminAnyDatabase`.

The :authaction:`applyOps` action permits users to run the 
:dbcommand:`applyOps` database command.

Sharded Clusters
----------------

Resharding
~~~~~~~~~~

The ideal shard key allows MongoDB to distribute documents evenly
throughout the cluster while facilitating common query patterns. A
suboptimal shard key can lead to performance or scaling issues due to
uneven data distribution. Starting in MongoDB 5.0, you can use the
:dbcommand:`reshardCollection` command to :ref:`change the shard key
<change-a-shard-key>` for a collection to change the distribution of
your data across your cluster.

``currentOp`` Reports Ongoing Resharding Operations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, the :pipeline:`$currentOp` aggregation stage
(and the :dbcommand:`currentOp` command and :method:`db.currentOp()`
shell method) include additional information about the status of ongoing
resharding operations for the resharding coordinator and the
donor and recipient shards.

``db.currentOp`` Method Now Uses Aggregation Stage in ``mongosh``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, the :pipeline:`$currentOp` aggregation 
stage is used when running the helper method :method:`db.currentOp()` 
with :binary:`~bin.mongosh`.

``mongos`` / ``mongod`` Connection Pool
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0 (also available starting in 4.4.5 and 4.2.13),
MongoDB adds the parameter option ``"automatic"`` as the new default for
the :parameter:`ShardingTaskExecutorPoolReplicaSetMatching`. When set
for a :binary:`~bin.mongos`, the instance follows the behavior specified
for the ``"matchPrimaryNode"`` option. When set for a
:binary:`~bin.mongod`, the instance follows the behavior specified for
the ``"disabled"`` option.

``renameCollection`` Compatible with Sharded Collections
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, you can use the :dbcommand:`renameCollection`
command to change the name of a sharded collection.

.. include:: /includes/rename-collection-in-shard.rst

``movePrimary`` Error Message For Writes During Operation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, when using the :dbcommand:`movePrimary` command
to remove a shard from a :ref:`sharded cluster <sharded-cluster>`, 
writes to the original shard will generate an error message.

Split and Merge Chunk Changelogs Show Owning Shard
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, documents in the :data:`config.changelog`
collection for
:manual:`split </tutorial/split-chunks-in-sharded-cluster/>` and
:manual:`merge </tutorial/merge-chunks-in-sharded-cluster/>` operations
contain an ``owningShard`` field. The ``owningShard`` field shows the
``shardId`` of the shard that owns the chunks that were split or
merged.

The ``owningShard`` field helps identify shards where split or merge
operations frequently occur.

``maxCatchUpPercentageBeforeBlockingWrites`` Server Parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0 (and 4.4.7, 4.2.15, 4.0.26), you can set the
:parameter:`maxCatchUpPercentageBeforeBlockingWrites` to specify the
maximum allowed percentage of data not yet migrated
during a :dbcommand:`moveChunk` operation when compared to the
total size (in MBs) of the chunk being transferred.

This parameter can affect the behavior of:

- :dbcommand:`moveChunk` commands that are run manually.

- Load balancer functionality, which automatically runs multiple
  :dbcommand:`moveChunk` commands to evenly distribute chunks across
  shards. See :ref:`sharding-balancing`.


.. _5.0-rel-notes-shell:

Shell Changes
-------------

New MongoDB Shell: ``mongosh``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``mongo`` shell has been deprecated in MongoDB v5.0. The
replacement shell is :binary:`~bin.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 </install>` 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 :binary:`~bin.mongosh`
and the legacy :binary:`~bin.mongo` shell as
:ref:`Key Management Service (KMS) <field-level-encryption-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
<csfle-encryption-components>`.

In addition, a configured KMS allows for the use of
:ref:`field-level-encryption-automatic-decryption` of data fields when
used with MongoDB Enterprise.

Instructions are available for both shells:

- :mongosh:`Configure a KMS provider using mongosh </field-level-encryption/>`
- :doc:`Configure a KMS provider using the legacy mongo shell </core/security-client-side-encryption-key-management>`

.. _5.0-snapshot-reads:

Snapshots
---------

Extended Support for Read Concern ``"snapshot"``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, read concern :readconcern:`"snapshot"` is
supported for some read operations outside of multi-document
transactions on primaries and secondaries.

``minSnapshotHistoryWindowInSeconds`` Server Parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, you can use the
:parameter:`minSnapshotHistoryWindowInSeconds` parameter to control how
long WiredTiger keeps the snapshot history.

.. _5.0-rel-notes-transactions:

Transactions
------------

``coordinateCommitReturnImmediatelyAfterPersistingDecision`` Parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/return-commit-decision-parameter.rst

.. _5.0-rel-notes-general:

General Improvements
--------------------

Execution Plan Statistics for Query with ``$lookup`` Pipeline Stage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

MongoDB 5.0 adds :ref:`execution plan statistics
<explain-results-lookup>` for queries that use a :pipeline:`$lookup`
pipeline stage.

Improved Handling of (``$``) and (``.``) in Field Names
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

MongoDB 5.0 adds :ref:`improved support
<crud-concepts-dot-dollar-considerations>` for field names that are
(``$``) prefixed or that contain (``.``) characters. The validation
rules for storing data have been updated to make it easier to work with
data sources that use these characters.    

Cluster Wide Default Write Concern
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/5.0-cluster-wide-write-concern.rst

Implicit Default Write Concern
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/5.0-default-wc.rst

The :writeconcern:`{ w: "majority" } <"majority">` default
:doc:`write concern </reference/write-concern>` provides a stronger
durability guarantee in the event of an election, or if replica set
members become unavailable.

The :writeconcern:`{ w: "majority" } <"majority">` write concern may
impact performance since writes will only be acknowledged once a
:ref:`calculated majority <calculating-majority-count>` of replica set
members have executed and persisted the write to disk. If your
application relies on performance-sensitive writes, you can use the
:dbcommand:`setDefaultRWConcern` command to explicitly set the default
write concern for improved performance at the cost of data durability
guarantees. You can also set the write concern at the individual
operation level for performance-critical writes. See your
:driver:`driver documentation </>` for details. 

``mongosShutdownTimeoutMillisForSignaledShutdown`` Parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, the new parameter
:parameter:`mongosShutdownTimeoutMillisForSignaledShutdown` specifies
the time in milliseconds to wait for any ongoing database operations to
complete before initiating a shutdown of :binary:`~bin.mongos`.

Configurable ``zstd`` Compression Level
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

MongoDB 5.0 introduces the
:setting:`~storage.wiredTiger.engineConfig.zstdCompressionLevel`
configuration file option which allows for configurable compression
levels when
:setting:`~storage.wiredTiger.collectionConfig.blockCompressor` is set
to ``zstd``.

Lock-Free Read Operations
~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/lock-free-commands.rst

Schema Validation Failures Explained
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

MongoDB 5.0 adds detailed explanations when a document fails
:ref:`schema validation <schema-validation-overview>`.

Repair Option in ``validate`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, the :dbcommand:`validate` command and
:method:`db.collection.validate()` helper method have a new :ref:`repair
<cmd-validate-repair>` option for repairing a collection that has
inconsistencies.

The :dbcommand:`validate` command and :method:`db.collection.validate()`
helper method also return a new :data:`~validate.repaired` boolean value
that is ``true`` if the collection was repaired.

Repair Option in ``mongod``
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, the :option:`--repair <mongod --repair>` option
for :binary:`~bin.mongod` validates the collections to find any
inconsistencies and fixes them if possible, which avoids rebuilding the
indexes. See the :option:`--repair <mongod --repair>` option for usage
and limitations.

``corruptRecords`` Field in Validation Output
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, the :dbcommand:`validate` command and
:method:`db.collection.validate()` helper method return a new
:data:`~validate.corruptRecords` field that contains an array of
``RecordId`` values for corrupt documents.

``maxValidateMemoryUsageMB`` Server Parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, the :dbcommand:`setParameter` command has a new
:parameter:`maxValidateMemoryUsageMB` parameter, which sets the maximum
memory usage for the :dbcommand:`validate` command.

``findChunksOnConfigTimeoutMS`` Server Parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, you can use the
:parameter:`findChunksOnConfigTimeoutMS` parameter to change the timeout
for find operations on :data:`~config.chunks`.

Database Profiler ``filter`` Option
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, you can set a ``filter`` option for the
:ref:`database profiler <database-profiler>` to determine which
operations are profiled and logged. You can use the ``filter``
expression in place of the ``slowms`` and ``sampleRate`` profiler
options.

See:

- :ref:`database-profiler`
- :method:`db.setProfilingLevel()`
- :dbcommand:`profile`

Log Changes to Database Profiler Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/log-changes-to-database-profiler.rst

Independent Log Rotation for Server and Audit Logs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, when :doc:`auditing </core/auditing>` is
enabled, you may now rotate the server and audit logs
independently using the :dbcommand:`logRotate` command.
Previously, :dbcommand:`logRotate` would rotate the two logs together.

``remote`` Field in Slow Operation Logs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, :ref:`slow operation
<database-profiling-specify-slowms-threshold>` log messages include a
``remote`` field specifying client IP address.

``remoteOpWaitMillis`` Log Field
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, you can use the :ref:`remoteOpWaitMillis
<log-messages-remoteOpWaitMillis>` log field to obtain the wait time for
results from :term:`shards <shard>`.

Define Variables Using the ``let`` Option
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, the following commands have a ``let`` option to
define a list of variables. This allows you to improve command
readability by separating the variables from the query text.

- :dbcommand:`find` command

- :dbcommand:`findAndModify` command and corresponding
  :method:`db.collection.findAndModify()` shell helper

- :dbcommand:`update` command and corresponding
  :method:`db.collection.update()` shell helper

- :dbcommand:`delete` command

- :method:`db.collection.remove()` shell helper

The :dbcommand:`update` command also has a ``c`` field to define a list
of variables.

Support for Username to LDAP DN Mapping by Default
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, the :setting:`~security.ldap.userToDNMapping`
configuration file option and the :option:`--ldapUserToDNMapping
<mongod --ldapUserToDNMapping>` command line option for
:binary:`~bin.mongod` / :binary:`~bin.mongos` and :program:`mongoldap`
now map the authenticated username as the LDAP DN by default if an
empty mapping document (i.e. an empty string or empty array) is
specified to the option. Previously, providing an empty mapping document
would cause mapping to fail.

Additional ``dbStats`` Free Space Statistics
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0, the :dbcommand:`dbStats` command outputs these
additional statistics:

- Free space allocated to collections (:data:`~dbStats.freeStorageSize`)

- Free space allocated to indexes
  (:data:`~dbStats.indexFreeStorageSize`)

- Total free space allocated to collections and indexes
  (:data:`~dbStats.totalFreeStorageSize`)

``serverStatus`` Output Change
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:dbcommand:`serverStatus` includes the following new fields in its
output:

Aggregation Metrics
  - :serverstatus:`metrics.commands.update.pipeline` *(Also available in 4.4.2+, 4.2.11+)*
  - :serverstatus:`metrics.commands.update.arrayFilters` *(Also available in 4.4.2+, 4.2.11+)*
  - :serverstatus:`metrics.commands.findAndModify.pipeline` *(Also available in 4.4.2+, 4.2.11+)*
  - :serverstatus:`metrics.commands.findAndModify.arrayFilters` *(Also available in 4.4.2+, 4.2.11+)*
  - :serverstatus:`metrics.dotsAndDollarsFields`
  - :serverstatus:`metrics.operatorCounters`

Replication Metrics
  - :serverstatus:`metrics.repl.reconfig.numAutoReconfigsForRemovalOfNewlyAddedFields`

Read Concern Counters
  - :serverstatus:`readConcernCounters`, which reports on the
    :ref:`read concern level <read-concern-levels>` specified by query
    operations (:serverstatus:`readConcernCounters` replaces
    :serverstatus:`opReadConcernCounters`)

Number of Threaded Connections
  - :serverstatus:`connections.threaded`, which reports the number of
    incoming connections from clients that are assigned to threads that
    service client requests

Resharding Statistics
  - :serverstatus:`shardingStatistics.resharding`, which reports
    statistics about resharding operations

Service Executor Metrics
  - :serverstatus:`network.serviceExecutors`, which reports on the
    service executors that run operations for client requests

Cursor Metrics
  - :serverstatus:`metrics.cursor.moreThanOneBatch`, which reports the
    total number of cursors that have returned more than one batch
    (additional batches are retrieved using the :dbcommand:`getMore`
    command)

  - :serverstatus:`metrics.cursor.totalOpened`, which reports the total
    number of cursors that have been opened

Security Counter
  - :serverstatus:`security.authentication.saslSupportedMechsReceived`,
    which reports the number of times a :dbcommand:`hello` request
    includes a valid :data:`hello.saslSupportedMechs` field.

Plan Cache Debug Info Size Limit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0 (and 4.4.3, 4.2.12, 4.0.23, and 3.6.23), the
:doc:`plan cache </core/query-plans>` will save full ``plan cache``
entries only if the cumulative size of the ``plan caches`` for all
collections is lower than 0.5 GB. When the cumulative size of the
``plan caches`` for all collections exceeds this threshold, additional
``plan cache`` entries are stored without certain debug information.

The estimated size in bytes of a ``plan cache`` entry is available in
the output of :pipeline:`$planCacheStats`.

Closure of Inactive Cursors Opened Within a Session
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 5.0 (and 4.4.8), cursors created within a 
:doc:`client session </core/read-isolation-consistency-recency>` close 
when the corresponding :doc:`server session </reference/server-sessions>` 
ends with the :dbcommand:`killSessions` command, if the session times 
out, or if the client has exhausted the cursor. 
See :ref:`read-operations-cursors`.

New ``validateDBMetadata`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

MongoDB 5.0 adds the :dbcommand:`validateDBMetadata` command. The 
:dbcommand:`validateDBMetadata` command checks that the stored metadata 
of a database or a collection is valid within a particular API version.

.. _5.0-rel-notes-platforms:

Platform Support
----------------

.. _5.0-rel-notes-minimum-microarchitecture:

Minimum Microarchitecture
~~~~~~~~~~~~~~~~~~~~~~~~~

MongoDB 5.0 introduces the following minimum microarchitecture
requirements:

.. list-table::
   :header-rows: 1
   :widths: 15 85

   * - CPU
     - Minimum Supported Microarchitecture

   * - Intel ``x86_64``
     - MongoDB 5.0 requires one of:

       - Intel *Sandy Bridge* or later Core processor, or
       - Intel *Tiger Lake* or later Celeron or Pentium processor.

   * - AMD ``x86_64``
     - MongoDB 5.0 requires AMD *Bulldozer* or later.

   * - ARM ``arm64``
     - MongoDB 5.0 requires *ARMv8.2-A* or later.

MongoDB v5.0 is not supported on ``x86_64`` or ``arm64`` platforms that
do not meet these minimum microarchitecture requirements.

See :ref:`x86_64 Platform Support
<prod-notes-supported-platforms-x86_64>` for more information.

Removed Platforms
~~~~~~~~~~~~~~~~~

MongoDB 5.0 removes support for the following platforms:

- **macOS 10.13**

- **RHEL 7 / CentOS 7 / Oracle 7** on the
  :ref:`PPC64LE <prod-notes-supported-platforms-PPC64LE>` and
  :ref:`s390x <prod-notes-supported-platforms-s390x>` architectures

- **SLES 12** on the :ref:`s390x <prod-notes-supported-platforms-s390x>`
  architecture

- **Ubuntu 18.04** on the
  :ref:`PPC64LE <prod-notes-supported-platforms-PPC64LE>` and
  :ref:`s390x <prod-notes-supported-platforms-s390x>` architectures

See :ref:`prod-notes-supported-platforms` for the full list of platforms
and architectures supported in MongoDB 5.0.

Changes Affecting Compatibility
-------------------------------

Some changes can affect compatibility and may require user actions. For
a detailed list of compatibility changes, see
:doc:`/release-notes/5.0-compatibility`.

.. _5.0-upgrade:

Upgrade Procedures
------------------

.. important:: Feature Compatibility Version

   To upgrade to MongoDB 5.0 from a 4.4 deployment, the 4.4 deployment
   must have ``featureCompatibilityVersion`` set to ``4.4``. To check
   the version:

   .. code-block:: javascript

      db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )

To upgrade to MongoDB 5.0, refer to the upgrade instructions specific to
your MongoDB deployment:

- :doc:`/release-notes/5.0-upgrade-standalone`

- :doc:`/release-notes/5.0-upgrade-replica-set`

- :doc:`/release-notes/5.0-upgrade-sharded-cluster`

If you need guidance on upgrading to 5.0, `MongoDB offers major version
upgrade services
<https://www.mongodb.com/products/consulting?tck=docs_server>`_
to help ensure a smooth transition without interruption to your MongoDB
application.

.. _5.0-download:

Download
--------

To download MongoDB 5.0, go to the `MongoDB Download Center
<https://www.mongodb.com/try/download?tck=docs_server>`_.

.. seealso::

   - `All Third Party License Notices <https://github.com/mongodb/mongo/blob/v4.4/distsrc/THIRD-PARTY-NOTICES>`_.

.. _5.0-known-issues:
.. _5.0-known-issue-granularity:
.. _5.0-known-issue-backup-resharding:

Known Issues
------------

.. list-table::
   :header-rows: 1
   :widths: 15 70 20
   
   * - In Version
     - Issues
     - Status

   * - 5.0.0

     - :issue:`SERVER-58171`: A Time Series collection's ``granularity``
       parameter cannot be modified after the collection is created.

     - Fixed in 5.0.1

   * - 5.0.0

     - :issue:`SERVER-58392`: An ongoing resharding operation may
       prevent a backup or restore operation from succeeding.

     - Unresolved

Report an Issue
---------------

To report an issue, see
https://github.com/mongodb/mongo/wiki/Submit-Bug-Reports for
instructions on how to file a JIRA ticket for the MongoDB server or one
of the related projects.

.. toctree::
   :titlesonly:
   :hidden:

   /release-notes/5.0-compatibility
   /release-notes/5.0-upgrade-standalone
   /release-notes/5.0-upgrade-replica-set
   /release-notes/5.0-upgrade-sharded-cluster
   /release-notes/5.0-downgrade
   /release-notes/5.0-changelog