Navigation

Release Notes for MongoDB 3.6

Security

Default Bind to Localhost

Starting in MongoDB 3.6, MongoDB binaries, mongod and mongos, bind to localhost by default. Previously, starting in MongoDB 2.6, only the binaries from the official MongoDB RPM (Red Hat, CentOS, Fedora Linux, and derivatives) and DEB (Debian, Ubuntu, and derivatives) packages bind to localhost by default. For more details, see Localhost Binding Compatibility Changes.

Authentication Restrictions

To restrict database user connections to specified IP addresses, added authenticationRestrictions parameter to the following:

Commands Methods
createUser db.createUser()
updateUser db.updateUser()
createRole db.createRole()
updateRole db.updateRole()

Additional Security Enhancements

Aggregation

The following features are available starting in MongoDB 3.6.

More Expressive $lookup

$lookup adds support for specifying multiple join conditions as well as uncorrelated sub-queries by allowing variable specification and pipeline execution on the joined collection.

For details, see the $lookup syntax for Join Conditions and Uncorrelated Sub-queries.

New Aggregation Stages

MongoDB 3.6 adds the following new aggregation pipeline stages:

Operator Description
$currentOp Returns a stream of documents containing information on active and/or dormant operations on a mongod instance. Uses the new aggregation helper db.aggregate().
$listSessions Lists server sessions in the system.sessions collection in the config database. Uses the new aggregation helper db.aggregate().
$listLocalSessions Lists server sessions cached in memory by the server.

New Aggregation Operators

Operator Description
$arrayToObject Converts an array of key value pairs to a document.
$objectToArray Converts a document to an array of documents representing key-value pairs.
$mergeObjects Combines multiple documents into a single document.
$dateFromString Converts a date/time string to a date object.
$dateFromParts Constructs a BSON Date object given the date’s constituent parts.
$dateToParts Returns a document containing the constituent parts of a date.

New Aggregation Helper

MongoDB 3.6 adds a helper, db.aggregate(), to perform aggregations that do not rely on an underlying collection, such as those that start with $currentOp or $listLocalSessions.

New Aggregation Variable

REMOVE allows for the conditional exclusion of a field.

New Options

aggregate command and the db.collection.aggregate() method support the following new options:

  • hint option to specify the index to use.

    Note

    The hint does not apply to $lookup and $graphLookup stages.

  • comment option to help trace the operation through the database profiler, currentOp, and logs.

Support for Time Zones

MongoDB 3.6 adds support for time zones to aggregation date operators.

Array Update Operator Enhancements

arrayFilters

The following commands and methods can accept an arrayFilters parameter to specify which elements to modify in an array field:

Commands Methods
findAndModify
update
 
Bulk.find.arrayFilters() for Bulk() operation methods updateOne() and update().

Multi-Element Array Updates

MongoDB 3.6 adds the following new positional operators for update operations on arrays and nested arrays:

  • The all positional $[] operator updates all elements in an array.
  • The filtered positional $[<identifier>] operator updates all elements in an array that match the arrayFilters criteria.

Negative Array Index Position for push

The $position modifier for the push update operator can accept a negative array index value to indicate a position starting from the end of the array.

3.6 Compatible Drivers

The following drivers are feature compatible with MongoDB 3.6:

  • Java 3.6,
  • Python 3.6
  • C 1.9
  • Node 3.0

DNS-constructed Seedlist mongodb+srv

In addition to the standard connection format, the 3.6 drivers support a DNS-constructed seedlist. For more information, see DNS Seedlist Connection Format.

Change Streams

MongoDB 3.6 supports opening change streams against replica sets and sharded clusters with replica set shards.

Change streams allow applications to access real-time data changes without the complexity and risk of tailing the oplog. Applications can use change streams to subscribe to all data changes on a collection and respond to those changes.

You can open a change stream from any 3.6-series driver using the db.collection.watch() method. See the documentation for your preferred driver for complete instructions on usage.

See Change Streams for more information.

Important

To use change streams, featureCompatibilityVersion must be set to “3.6”. For more information, see View FeatureCompatibilityVersion and setFeatureCompatibilityVersion.

Client Sessions

Causal Consistency

To provide causal consistency, MongoDB 3.6 enables causal consistency in client sessions. A causally consistent client session denotes that the associated sequence of read and acknowledged write operations have a causal relationship that is reflected by their ordering. Client applications must ensure that only one thread at a time executes these operations in a client session.

Applications can start a client session and associate operations with a specific session. Applications must ensure that only one thread at a time executes these operations in a client session.

Important

To use client sessions:

Retryable Writes

Important

For retryable writes:

Starting in MongoDB 3.6, certain acknowledged write operations on replica sets and sharded clusters are “retryable” to provide handling of transient network errors or replica set elections.

With retryable writes, MongoDB drivers automatically retries these operations upon encountering network errors or encountering a replica set failover during which time the replica set has no primary. To enable retryable writes for the 3.6 drivers, see retryWrites.

As the retry attempt is made only once, the retryable feature can help address transient network errors but not persistent network errors.

For more information on retryable writes, see Retryable Writes.

mongo Shell Changes

MongoDB 3.6 adds the new command-line option --retryWrites to the mongo shell. The option enables Retryable Writes in the mongo shell.

The following new methods have been added to the Mongo() connection object in the mongo shell:

Server Sessions

MongoDB’s server sessions, or logical sessions, are the underlying framework used by client sessions to support Causal Consistency and retryable writes.

Important

Applications use client sessions to interface with server sessions.

Server sessions are available for standalone mongod instances, replica sets, and sharded clusters.

Server Session Commands

Starting in 3.6, MongoDB drivers associate all operations with a server session, with the exception of unacknowledged writes. If the deployment enforces authentication/authorization, server sessions are associated with the authenticated users.

The following commands can be used to list, manage, and kill server sessions throughout MongoDB clusters:

Commands Descriptions
endSessions Expires specified server sessions.
killAllSessions Kills all server sessions.
killAllSessionsByPattern Kills all server sessions that match the specified pattern.
killSessions Kills specified server sessions.
refreshSessions Refreshes idle server sessions.
startSession Starts a new server session.

Parameters

The following new parameters are available for server sessions:

Aggregation Stages

To support server sessions, MongoDB 3.6 adds the following new aggregation pipeline stages:

Operator Description
$listSessions Lists the server sessions in the system.sessions collection in the config database.
$listLocalSessions Lists the server sessions cached in memory by the server. Uses the new aggregation helper db.aggregate().

General

serverStatus returns information on the number of logicalSessionRecordCache.

Command Options

Starting in 3.6, MongoDB drivers associate all operations with a server session, with the exception of unacknowledged writes. The following options are available for all commands to support association with a server session:

Important

The mongo shell and the drivers assign these options to the commands in the session.

Option Type Description
lsid Document The document that specifies the unique id of the session associated with the command. If the txnNumber is specified, the lsid is required.
txnNumber 64-bit integer

A strictly increasing non-negative number that uniquely identifies the command in the command’s session.

If specified, the command must also include the lsid option.

For the delete, insert, and update commands that take an array of statements, the following option is also available:

Important

Do not manually set the stmtIds. MongoDB sets the stmtIds to strictly increasing non-negative number.

Option Type Description
stmtIds Array of 32-bit integers Array of numbers that uniquely identifies their respective write operations within the write command.

JSON Schema

MongoDB 3.6 adds the $jsonSchema operator to support document validation using JSON Schema. For details, see $jsonSchema.

To use $jsonSchema, featureCompatibilityVersion must be set to “3.6”.

Replica Sets

Sharded Clusters

General Enhancements

MongoDB Compass Packaging

The MongoDB Server download is packaged with a platform-specific installation script for MongoDB Compass Community Edition. This script installs MongoDB Compass as part of the MongoDB Server installation process.

Collection Identifier

Collections have an immutable unique identifier. The featureCompatibilityVersion must be set to "3.6".

New Query Operators

MongoDB 3.6 adds the following new query operators:

  • The new $jsonSchema operator matches documents that validate against the given JSON Schema. To use $jsonSchema, featureCompatibilityVersion must be set to “3.6”.
  • The $expr allows the use of aggregation expressions within the query language.

Removed Operators

MongoDB 3.6 removes the deprecated $pushAll update operator. For more information, see Remove $pushAll Update Operator.

Indexes

  • An index can cover a query on fields within nested documents.
  • Multikey indexes can cover queries over non-array keys if the index tracks which fields make it multikey.
  • When creating an index, you cannot specify * as the name of the index. See Indexes Named *.

Commands

  • Added the following options to the listDatabases command:
    • nameOnly to return only the database names (which does not require database locks) instead of returning both the database names and size information (which does require database locks).
    • filter to return databases that match the specified match criteria on the outputs.
  • Modified behavior of the validate command and the db.collection.validate() method such that only for full validation does the WiredTiger storage engine force a checkpoint, flush all in-memory data to disk, then verify the on-disk data. See also validate Operation.
  • The <database>.system.profile entry for update and delete contains the entire update/delete document applied to the named collection.
  • dropDatabase waits until all collections drops in the database have propagated to a majority of the replica set members.
  • For commands run on replica sets and sharded clusters, the response documents include the operationTime and $clusterTime. See db.runCommand and db.adminCommand.

Wire Protocol and Compression

  • MongoDB 3.6 introduces a new wire protocol opcode called OP_MSG. This opcode’s message format is extensible and designed to subsume the functionality of other opcodes.
  • Added support for the zlib compressor for --networkMessageCompressors option (or net.compression.compressors setting if using the configuration file). --networkMessageCompressors option (or net.compression.compressors setting) enables network compression for communication among mongod, mongos, mongo shell, and drivers that support the OP_COMPRESSED message format.
  • Enables snappy network compression for communication, by default, among mongod, mongos, and mongo shell.

Read Concern

FTDC

MongoDB 3.6 adds support for Diagnostics Capture (also known as FTDC) in mongos. In previous versions, the feature is available for mongod only. See Diagnostic Parameters.

Note

FTDC is enabled by default.

Additional Enhancements

MongoDB 3.6 includes the following enhancements:

  • Added support for specifying full Unix domain socket paths with --bind_ip.
  • mongod now offers a --timeZoneInfo option. Use this option to specify the path to your system time zone database. The default configuration file included with Linux and macOS packages sets this to /usr/share/zoneinfo.
  • Date operations now accept consistent date ranges across all supported operating systems. You may safely work with years in the range 0 through 9999.
  • The new honorSystemUmask startup option for mongod causes new files created by MongoDB to have the read/write permissions specified by the umask of the user who runs the mongod process. Only available on Linux and macOS systems.
  • The maxWriteBatchSize limit of a database, which indicates the maximum number of write operations permitted in a write batch, raises from 1,000 to 100,000.
  • The planCacheListPlans database command produces the same output as the PlanCache.getPlansByQuery() shell method. The output from both operations now includes a timestamp for when the plans were generated.
  • The new KeysRotationIntervalSec server parameter specifies the number of seconds for which an HMAC signing key is valid before rotating to the next one.

Changes Affecting Compatibility

Some changes can affect compatibility and may require user actions. For a detailed list of compatibility changes, see Compatibility Changes in MongoDB 3.6.

Upgrade Procedures

Note

To upgrade, the 3.4 instances must have featureCompatibilityVersion set to 3.4. For more information, see View FeatureCompatibilityVersion and setFeatureCompatibilityVersion.

For upgrade instructions, see:

If you need guidance on upgrading to 3.6, MongoDB offers major version upgrade services to help ensure a smooth transition without interruption to your MongoDB application.

Download

To download the MongoDB 3.6, go to the MongoDB Download Center

Known Issues in 3.6.0

  • SERVER-31760:
    $expr does not use indexes for equality match against field, including when used as part of a $lookup aggregation stage with foreign pipeline.
  • TOOLS-1827:
    When using a URI with SRV, fetched TXT records will be ignored if no query parameters are specified in the command line URI. To get around this, explicitly specify the SSL setting used to communicate with the database (either ssl=true or ssl=false) in the URI query string.
  • WT-3724:
    MongoDB 3.6 is not tested on APFS, the new filesystem in macOS 10.13 and may encounter errors.
  • Operations that build in-memory structures are not causally consistent; however, only some operations return errors when associated with causally consistent sessions. See Causal Consistency Limitations.

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.