Release Notes for MongoDB 8.0
On this page
This page describes changes and new features introduced in MongoDB 8.0.
MongoDB 8.0 is a Major Release, which means that it is supported for both MongoDB Atlas and on-premises deployments. MongoDB 8.0 includes changes introduced in MongoDB Rapid Releases 7.1, 7.2, and 7.3. This page describes changes introduced in those Rapid Releases and MongoDB 8.0.
To learn more about the differences between Major and Rapid releases, see MongoDB Versioning.
Patch Releases
8.0.3 - Oct 24, 2024
Important
Improper neutralization of null bytes may lead to buffer over-reads in MongoDB Server
In MongoDB 8.0 prior to 8.0.3, an authorized user may trigger crashes or receive the contents of buffer over-reads of Server memory by issuing specially crafted requests that construct malformed BSON in the MongoDB Server.
This issue affects MongoDB Server versions:
5.0.0 - 5.0.29
6.0.0 - 6.0.18
7.0.0 - 7.0.14
8.0.0 - 8.0.2
Issues fixed:
SERVER-96419 Improper neutralization of null bytes may lead to buffer over-reads in MongoDB Server
8.0.1 - Oct 9, 2024
Issues fixed:
SERVER-76883 Reduce chattiness of "Role does not exist" logs for externally sourced users
SERVER-82221 listCollections and listIndexes should include commit-pending namespaces
SERVER-94635 Make session refresh parameters configurable
SERVER-95244 Upsert statements which result in an insert may fail with tassert 9146500 when client connects directly to shard
WT-13409 One ret in __txn_checkpoint is not handled
8.0.0 - Oct 2, 2024
The rest of this page describes changes and new features introduced in MongoDB 8.0.
Platform Support Updates
Starting in MongoDB 8.0, new MongoDB Server versions (major and minor) support the minimum operating system (OS) minor version defined by the OS vendor. After an OS minor version is no longer supported by the OS vendor, MongoDB updates the MongoDB Server to support the next OS minor version. For details, see MongoDB Platform Support Improvements.
MongoDB 8.0 supports the following minimum OS minor versions:
Red Hat Enterprise Linux 8.8
Red Hat Enterprise Linux 9.3
SUSE Linux Enterprise Server 15 SP5
Amazon Linux 2023 version 2023.3
Logging
Starting in MongoDB 8.0, you can configure the Database Profiler to log slow operations based on the time that MongoDB spends working on that operation, rather than the total latency for the operation. This means that factors such as waiting for locks and flow control do not affect whether an operation exceeds the slow operation threshold.
This change provides the following improvements for logging and query analysis:
Slow queries are logged more accurately based on the time MongoDB spends processing the query.
Query analysis tools such as the Query Profiler, Performance Advisor, and Search Query Telemetry report slow operations based on
workingMillis
instead ofdurationMillis
. This change provides a more accurate view of problematic queries.Slow query logs include a metric for the time queued on execution tickets,
queues.execution.totalTimeQueuedMicros
. This metric helps identify whether an operation is slow because of the time it takes to complete, or the time it spends waiting to start.
For more information, see db.setProfilingLevel()
.
Database Profiler
When you specify a filter
for the database profiler, you can log operations based on the new
workingMillis
metric. You can log operations based on both
workingMillis
and durationMillis
and set each metric to a
different threshold.
Aggregation
BinData Conversion
Starting in MongoDB 8.0, you can use the $convert
operator
to perform the following conversions:
String values to binData values
binData values to string values
MongoDB 8.0 also includes a new helper expression,
$toUUID
, which provides simplified syntax for converting
strings to UUID values.
$queryStats
Starting in MongoDB 7.1, the $queryStats
stage returns statistics
for recorded queries.
Change Stream Improvements
Starting in MongoDB 8.0, $queryStats
improves tracking and
reporting metrics for change streams. For more information, see
$queryStats Change Streams Behavior.
$rank and $denseRank Behavior
Starting in MongoDB 8.0, null
and missing field values in
$denseRank
and $rank
sortBy operations
are treated the same when calculating rankings. This change makes
the behavior of denseRank
and rank
consistent with
$sort
.
Security
Queryable Encryption Range Queries
Starting in MongoDB 8.0, Queryable Encryption
supports range queries on encrypted fields using the $lt
,
$lte
, $gt
, and $gte
operators. For details, see
Supported Operations for Queryable Encryption. To enable range
queries on encrypted fields, see Create an Encryption Schema.
OCSF Schema for Log Messages
Starting in MongoDB 8.0, you can specify the OCSF schema for audit log messages. The OCSF schema provides logs in a standardized format compatible with log processors.
To set the schema used for log messages, use the
auditLog.schema
configuration file option.
For example log messages in OCSF format, see OCSF Schema Audit Messages.
Ingress Queue
MongoDB 8.0 introduces a new queue for ingress admission control. Operations that wait for entry into the database from the network enter the ingress queue. By default, the queue is unrestricted, meaning that MongoDB allows all operations to execute through this stage without any queueing. Setting the queue maximum to a specific value allows you to queue operations at this stage if the number of oncurrent operations reaches the specified limit.
Sharding
Starting in MongoDB 8.0, you can unshard collections and move unsharded collections between shards on sharded clusters.
Moving a Collection
Starting in MongoDB 8.0, you can move an unsharded collection to a
different shard using the moveCollection
command.
For details, see Moveable Collections. To get started, see Move a Collection.
Moving Collections that have Change Streams
Starting in MongoDB 8.0, movePrimary
doesn't
invalidate collections that have change
streams. The change streams can continue to read events
from collections after the collections are moved to a new shard.
For details, see Moving Collections that have Change Streams.
Unsharding a Collection
Starting in MongoDB 8.0, you can unshard existing sharded collections with the
unshardCollection
command or the sh.unshardCollection()
method. This operation moves all documents in the collection onto a specified
shard or the shard with the least amount of data.
For details, see Unsharded Collections. To get started, see Unshard a Collection.
Config Shards
Starting in MongoDB 8.0, you can configure a config server to store your
application data in addition to the usual sharded cluster metadata. A
mongod
node that provides both config server and shard server
functionality is called a config shard. A mongod
node that runs as a
standalone --configsvr
without shard server functionality
is called a dedicated config server.
To configure a dedicated config server to run as a config shard, run the
transitionFromDedicatedConfigServer
command.
To configure a config shard to run as a dedicated config server, run the
transitionToDedicatedConfigServer
command.
For details, see Config Shard. To get started, see Start a Sharded Cluster with a Config Shard. To convert a replica set to a sharded cluster with a config shard, see Convert a Replica Set to a Sharded Cluster with an Embedded Config Server.
New Database Commands
New mongosh Methods
serverStatus Metrics
Starting in MongoDB 8.0, serverStatus
includes the following new
shardingStatistics
fields in its output:
shardingStatistics.countTransitionToDedicatedConfigServerStarted
shardingStatistics.countTransitionToDedicatedConfigServerCompleted
shardingStatistics.countTransitionFromDedicatedConfigServerCompleted
MongoDB 7.1 includes the following new sharding statistics for chunk migrations:
Default Chunks Per Shard
Starting in MongoDB 7.2, when you shard an empty collection with a hashed shard key, the operation creates one chunk per shard by default. Previously, the operation created two chunks by default.
directShardOperations Role
Starting in MongoDB 8.0, you can use the
directShardOperations
role to perform maintenance operations
that require you to execute commands directly against a shard.
Warning
Running commands using the directShardOperations
role can cause
your cluster to stop working correctly and may cause data corruption.
Only use the directShardOperations
role for maintenance purposes
or under the guidance of MongoDB support. Once you are done
performing maintenance operations, stop using the
directShardOperations
role.
Exhaust Cursors Enabled for Sharded Clusters
Starting in MongoDB 7.1, mongos
supports exhaust cursors
when a client's getMore request sets
the exhaustAllowed flag. This can improve query
performance on sharded clusters when the client receives multiple replies
from the database server for a single request.
mongos Port Range
Starting in MongoDB 7.1, mongos
accepts --port
values
from [0, 65535]. For more information, see --port
.
Query with Partial Shard Key
Starting in MongoDB 7.1, findAndModify
and deleteOne()
can use a partial shard key to query on a sharded collection.
Resharding Improvements
MongoDB 7.2 introduces significant performance improvements in reshard collection operations, substantially reducing the amount of time the operation takes to run.
Additionally, if your application and cluster meet the necessary
requirements and limitations, you can reshard the collection on the same key using
the reshardCollection
command to redistribute your collection,
which is much faster than alternative range migration procedure.
The following options are added to the command:
Field | Description |
---|---|
forceRedistribution | Enables same-key resharding. |
For examples, see Redistribute Data to New Shards.
Self-Managed Backups of Sharded Clusters
Starting in MongoDB 7.1, the fsync
and fsyncUnlock
commands can perform fsync operations on sharded clusters.
When run on mongos
with the lock
field set to true
, the
fsync
command flushes writes from the storage layer to disk and
locks each shard, preventing additional writes. The fsyncUnlock
command can then be used to unlock the cluster.
This feature enables self-managed backups of sharded clusters using
mongodump
.
UpdateOne upsert Behavior on Sharded Collections
Starting in MongoDB 7.1, when using
updateOne()
with upsert: true
on a
sharded collection, you do not need to include the full shard key
in the filter.
$lookup Stage in Transactions with Sharded Collections
Starting in MongoDB 8.0, you can use the $lookup
stage within
a transaction while targeting a sharded collection.
Replication
Majority Write Concern
Starting in MongoDB 8.0, write operations that use the
"majority"
write concern return an
acknowledgment when the majority of replica set members have
written the oplog entry for the change. This improves the
performance of "majority"
writes. In previous releases,
these operations would wait and return an acknowledgment after
the majority of replica set members applied the change.
If your application reads from a secondary immediately after
receiving an acknowledgment from a { w: "majority" }
write
operation (without a causally consistent
session), the query may return results that don't include
changes from the write.
New replSetGetStatus Metrics
Starting in MongoDB 8.0, the following metrics are available when using the
replSetGetStatus
command:
Oplog Buffers
Starting in MongoDB 8.0, secondaries write and apply oplog entries for each batch in parallel. A writer thread reads new entries from the primary and writes them to the local oplog. An applier thread asynchronously applies these changes to the local database. This changes increases replication throughput for secondaries.
This introduces a breaking change for metrics.repl.buffer
, as it
now provides metrics on two buffers instead of one.
MongoDB 8.0 deprecates the following server status metrics:
MongoDB 8.0 adds the following server status metrics:
Upgraded TCMalloc
Starting in MongoDB 8.0, MongoDB uses an upgraded version of TCMalloc that uses per-CPU caches, instead of per-thread caches, to reduce memory fragmentation and make your database more resilient to high-stress workloads.
The new TCMalloc version directly impacts previous production recommendations for Transparent Huge Pages. To learn more, see TCMalloc Performance Optimization for a Self-Managed Deployment.
serverStatus Metrics
Starting in MongoDB 8.0, the following new serverStatus
metrics
report information about tcmalloc
usage:
General Changes
Shutdown Performance
Starting in MongoDB 8.0, Bulk.insert()
and data ingestion
workloads may perform better. However, shutting down MongoDB
immediately after running these workloads might take longer because
of the extra data being flushed to disk.
Store Application Data on Config Shards
Starting in MongoDB 8.0, you can configure a config server to store application data in addition to the usual sharded cluster metadata. The config server is then known as a config shard. For details, see Config Shards.
Compaction Improvements
Starting in MongoDB 7.3, the compact
command includes a new
freeSpaceTargetMB
option to specify the minimum amount of storage space, in
megabytes, that must be recoverable for compaction to proceed.
Background Compaction
Starting in MongoDB 8.0, you can use the new autoCompact
command
to perform background compaction. If enabled, the server attempts to keep free
space within each collection and index below the specified the
freeSpaceTargetMB
value.
dryRun Option
If enabled, the compact
command returns an estimate of how much space, in
bytes, compaction can reclaim from the targeted collection. If you run
compact
with dryRun
set to true
, MongoDB only returns the estimated
value and does not perform any kind of compaction.
Concurrent DDL Operations
Starting in MongoDB 7.1, when you run multiple DDL operations that target different collections from the same database, MongoDB runs those operations concurrently.
This change adds two new types to the serverStatus
locks
field and currentOp.locks
output:
DDLDatabase
DDLCollection
Database Validation on mongos Aggregation Queries
Starting in MongoDB 7.2, aggregation pipeline queries that attempt to use non-existent databases on mongos deployments return validation errors.
In previous versions, these aggregation queries return empty cursors.
DDL Operations
In MongoDB 8.0, if you add or remove a shard while your cluster executes
a DDL operation (operation that modifies a collection such as
reshardCollection
), any operation that adds or removes a
shard only executes after the concurrent DDL operation finishes.
Error Codes for Exceeding Pipeline Size Limit
Starting in MongoDB 7.1, an aggregation command will throw an error when a pipeline exceeds the pipeline stage limit. For more details, see Number of Stages Restrictions.
getField Field Supports All Strings
Starting in MongoDB 7.2, you can specify any valid expression that resolves to a string for the field
input of the $getField
operator. In earlier versions,
field
accepts only string constants.
Improved Index Builds
Starting in MongoDB 7.1, index builds are improved with faster error
reporting and increased failure resilience. You can also set the minimum
available disk space required for index builds using the new
indexBuildMinAvailableDiskSpaceMB
parameter, which stops
index builds if disk space is too low.
The following new index build metrics were added:
For full details, see Index Builds.
New Parameters
auditConfig Parameter
MongoDB 7.1 adds the auditConfig
cluster parameter, which contains
information on audit configurations from mongod
and
mongos
server instances.
defaultMaxTimeMS Parameter
Starting in MongoDB 8.0, you can use the defaultMaxTimeMS
cluster parameter to specify a default time limit for individual read
operations to complete.
indexBuildMinAvailableDiskSpaceMB Parameter
MongoDB 7.1 adds the indexBuildMinAvailableDiskSpaceMB
parameter, which allows you to set the minimum available disk space
required for index builds.
tcmallocEnableBackgroundThread Parameter
Starting in MongoDB 8.0, the tcmallocEnableBackgroundThread
is
enabled by default. This allows MongoDB to periodically release memory back to
the operating system.
New Bulk Write Command
Starting in MongoDB 8.0, you can use the new bulkWrite
command to perform many insert, update, and delete operations on
multiple collections in one request. The existing
db.collection.bulkWrite()
method only allows you to modify one
collection in one request.
New Query Shape and Query Settings
MongoDB 8.0 introduces a new query shape. The pre-existing query shape is renamed as the plan cache query shape.
Starting in MongoDB 8.0, you can add query settings for the new query shape. The query optimizer uses the query settings as an additional input during query planning, which affects the plan selected to run a query that has a matching query shape.
Query settings have improved functionality compared to index filters. Index filters are also deprecated starting in MongoDB 8.0, and you should avoid using them.
To add query settings, use the
setQuerySettings
command.To delete query settings, use the
removeQuerySettings
command.To retrieve query settings, use a
$querySettings
stage in an aggregation pipeline.To block a query shape, see operation rejection filters.
Starting in MongoDB 8.0, queryShapeHash
is included in the following
output:
explain
command in theexplain.queryShapeHash
fielddatabase profiler in the
system.profile.queryShapeHash
field$currentOp aggregation pipeline stage in the
$currentOp.queryShapeHash
field
Starting in MongoDB 8.0, the pre-existing queryHash
field is renamed
to planCacheShapeHash
. If you're using an earlier MongoDB version,
you'll see queryHash
instead of planCacheShapeHash
.
Parameter Filtering
Starting in MongoDB 8.0, the getParameter
command
accepts a setAt
field. You can use this field to filter the
allParameters: true
return document to show only those
parameters that you can set at
startup or
runtime.
Read Concern on Capped Collections
Starting in MongoDB 8.0, you can use read concern
"snapshot"
on capped
collections.
serverStatus Output Change
Starting in MongoDB 7.1, the serverStatus
command output includes
the following new metrics:
Starting in MongoDB 7.2, the serverStatus
command output includes
the following new metrics:
Starting in MongoDB 7.3, the serverStatus
command output
includes the following new metrics:
Starting in MongoDB 8.0, the serverStatus
command output
includes the following new metrics:
Sort Support for updateOne
Starting in MongoDB 8.0, the updateOne()
method supports
a sort
option. This controls how MongoDB orders the document before it selects
the document to receive the update.
Previous releases use the findAndModify()
and
findOneAndUpdate()
methods to update
the first document in a user-specified sort order. Support for retryable writes
requires these methods to copy the entire document to a special side
collection for each node, which is a more expensive operation than the updateOne()
method with the new sort
option.
Specify Query Index Hints for distinct Commands
Starting in MongoDB 7.1, the hint
field is available in the
distinct
command, allowing you to specify the query's index.
TTL Indexes
Starting in MongoDB 7.1, you can create TTL indexes on capped collections.
Query Planning and Execution
Block Processing
Starting in version 8.0, MongoDB may execute certain time series queries using block processing. This performance improvement processes queries in "blocks" of data, rather than individual values. Block processing improves query execution speed and throughput when working with time series collections.
To see if your time series query uses block processing, check the
explain.queryPlanner.winningPlan.slotBasedPlan.stages
field in the
explain plan output.
To learn more, see Block Processing.
Express Query Stages
Starting in MongoDB 8.0, a limited set of queries (including _id
equality matches) skip regular query planning and execution. Instead,
these queries use an optimized index scan plan consisting of one of
these plan stages:
EXPRESS_CLUSTERED_IXSCAN
EXPRESS_DELETE
EXPRESS_IXSCAN
EXPRESS_UPDATE
For more information on query plans, see Explain Results.
Rejected Query Plan Output
Starting in MongoDB 8.0, rejected query plans only contain the find
portion of the query. In previous versions, rejected plans can contain
aggregation stages like $group
. Those aggregation stages
aren't used by the query planner to choose the winning plan, so the
rejectedPlans
field only contains the portion of the query that was
used to choose the winning plan.
This change also ensures that executionStats
for rejected plans are
non-zero. As a result, you can now see statistics such as how many
documents or keys a rejected plan examined.
For more information on rejected query plans, see
explain.queryPlanner.rejectedPlans
.
Batch Multi-Document Insert Operations
Starting in MongoDB 8.0, insert operations for
multi-document transactions no longer produce
individual oplog
entries. Instead, multi-document inserts are batched
as a single entry. The change stream insert
event for each document
has the same clusterTime
.
This change increases performance of multi-document insert operations
and eliminates possible replication lag caused by multiple oplog
writes.
OIDC Identity Providers Can Share an Issuer
Starting in MongoDB 8.0, when multiple identity providers (IDP) are
defined, the oidcIdentityProviders
parameter accepts duplicate
issuer
values as long as the audience
value is unique for each
issuer. This is also available in versions 7.3 and 7.0.
Namespaces in Subpipelines
Starting in MongoDB 8.0, namespaces in subpipelines inside
$lookup
and $unionWith
are validated to ensure
the correct use of from
and coll
fields.
For details, see $lookup subpipelines and $unionWith subpipelines.
Query Planner Optimization Time
The explain()
method now returns
information on query planner optimization time. The
queryPlanner.optimizationTimeMillis
status shows the
time in milliseconds that the query planner spent on
optimizations.
Known Issues
This section describes known issues in MongoDB 8.0 and their resolution status.
In Version | Issue | Status |
---|---|---|
8.0.0 | SERVER-94741: When multiple indexes are usable by
$or queries that include top-level $and clauses
(including implicit $and clauses), the query may use less
efficient indexes because the most efficient indexes have been
incorrectly removed from consideration during the new "index
pruning" phase of query planning in MongoDB 8.0. | Unresolved. Planned to be mitigated in 8.0.1 by disabling the
index pruning feature in SERVER-94738. |
8.0.0 | SERVER-95244: Upsert operations on single-shard sharded clusters may fail more often when all of the following are true:
The recommended process for transitioning to a sharded cluster requires
shifting clients to connect to | This issue is planned to be fixed in 8.0.1. |
Upgrade Procedures
Important
Feature Compatibility Version
To upgrade to MongoDB 8.0 from a 7.0 deployment, the 7.0 deployment
must have featureCompatibilityVersion
set to 7.0
. To check
the version:
db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
To upgrade to MongoDB 8.0, refer to the upgrade instructions specific to your MongoDB deployment:
If you need guidance on upgrading to 8.0, MongoDB professional services offer major version upgrade support to help ensure a smooth transition without interruption to your MongoDB application. To learn more, see MongoDB Consulting.
Download
To download MongoDB 8.0, go to the MongoDB Download Center.