From afef0e403acc56af00f1df4bf02fb05d263e09c5 Mon Sep 17 00:00:00 2001 From: jason-price-mongodb Date: Tue, 24 Aug 2021 11:42:56 -0700 Subject: [PATCH 001/109] execution-stats-fix --- source/indexes.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/indexes.txt b/source/indexes.txt index eb6a7646d2f..2d3458a1b5e 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -295,8 +295,6 @@ page `. .. include:: /includes/extracts/collation-index-type-restrictions.rst -.. _indexes-covered-queries: - Covered Queries --------------- From 26054f94e7a5e3899e39fcd7a32dc656026b39ba Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Wed, 25 Aug 2021 08:45:51 -0400 Subject: [PATCH 002/109] DOCS-13584 Add reference that commands fail against system collections in 4.4 notes --- source/release-notes/4.4.txt | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/source/release-notes/4.4.txt b/source/release-notes/4.4.txt index 92d95b156bb..c1f8e0f91d4 100644 --- a/source/release-notes/4.4.txt +++ b/source/release-notes/4.4.txt @@ -1042,6 +1042,10 @@ When creating a collection inside a transaction: :dbcommand:`create` command or its helper :method:`db.createCollection()`. +- The :method:`db.createCollection()` method fails if + executed against a + :doc:`system collection `. + When :ref:`creating an index ` inside a transaction: @@ -1051,6 +1055,10 @@ inside a transaction: - You can create an index on a new empty collection created earlier in the same transaction. +- The :method:`db.collection.createIndex()` method + fails if executed against a + :doc:`system collection `. + For more details, see :ref:`transactions-create-collections-indexes`. MongoDB 4.4 adds a new parameter From 64931392330a259e278f95c1edc93742f10d4a8f Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Wed, 18 Aug 2021 12:02:54 -0400 Subject: [PATCH 003/109] DOCS-13896 Added configTime and topologyTime with timestamp fields to Sharded cluster tab --- source/includes/currentOp-output-example.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/includes/currentOp-output-example.rst b/source/includes/currentOp-output-example.rst index b8ca98380fd..09bc864d258 100644 --- a/source/includes/currentOp-output-example.rst +++ b/source/includes/currentOp-output-example.rst @@ -342,6 +342,8 @@ "op" : , "ns" : , "command" : , + "configTime" : , // Starting in 5.0 + "topologyTime" : , // Starting in 5.0 "planSummary": , "prepareReadConflicts" : , "writeConflicts" : , From 9510fd68f8532a4aa3cfa0086463323a95d83f98 Mon Sep 17 00:00:00 2001 From: Dave Cuthbert Date: Mon, 23 Aug 2021 16:06:11 -0400 Subject: [PATCH 004/109] DOCSP-14117 Timezone datafile update --- source/includes/fact-timeZoneInfo.rst | 15 ++++++++------- source/includes/warning-timeZoneInfo.rst | 14 ++++++++++++++ source/reference/configuration-options.txt | 3 ++- source/reference/program/mongod.txt | 4 +++- source/reference/program/mongos.txt | 3 ++- 5 files changed, 29 insertions(+), 10 deletions(-) create mode 100644 source/includes/warning-timeZoneInfo.rst diff --git a/source/includes/fact-timeZoneInfo.rst b/source/includes/fact-timeZoneInfo.rst index 9af599d1cfc..fad8926aa94 100644 --- a/source/includes/fact-timeZoneInfo.rst +++ b/source/includes/fact-timeZoneInfo.rst @@ -1,12 +1,13 @@ The full path from which to load the time zone database. If this option is not provided, then MongoDB will use its built-in time zone database. -The configuration file included with Linux and macOS packages sets the time -zone database path to ``/usr/share/zoneinfo`` by default. +The configuration file included with Linux and macOS packages sets the +time zone database path to ``/usr/share/zoneinfo`` by default. The built-in time zone database is a copy of the `Olson/IANA time zone -database `_. It is updated along with MongoDB -releases, but the release cycle of the time zone database differs from the -release cycle of MongoDB. A copy of the most recent release of the time zone -database can be downloaded from -https://downloads.mongodb.org/olson_tz_db/timezonedb-latest.zip. +database `_. It is updated along with +MongoDB releases, but the time zone database release cycle +differs from the MongoDB release cycle. The most recent release of +the time zone database is available on our `download site +`_. + diff --git a/source/includes/warning-timeZoneInfo.rst b/source/includes/warning-timeZoneInfo.rst new file mode 100644 index 00000000000..2c3e81e2cc8 --- /dev/null +++ b/source/includes/warning-timeZoneInfo.rst @@ -0,0 +1,14 @@ +.. warning:: + + MongoDB uses the third party `timelib + `_ library to provide accurate + conversions between timezones. Due to a recent update, ``timelib`` + could create inaccurate time zone conversions in older versions of + MongoDB. + + To explicitly link to the time zone database in versions of MongoDB + prior to 5.0, 4.4.7, 4.2.14, and 4.0.25, download the `time zone + database + `_. + and use the :option:`timeZoneInfo ` parameter. + diff --git a/source/reference/configuration-options.txt b/source/reference/configuration-options.txt index 50ec1d45002..cf01997e585 100644 --- a/source/reference/configuration-options.txt +++ b/source/reference/configuration-options.txt @@ -734,7 +734,8 @@ Core Options *Type*: string .. include:: /includes/fact-timeZoneInfo.rst - + + .. include:: /includes/warning-timeZoneInfo.rst .. _free-monitoring-configuration-options: diff --git a/source/reference/program/mongod.txt b/source/reference/program/mongod.txt index b4accbc003e..d6cfb153029 100644 --- a/source/reference/program/mongod.txt +++ b/source/reference/program/mongod.txt @@ -807,7 +807,9 @@ Core Options wget https://downloads.mongodb.org/olson_tz_db/timezonedb-latest.zip unzip timezonedb-latest.zip mongod --timeZoneInfo timezonedb-2017b/ - + + .. include:: /includes/warning-timeZoneInfo.rst + .. seealso:: :setting:`processManagement.timeZoneInfo`. diff --git a/source/reference/program/mongos.txt b/source/reference/program/mongos.txt index 37837a7cf2c..c35404b688b 100644 --- a/source/reference/program/mongos.txt +++ b/source/reference/program/mongos.txt @@ -607,7 +607,8 @@ Core Options wget https://downloads.mongodb.org/olson_tz_db/timezonedb-latest.zip unzip timezonedb-latest.zip mongos --timeZoneInfo timezonedb-2017b/ - + + .. include:: /includes/warning-timeZoneInfo.rst .. option:: --outputConfig From ed7991e4f0c77237e15e1239eed207bd880fad85 Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Wed, 18 Aug 2021 13:14:44 -0400 Subject: [PATCH 005/109] (DOCS-14741): Future-proof patch release warnings --- source/release-notes/4.4.txt | 8 ++++---- source/release-notes/5.0.txt | 9 ++++----- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/source/release-notes/4.4.txt b/source/release-notes/4.4.txt index c1f8e0f91d4..0a166513f92 100644 --- a/source/release-notes/4.4.txt +++ b/source/release-notes/4.4.txt @@ -44,8 +44,8 @@ Issues fixed: .. warning:: MongoDB version 4.4.7 is not recommended for production use due to a - critical issue, :issue:`SERVER-58936`. The issue is fixed in version - 4.4.8. + critical issue, :issue:`SERVER-58936`, fixed in later versions. + Use the latest available patch release version. Issues fixed: @@ -95,8 +95,8 @@ Issues fixed: .. warning:: MongoDB version 4.4.5 is not recommended for production use due to a - critical issue, :issue:`WT-7426`. The issue is fixed in version - 4.4.6. + critical issue, :issue:`WT-7426`, fixed in later versions. + Use the latest available patch release version. Issues fixed: diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index fcd081c0255..f15463df2a0 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -48,12 +48,11 @@ Issues fixed: .. warning:: MongoDB version 5.0.1 is not recommended for production use due to a - critical issue, :issue:`SERVER-58936`. The issue is fixed in version - 5.0.2. + 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 @@ -70,8 +69,8 @@ Issues fixed: .. warning:: MongoDB version 5.0.0 is not recommended for production use due to a - critical issue, :issue:`SERVER-58936`. The issue is fixed in version - 5.0.2. + 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: From 660765c3ef55873deaa3a5731fe4b80955cb1893 Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Wed, 18 Aug 2021 11:57:08 -0400 Subject: [PATCH 006/109] (DOCS-14449): maxCatchUpPercentageBeforeBlockingWrites server parameter --- source/reference/command/moveChunk.txt | 9 +++++ source/reference/parameters.txt | 34 +++++++++++++++++++ source/release-notes/5.0.txt | 18 ++++++++++ .../migrate-chunks-in-sharded-cluster.txt | 2 ++ 4 files changed, 63 insertions(+) diff --git a/source/reference/command/moveChunk.txt b/source/reference/command/moveChunk.txt index 6cceb331a2f..d415077f5d8 100644 --- a/source/reference/command/moveChunk.txt +++ b/source/reference/command/moveChunk.txt @@ -220,5 +220,14 @@ while :dbcommand:`moveChunk` is running, you may see this error. You may retry the :dbcommand:`moveChunk` operation without side effects. +``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. + .. admin-only diff --git a/source/reference/parameters.txt b/source/reference/parameters.txt index 966c43c2983..954d91bdd5d 100644 --- a/source/reference/parameters.txt +++ b/source/reference/parameters.txt @@ -2735,6 +2735,40 @@ Sharding Parameters - :parameter:`readHedgingMode` - :ref:`mongos-hedged-reads` +.. parameter:: maxCatchUpPercentageBeforeBlockingWrites + + .. versionadded:: 5.0 (*Also available starting in 4.4.7, 4.2.15, 4.0.26*) + + *Type*: integer + + *Default*: 10 + + |mongod-only| + + For :dbcommand:`moveChunk` operations, specifies the maximum + percentage of untrasferred data allowed by the migration protocol + (expressed in percentage of the total chunk size) to + transition from the ``catchup`` phase to the ``commit`` phase. + + Setting a higher catchup percentage can decrease the amount of time + it takes for the migration to complete at the cost of increased + latency during concurrent :method:`upsert ` + and :method:`delete ` operations. + + For example, to set the maximum percentage to 20, you can issue the + followingduring startup: + + .. code-block:: bash + + mongod --setParameter maxCatchUpPercentageBeforeBlockingWrites=20 + + You cannot change + :parameter:`maxCatchUpPercentageBeforeBlockingWrites` during runtime. + + .. seealso:: + + `Live Migration Protocol `__ + .. parameter:: readHedgingMode .. versionadded:: 4.4 diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index f15463df2a0..7e71d3b8ee5 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -526,6 +526,24 @@ 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 diff --git a/source/tutorial/migrate-chunks-in-sharded-cluster.txt b/source/tutorial/migrate-chunks-in-sharded-cluster.txt index 81d0f4140e2..074daa31c56 100644 --- a/source/tutorial/migrate-chunks-in-sharded-cluster.txt +++ b/source/tutorial/migrate-chunks-in-sharded-cluster.txt @@ -1,3 +1,5 @@ +.. _migrate-chunks-sharded-cluster: + =================================== Migrate Chunks in a Sharded Cluster =================================== From fe07d06312896b56352d676df1458f1342d04256 Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Fri, 27 Aug 2021 11:47:34 -0400 Subject: [PATCH 007/109] (DOCS-14764): Fix typo in 5.0 compat notes --- source/release-notes/5.0-compatibility.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt index 5c16efd1ec8..192d01b98e2 100644 --- a/source/release-notes/5.0-compatibility.txt +++ b/source/release-notes/5.0-compatibility.txt @@ -415,7 +415,7 @@ protocol, upgrade your driver to a 5.0-compatible version. Any code explicitly using :dbcommand:`getLastError`, :method:`db.getLastError()`, or :method:`db.getLastErrorObj()` should instead use the CRUD API to issue the write with -the designed :doc:`write concern `. +the desired :doc:`write concern `. Information about the success or failure of the write operation will be provided directly by the driver as a return value. From de6ef653ba24aac828a44f62eda5594c3d82fbdc Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Thu, 26 Aug 2021 08:39:51 -0400 Subject: [PATCH 008/109] DOCS-14440 Update getlast.error in replica set config command REMOVED --- .../5.0-changes-getLastErrorDefaults-removed.rst | 5 +++++ source/reference/replica-configuration.txt | 12 ++---------- source/release-notes/5.0.txt | 5 +++++ 3 files changed, 12 insertions(+), 10 deletions(-) create mode 100644 source/includes/5.0-changes-getLastErrorDefaults-removed.rst diff --git a/source/includes/5.0-changes-getLastErrorDefaults-removed.rst b/source/includes/5.0-changes-getLastErrorDefaults-removed.rst new file mode 100644 index 00000000000..3c12e925c21 --- /dev/null +++ b/source/includes/5.0-changes-getLastErrorDefaults-removed.rst @@ -0,0 +1,5 @@ +Starting in MongoDB 5.0, you cannot specify a default write concern with +:rsconf:`settings.getLastErrorDefaults` other than the default of +``{ w: 1, wtimeout: 0 }`` . Instead, use the +:dbcommand:`setDefaultRWConcern` command to set the default read or +write concern configuration for a replica set or sharded cluster. diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index 5ea1619cd34..51122465f74 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -483,19 +483,11 @@ Replica Set Configuration Fields *Type*: document - A document that specifies the :doc:`write concern - ` for the replica set. The - replica set will use this write concern only when :ref:`write - operations ` or - :dbcommand:`getLastError` specify no other write concern. - - If :rsconf:`settings.getLastErrorDefaults` is - not set, the default write concern for the replica set only - requires confirmation from the primary. + Unavailable starting in MongoDB 5.0 .. important:: - .. include:: /includes/extracts/4.4-changes-getLastErrorDefaults-deprecation.rst + .. include:: /includes/5.0-changes-getLastErrorDefaults-removed.rst .. rsconf:: settings.getLastErrorModes diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 7e71d3b8ee5..aac11a3705c 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -357,6 +357,11 @@ Starting in MongoDB 5.0, these database commands and Replica Sets ------------ +Removed Customizable Values For getLastErrorDefaults +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/5.0-changes-getLastErrorDefaults-removed.rst + ``hello`` Command ~~~~~~~~~~~~~~~~~ From 84704db9c3ac3b7bee2bddc4d2b20b62a830ef77 Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Fri, 27 Aug 2021 15:21:17 -0400 Subject: [PATCH 009/109] Small release and compat notes refactor --- source/reference/replica-configuration.txt | 2 +- source/release-notes/5.0-compatibility.txt | 110 ++++++++++++--------- source/release-notes/5.0.txt | 15 --- 3 files changed, 67 insertions(+), 60 deletions(-) diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index 51122465f74..ac3af0c64fd 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -483,7 +483,7 @@ Replica Set Configuration Fields *Type*: document - Unavailable starting in MongoDB 5.0 + Unavailable starting in MongoDB 5.0. .. important:: diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt index 192d01b98e2..d4787b7fd04 100644 --- a/source/release-notes/5.0-compatibility.txt +++ b/source/release-notes/5.0-compatibility.txt @@ -168,6 +168,11 @@ Automatic Reconfiguration for New Voting Replica Set Members .. include:: /includes/extracts/initial-sync-semantics.rst +Removed Customizable Values For getLastErrorDefaults +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/5.0-changes-getLastErrorDefaults-removed.rst + Read Concern ``snapshot`` on Capped Collections ----------------------------------------------- @@ -303,86 +308,103 @@ issued but the server will not abort. General Changes --------------- -- .. include:: /includes/5.0-changes/no-direct-write-system-views.rst +Starting in MongoDB 5.0: + +- For :ref:`featureCompatibilityVersion ` set to ``"5.0"`` or + greater, users can no longer write directly to the + :data:`.system.views` collection. -- Starting in MongoDB 5.0, the :dbcommand:`reIndex` command and the +- The :dbcommand:`reIndex` command and the :method:`db.collection.reIndex()` shell method may only be run on :term:`standalone` instances. -- Starting in MongoDB 5.0, the number of :doc:`aggregation pipeline - stages ` allowed in a single +- The number of :doc:`aggregation pipeline stages + ` allowed in a single pipeline is limited to 1000. -- Starting in MongoDB 5.0, dropping the final collection in a database - (or dropping the database itself) when - :setting:`~storage.directoryPerDB` or :option:`--directoryperdb` is - enabled deletes the newly empty subdirectory for that database. +- Dropping the final collection in a database (or dropping the database + itself) when :setting:`~storage.directoryPerDB` or + :option:`--directoryperdb` is enabled deletes the newly empty + subdirectory for that database. -- Starting in MongoDB 5.0 (and 4.4.3, 4.2.12, 4.0.22, and 3.6.22), the - :expression:`$subtract` aggregation operator will convert the data +- The :expression:`$subtract` aggregation operator will convert the data type of the result if necessary to accurately represent the result - value. See :expression:`$subtract` for the specific conversions. + value. See :expression:`$subtract` for the specific conversions. This + change also applies to MongoDB 4.4.3+, 4.2.12+, 4.0.22+, and 3.6.22+. -- MongoDB 5.0 removes the ``--serviceExecutor`` command-line option and +- MongoDB removes the ``--serviceExecutor`` command-line option and the corresponding ``net.serviceExecutor`` configuration option. -- Starting in MongoDB 5.0, you may not authenticate as multiple - simultaneous users on the same client session if the - :option:`--apiStrict` option is set. Attempting to - authenticate as a new user while currently logged in as an existing +- You may not authenticate as multiple simultaneous users on the same + client session if the :option:`--apiStrict` option is set. Attempting + to authenticate as a new user while currently logged in as an existing user when the :option:`--apiStrict` option is set will generate an error message once per authentication attempt. If you are not using the :option:`--apiStrict` option, authenticating as a new user while currently logged in as an existing user will write a warning to the log once per authentication attempt. -- Starting in MongoDB 5.0, the - :ref:`weights ` option is only allowed - for ``$text`` indexes. +- The :ref:`weights ` option is only allowed for + ``$text`` indexes. + +- You must explicitly set the global default + :ref:`write concern ` before attempting to reconfigure + a :ref:`non-sharded ` + :term:`replica set ` with a :doc:`configuration + ` that would change the implicit + default write concern. To set the global default write concern, use + the :dbcommand:`setDefaultRWConcern` command. -- .. include:: /includes/fact-set-global-write-concern-before-reconfig.rst Deprecations ~~~~~~~~~~~~ -- :binary:`~bin.mongo` +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Deprecated + + - Description + + * - :binary:`~bin.mongo` - The legacy ``mongo`` shell has been deprecated in MongoDB v5.0. The - replacement is :binary:`~bin.mongosh`. + - The legacy ``mongo`` shell has been deprecated in MongoDB v5.0. The + replacement is :binary:`~bin.mongosh`. -- :method:`db.printSlaveReplicationInfo()` + * - :method:`db.printSlaveReplicationInfo()` - .. include:: /includes/deprecated-db.printSlaveReplicationInfo.rst + - .. include:: /includes/deprecated-db.printSlaveReplicationInfo.rst -- :method:`rs.printSlaveReplicationInfo()` + * - :method:`rs.printSlaveReplicationInfo()` - .. include:: /includes/deprecated-rs.printSlaveReplicationInfo.rst + - .. include:: /includes/deprecated-rs.printSlaveReplicationInfo.rst -- :setting:`security.clusterIpSourceWhitelist` + * - :setting:`security.clusterIpSourceWhitelist` - *Deprecated in version 5.0:* Use - :setting:`security.clusterIpSourceAllowlist` instead. + - *Deprecated in version 5.0:* Use + :setting:`security.clusterIpSourceAllowlist` instead. -- :option:`--clusterIpSourceWhitelist` - - *Deprecated in version 5.0:* Use :option:`--clusterIpSourceAllowlist` - instead. + * - :option:`--clusterIpSourceWhitelist` + + - *Deprecated in version 5.0:* Use :option:`--clusterIpSourceAllowlist` + instead. -- :dbcommand:`logout` + * - :dbcommand:`logout` - *Deprecated in version 5.0:* Disconnect from the server to end your - session instead. + - *Deprecated in version 5.0:* Disconnect from the server to end your + session instead. -- :method:`db.logout()` + * - :method:`db.logout()` - *Deprecated in version 5.0:* Disconnect from the server to end your - session instead. + - *Deprecated in version 5.0:* Disconnect from the server to end your + session instead. -- :ref:`local ` audit message field + * - :ref:`local ` audit message field - *Deprecated in version 5.0:* Use the ``localEndpoint`` field in - the :ref:`clientMetadata ` audit message - instead. + - *Deprecated in version 5.0:* Use the ``localEndpoint`` field in + the :ref:`clientMetadata ` audit message + instead. .. _deprecated-wire-protocol-opcodes: diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index aac11a3705c..559a6ee7670 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -85,16 +85,6 @@ 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. -Deprecate Map Reduce Operation ------------------------------- - -Starting in version 5.0, MongoDB deprecates the -:doc:`map-reduce` operation. - -For examples of aggregation pipeline alternatives to map-reduce -operations, see :doc:`/reference/map-reduce-to-aggregation-pipeline` and -:doc:`/tutorial/map-reduce-examples`. - Aggregation ----------- @@ -357,11 +347,6 @@ Starting in MongoDB 5.0, these database commands and Replica Sets ------------ -Removed Customizable Values For getLastErrorDefaults -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/5.0-changes-getLastErrorDefaults-removed.rst - ``hello`` Command ~~~~~~~~~~~~~~~~~ From b09aee51ad37f2b2d8f83472971ee42afee9f35f Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Fri, 27 Aug 2021 15:50:55 -0400 Subject: [PATCH 010/109] Re-add map reduce deprecation --- source/release-notes/5.0-compatibility.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt index d4787b7fd04..79947e5e49c 100644 --- a/source/release-notes/5.0-compatibility.txt +++ b/source/release-notes/5.0-compatibility.txt @@ -287,6 +287,16 @@ When run against :binary:`~bin.mongos`, the ``shards`` field in the collection on a particular shard. Size values in the ``shards`` field are expressed as integers. +Map-Reduce +---------- + +Starting in version 5.0, MongoDB deprecates the +:doc:`map-reduce` operation. + +For examples of aggregation pipeline alternatives to map-reduce +operations, see :doc:`/reference/map-reduce-to-aggregation-pipeline` and +:doc:`/tutorial/map-reduce-examples`. + Auditing -------- From 6a0801e1cd7f9d4a4a754e9b670bfd970d6bda9d Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Mon, 23 Aug 2021 10:39:38 -0400 Subject: [PATCH 011/109] DOCS-14290 Mongosh db.currentOp now uses agg stage --- source/includes/5.0-fact-currentop.rst | 9 +++++++++ source/reference/command/currentOp.txt | 5 +---- source/reference/method/db.currentOp.txt | 2 +- source/release-notes/5.0.txt | 7 +++++++ 4 files changed, 18 insertions(+), 5 deletions(-) create mode 100644 source/includes/5.0-fact-currentop.rst diff --git a/source/includes/5.0-fact-currentop.rst b/source/includes/5.0-fact-currentop.rst new file mode 100644 index 00000000000..90cb4a7faa4 --- /dev/null +++ b/source/includes/5.0-fact-currentop.rst @@ -0,0 +1,9 @@ +Starting in MongoDB 5.0, the :pipeline:`$currentOp` aggregation +stage is used when running the helper method :method:`db.currentOp()` +with :binary:`~bin.mongosh`. + +Given this, in the 5.0 version of the shell and with mongosh, +:method:`db.currentOp()` result sets are not subject to the +:ref:`16MB BSON document return size` +document return size limit for documents of the previous legacy +:binary:`~bin.mongo` versions. \ No newline at end of file diff --git a/source/reference/command/currentOp.txt b/source/reference/command/currentOp.txt index 9b95c889658..fd506c4843e 100644 --- a/source/reference/command/currentOp.txt +++ b/source/reference/command/currentOp.txt @@ -26,12 +26,9 @@ Definition { currentOp: 1 } - :binary:`~bin.mongosh` provides the :method:`db.currentOp()` - wrapper for the :dbcommand:`currentOp` command. - .. note:: - .. include:: /includes/fact-currentop.rst + .. include:: /includes/5.0-fact-currentop.rst Behavior -------- diff --git a/source/reference/method/db.currentOp.txt b/source/reference/method/db.currentOp.txt index 747a6422db3..d82d4cc08bd 100644 --- a/source/reference/method/db.currentOp.txt +++ b/source/reference/method/db.currentOp.txt @@ -25,7 +25,7 @@ Definition .. note:: - .. include:: /includes/fact-currentop.rst + .. include:: /includes/5.0-fact-currentop.rst Syntax ~~~~~~ diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 559a6ee7670..b09a7aea1e2 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -476,6 +476,13 @@ 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 1d02085a21e0b4a504b78cee2d98d13a73607a88 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Mon, 30 Aug 2021 17:35:06 +0200 Subject: [PATCH 012/109] DOCSP-18309: Remove array restriction on time series --- source/core/timeseries-collections.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/core/timeseries-collections.txt b/source/core/timeseries-collections.txt index 1d3c3285c9d..24dadfe435e 100644 --- a/source/core/timeseries-collections.txt +++ b/source/core/timeseries-collections.txt @@ -109,8 +109,7 @@ When creating a time series collection, specify the following options: metadata should rarely, if ever, change. The name of the specified field may not be ``_id`` or the same as - the ``timeseries.timeField``. The field can be of any type except - array. + the ``timeseries.timeField``. The field can be of any type. * - ``timeseries.granularity`` From 7ac1ba860fb2622f3ad776ae91e5d09ec46fef5c Mon Sep 17 00:00:00 2001 From: corryroot <72401712+corryroot@users.noreply.github.com> Date: Mon, 30 Aug 2021 15:22:25 -0400 Subject: [PATCH 013/109] (DOCSP-18432): Backport DOCSP-17931 to v5.0. (#5755) * (DOCSP-17931): Added Atlas connection string note. * (DOCSP-17931): Incorporated Jeff's feedback. * (DOCSP-17931): Incorporated Jeff's feedback. * (DOCSP-17931): Incorporated JD's feedback. --- source/reference/connection-string.txt | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/source/reference/connection-string.txt b/source/reference/connection-string.txt index 15e27b90a10..a1952d08277 100644 --- a/source/reference/connection-string.txt +++ b/source/reference/connection-string.txt @@ -122,6 +122,25 @@ Examples .. include:: /includes/fact-pct-encode-uri.rst + - id: atlas + name: Atlas Deployment + content: | + + MongoDB Atlas provides the connection strings for + your deployment when you click the :atlas:`Connect + ` button in the Atlas UI. + To register a new Atlas account, start at the + :mdbacct:`MongoDB Atlas registration page + `. To learn more, see + :atlas:`Get Started with Atlas `. + + Your Atlas connection string might resemble the following + example: + + .. code-block:: bash + + mongosh "mongodb+srv://cluster0.example.mongodb.net myFirstDatabase" --username JohnDoe + For more examples, see :ref:`connections-connection-examples`. Components From fc24b8e9cfb299e24ee7e8d1bff6fc212b3291f9 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Tue, 31 Aug 2021 17:25:36 +0200 Subject: [PATCH 014/109] DOCSP-18453: Fix timeseries insert bug --- source/core/timeseries-collections.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/core/timeseries-collections.txt b/source/core/timeseries-collections.txt index 24dadfe435e..9b07a1f8182 100644 --- a/source/core/timeseries-collections.txt +++ b/source/core/timeseries-collections.txt @@ -226,7 +226,7 @@ following command: .. code-block:: javescript db.weather.findOne({ - "timestamp": {"$date": "2021-05-11T04:00:00.000Z"} + "timestamp": ISODate("2021-05-18T00:00:00.000Z") }) Run Aggregations on a Time Series Collection From 4c39898a5495633c0299d560628af2f8044905ba Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Tue, 31 Aug 2021 13:25:32 -0400 Subject: [PATCH 015/109] (DOCS-14769): Preparing changelog for 5.0.3 --- changelogs/generatechangelogs.py | 4 +- config/changelog_conf.yaml | 3 + source/includes/changelogs/releases/5.0.3.rst | 233 ++++++++++++++++++ source/release-notes/5.0-changelog.txt | 2 + source/release-notes/5.0.txt | 23 ++ 5 files changed, 263 insertions(+), 2 deletions(-) create mode 100644 source/includes/changelogs/releases/5.0.3.rst diff --git a/changelogs/generatechangelogs.py b/changelogs/generatechangelogs.py index 19bdd1db6cc..5288abed4f8 100644 --- a/changelogs/generatechangelogs.py +++ b/changelogs/generatechangelogs.py @@ -63,7 +63,7 @@ def get_jira_issues(fixVersion): return issues -def get_issue_structure(config, issues): +def get_issue_structure(config, issues, version): """ Group the JIRA issues by component. Structure headings and subheadings. @@ -227,7 +227,7 @@ def main(): config = get_config() # Generate issue headings based on component config - issue_headings = get_issue_structure(config, issues) + issue_headings = get_issue_structure(config, issues, fixVersion) # Convert the issue headings into rst changelog_rst = generate_changelog_rst(config, issue_headings, fixVersion) diff --git a/config/changelog_conf.yaml b/config/changelog_conf.yaml index 1ca1e251940..af87f7e7c15 100644 --- a/config/changelog_conf.yaml +++ b/config/changelog_conf.yaml @@ -12,7 +12,9 @@ groups: "Query": - Querying - Query Execution + - Query Language - Indexing + - Index Maintenance - Geo - Text Search "Write Operations": @@ -44,6 +46,7 @@ groups: - HTTP Console "Build and Packaging": - Build + - Build/compile - Packaging - Mobile "Internals": diff --git a/source/includes/changelogs/releases/5.0.3.rst b/source/includes/changelogs/releases/5.0.3.rst new file mode 100644 index 00000000000..e4cb1da9ccc --- /dev/null +++ b/source/includes/changelogs/releases/5.0.3.rst @@ -0,0 +1,233 @@ +.. _5.0.3-changelog: + +5.0.3 Changelog +--------------- + +Security +~~~~~~~~ + +:issue:`SERVER-57716` Partial certificate chain in PEM causes validation failure in OCSP + +Sharding +~~~~~~~~ + +- :issue:`SERVER-27383` Require --replSet with --configsvr +- :issue:`SERVER-50937` Make resharding coordinator support recovery +- :issue:`SERVER-55824` Make ssl_get_more.js start shards as replicaset +- :issue:`SERVER-57487` Update chunks during setFCV 4.4 «--» 5.0 must not block balancing for long periods +- :issue:`SERVER-57953` _flushReshardingStateChange attempts to refresh shard version while another refresh already pending, leading to invariant failure +- :issue:`SERVER-58081` _flushReshardingStateChange from coordinator races with donor shard acquiring critical section, stalling the resharding operation +- :issue:`SERVER-58315` Change jstests to not use standalone nodes as shards nor config server +- :issue:`SERVER-58342` Allow specifying of reshardCollection zones to be empty +- :issue:`SERVER-58603` ensureTempReshardingCollectionExistsWithIndexes may hit an invariant if collection was previously dropped +- :issue:`SERVER-58702` Fix comment in ReshardingDataReplication and update its member declaration order +- :issue:`SERVER-58720` DropDatabaseCoordinator must not re-execute destructive logic after removing CSRS metadata +- :issue:`SERVER-58781` ReshardingCoordinatorObserver should not fulfill promises if the "donors" or "recipients" fields are empty +- :issue:`SERVER-58868` Enable/Remove a commented moveChunk + AllowMigrations test +- :issue:`SERVER-58917` Wait until donors/recipients are aware that coordinator has persisted decision before expecting successful collMod, createIndexes, and dropIndexes in resharding_prohibited_commands.js +- :issue:`SERVER-58926` ReshardingDonor should not try to set the stop time of the critical section if it the critical section was already released +- :issue:`SERVER-59114` ReshardingOplogFetcher stops fetching new oplog entries if remote donor shard responds with Interruption exception +- :issue:`SERVER-59292` completion future can be set more than once because of WithAutomaticRetry + +Replication +~~~~~~~~~~~ + +- :issue:`SERVER-58133` Use split replication tasks because they are timing out because of "majority" implicit default write concern +- :issue:`SERVER-58987` Fix read_only_test.js to avoid start point beyond end point during replication recovery. +- :issue:`SERVER-59083` catchup_takeover_with_higher_config.js needs to be excluded from multiversion suite for last-continuous +- :issue:`SERVER-59131` Wrap rawMongoProgramOutput search in an assert.soon in implicit_default_write_concern_upgrade_shards.js +- :issue:`SERVER-59212` Make sure node stepped down before waiting for catchup takeover in catchup_takeover_with_higher_config.js +- :issue:`SERVER-59478` Move serverStatus command before taking RSTL in catchup_takeover_with_higher_config.js + +Query +~~~~~ + +- :issue:`SERVER-54791` Excessive file descriptor usage during index build with external sort +- :issue:`SERVER-57448` fix ExpressionParams::parseTwoDParams() to handle int values in key patterns that are out of bounds +- :issue:`SERVER-57667` Improve processing speed for resharding's collection cloning pipeline + +Storage +~~~~~~~ + +:issue:`SERVER-58744` applyOps on capped collections can violate the multi-timestamp constraint + +Build and Packaging +~~~~~~~~~~~~~~~~~~~ + +:issue:`WT-7830` Migrate the python setup scripts to use cmake + +Internals +~~~~~~~~~ + +- :issue:`SERVER-52007` Create feature flag for Integration work to support new $search parameters +- :issue:`SERVER-53001` Complete TODO listed in SERVER-47323 +- :issue:`SERVER-53437` Architecture Guide updates for Change the Default Write Concern to Majority +- :issue:`SERVER-54735` Executor shutdown can cause AsyncTry-until to set its result with ErrorCodes::BrokenPromise +- :issue:`SERVER-55589` replSetMaintenance command does not take the RSTL +- :issue:`SERVER-55664` Support clustered _id indexes in ephemeralForTest +- :issue:`SERVER-55760` Cancelation tests for AsyncTry are racy +- :issue:`SERVER-55966` AsyncTry no longer handles exceptions from until() lambda, leading to process crash +- :issue:`SERVER-56235` Evaluate index types that are dependent on a collection not being clustered, rather that it not being time-series +- :issue:`SERVER-56492` Normalize time-series metadata with array type +- :issue:`SERVER-56580` Promote build-tools=next to stable +- :issue:`SERVER-56763` Validate collection epoch when not holding a DB lock for $merge +- :issue:`SERVER-56800` Fail addShard if CWWC disagrees with existing CWWC on cluster +- :issue:`SERVER-56844` Fassert shard server on startup if DWCF=w:1 and no CWWC set +- :issue:`SERVER-56845` Fail addShard if DWCF=w:1 and no CWWC is set +- :issue:`SERVER-56846` Fail reconfig for shard server if it would change DWCF and CWWC is not set +- :issue:`SERVER-57086` Do not set inherited maxTimeMSOpOnly deadline on hello command in v4.4 +- :issue:`SERVER-57140` Fix up perl relics from migrated shell scripts +- :issue:`SERVER-57262` Allow nodes to vote for candidates with higher config +- :issue:`SERVER-57279` Update the FCV constant in the logkeeper snapshot workload +- :issue:`SERVER-57360` Log additional debug info for the "invariant (_requests.empty());" in ~LockerImpl +- :issue:`SERVER-57387` create_view_does_not_take_database_X.js should check its insert +- :issue:`SERVER-57435` Exclude views_coll_stats.js from causally_consistent test suites +- :issue:`SERVER-57465` remove_newly_added_field_after_finishing_initial_sync.js does not wait until the new configuration has been replicated +- :issue:`SERVER-57520` Make set_audit_config.js test start shard as replicaset +- :issue:`SERVER-57575` Investigate create_view_does_not_take_database_X.js failures on Windows +- :issue:`SERVER-57585` oplog_visibility.js prints null 'next' timestamp for missing oplog entry +- :issue:`SERVER-57599` DocumentSourceBucketAuto returning eof when disposed +- :issue:`SERVER-57615` Reset CWWC to w:majority for tests that don't create/stop the replica set +- :issue:`SERVER-57616` Wait for secondary to load signing keys in disable_cluster_time_gossiping_in_unreadable_state.js +- :issue:`SERVER-57617` Have the OplogFetcher in Tenant Migrations do an aggregation query instead of a find +- :issue:`SERVER-57630` Enable SSL_OP_NO_RENEGOTIATION on Ubuntu 18.04 when running against OpenSSL 1.1.1 +- :issue:`SERVER-57651` Prevent integer overflow in Query Planner parsing of hint parameter +- :issue:`SERVER-57657` disable_cluster_time_gossiping_in_unreadable_state.js shouldn't modify a response's $clusterTime +- :issue:`SERVER-57700` Measure latency/throughput of resharding::data_copy::fillBatchForInsert in ReshardingCollectionCloner::doOneBatch +- :issue:`SERVER-57737` The index builds code path can throw WCEs and invalidate an active cursor by calling abandonSnapshot without calling save/restore cursor. +- :issue:`SERVER-57740` ShardingTest use X509 also with preferTLS mode +- :issue:`SERVER-58051` Mongod.exe does not release file handles on rotated logs on windows 10 +- :issue:`SERVER-58060` Add new aggregation stage to downconvert RRFaM images to oplog entries +- :issue:`SERVER-58068` Multi updates interrupted by a tenant migration should wait for the migration to complete +- :issue:`SERVER-58119` single_node_set_new_hostname.js needs to call replSetReconfig with an assert.soonNoExcept +- :issue:`SERVER-58152` Create Feature flag for Remove Faulty Mongos From Cluster Topology +- :issue:`SERVER-58160` Increase egress timeout in cluster_x509_roate.js +- :issue:`SERVER-58184` Checkpoint thread causes assertions when raced with recovering prepared transactions on startup +- :issue:`SERVER-58264` Only run cron jobs in Evergreen on the master branch +- :issue:`SERVER-58293` mongocryptd does not include server API fields in explain command response +- :issue:`SERVER-58353` Fix disabled Replication tests failing in multiversion suites due to changing latest release to 5.1 +- :issue:`SERVER-58392` Unpin durable history on rollback to refetch +- :issue:`SERVER-58399` Duplicate errInfo field in write errors when operation fails document validation +- :issue:`SERVER-58402` Increase timeout of shutdown command in shutdown_primary.js +- :issue:`SERVER-58420` Gracefully handle the demotion of data-types in umask +- :issue:`SERVER-58432` Include dochub link in log line 5578800 when warning about deprecation/removal of old op codes +- :issue:`SERVER-58438` Tenant migration retryable write prefetching pipeline could be very slow under load +- :issue:`SERVER-58464` Invariant failure during time-series insert with concurrent shutdown +- :issue:`SERVER-58565` Adjust timeout for replica_sets_jscore_passthrough +- :issue:`SERVER-58581` Add SEARCH_META variable that populates from mongot +- :issue:`SERVER-58582` Create $documents stage and implement collectionless unionWith +- :issue:`SERVER-58588` Implement $searchMeta stage +- :issue:`SERVER-58594` ReplicationCoordinatorImpl::handleHeartbeatResponse_forTest doesn't use _mutex when reading _rsConfig +- :issue:`SERVER-58620` New recipient primary can complete migration before donor renames collection in tenant_migration_resume_collection_cloner_after_rename.js +- :issue:`SERVER-58626` Mark capped_max1 as tenant_migration_incompatible. +- :issue:`SERVER-58637` Temporarily disable null_query_semantics.js from multiversion passthroughs +- :issue:`SERVER-58669` createIndexes, dropIndexes, and collMod may still fail with ReshardCollectionInProgress after resharding operation completes +- :issue:`SERVER-58676` Ban pipelines that set SEARCH_META variable in sharded collections +- :issue:`SERVER-58682` check_todos.py should be no-oping in the waterfall +- :issue:`SERVER-58698` [Linux Repeated Execution builder] disable concurrency_replication_multi_stmt_txn +- :issue:`SERVER-58740` Reserve multiple oplog slots when writing retryable findAndModify with storeFindAndModifyImagesInSideCollection=true +- :issue:`SERVER-58806` Use replica_sets_jscore_passthrough_gen task on Enterprise MacOS +- :issue:`SERVER-58812` tenant_migration_timeseries_retryable_write_oplog_cloning.js should get donorDoc before being garbage collected +- :issue:`SERVER-58815` Have internal findAndModifyImageLookup set the synthetic oplog entry to timestamp of findAndModify - 1 +- :issue:`SERVER-58823` The refineShardKey command should mark its operation context as interruptible at step down/step up +- :issue:`SERVER-58855` Improve/Fix the Race Condition in out_max_time_ms.js +- :issue:`SERVER-58857` Change stream accidentally filters out rename event from reshardCollection [5.0 Only] +- :issue:`SERVER-58886` Allow 'vars' result to be returned from a sharded search query but fail on SEARCH_META access +- :issue:`SERVER-58898` Prevent writing to "local" db from waiting for writeConcern +- :issue:`SERVER-58904` Escaped or single-quoted DESTDIR causes malformed .ninja and resmoke.ini +- :issue:`SERVER-58919` sharding_jscore_passthrough_wire_ops_gen needs to be marked as a generated task. +- :issue:`SERVER-58948` idl_tool: support generated idls +- :issue:`SERVER-58973` Fix failure deprecated_wire_ops_mongos.js with v5.0 windows debug build +- :issue:`SERVER-58984` awaitable_hello_fcv_change.js doesn't account for window between awaitable hello requests due to reconfig +- :issue:`SERVER-59000` Enforce dependencies for generated tasks +- :issue:`SERVER-59025` Increase storage log verbosity in oplog_slow_sampling_logging.js +- :issue:`SERVER-59040` add operations_longer_than_stepdown_interval tag to background_unique_indexes.js +- :issue:`SERVER-59044` Handle empty time series collection for $sample in the TrialStage +- :issue:`SERVER-59056` [5.0] Fix primary check in timeseries_retryable_write_downgrade.js +- :issue:`SERVER-59071` Using $sample can trigger invariant when connecting directly to shards +- :issue:`SERVER-59091` Avoid fetching namespace from durable catalog for every key inserted in index build +- :issue:`SERVER-59093` Temporarily disable the failing jstest suite for ephemeralForTest on evergreen +- :issue:`SERVER-59101` remove unnecessary LIBDEPS edge from pipeline library +- :issue:`SERVER-59117` xcode next builders hit dyld 512 library limit +- :issue:`SERVER-59121` ssh connection failure during check_disk command in powercycle should cause ssh failure exit +- :issue:`SERVER-59135` Make mongocryptd targets in MSIs depend on libsasl2 +- :issue:`SERVER-59158` Support running checkFCV() shell helper with mongos connection +- :issue:`SERVER-59188` Coverity analysis defect 120391: Uninitialized scalar field +- :issue:`SERVER-59197` Delete fam image entries when the corresponding session documents are deleted +- :issue:`SERVER-59203` Don't rely on mocks to test generating tasks for build variants +- :issue:`SERVER-59204` unowned filter BSONObj stored in PlanCache entry debugInfo +- :issue:`SERVER-59217` convert spaces to tabs for package files +- :issue:`SERVER-59236` Add function to legacy shell to recursively copy directories +- :issue:`SERVER-59242` update to snmp 5.9.1 +- :issue:`SERVER-59291` Consider adding 'enableSearchMeta' query knob +- :issue:`SERVER-59324` Remove feature flag performance variant from sys-perf on 5.0. +- :issue:`SERVER-59353` Have shell strip featureFlagRetryableFindAndModify when launching mongod version <= 4.4 +- :issue:`SERVER-59362` Setup Fault Manager State Machine +- :issue:`SERVER-59404` Avoid powercycle_smoke_skip_compile reaching task timeout +- :issue:`SERVER-59431` [v5.0] disable parallel task in EFT builder +- :issue:`SERVER-59516` Create opCtx outside of lock in oplog fetcher +- :issue:`SERVER-59573` Add setParameter which can be used to restore inactive cursor timeout in sessions +- :issue:`SERVER-59640` [5.0] Add coverage for geoSearch command in views_all_commands.js test +- :issue:`WT-6755` Documentation: populate developer glossary +- :issue:`WT-6910` Write "history store" subpage for Architecture Guide +- :issue:`WT-6911` Write "block manager" subpage for Architecture Guide +- :issue:`WT-6915` Write "log files" subpage for Architecture Guide +- :issue:`WT-7006` Write Connection subpage for Architecture Guide +- :issue:`WT-7007` Backup architecture guide page +- :issue:`WT-7198` Fix test_backup15 failure with backup mismatch +- :issue:`WT-7352` Fix test_hs01 conflict between concurrent operations in cursor modify +- :issue:`WT-7363` Add support for dumping history store output in hex format +- :issue:`WT-7521` Remove excess ckplist invalidations +- :issue:`WT-7592` Remove log_flush("sync=background") support +- :issue:`WT-7599` Update the CONFIG file based on the release that is about to run for compatibility tests +- :issue:`WT-7663` Change local store extension to allow only readonly FS operations +- :issue:`WT-7673` Investigate and fix manydbs test failure on Windows +- :issue:`WT-7718` Rename 'build_cmake' +- :issue:`WT-7838` Ability for ordered timestamp assertion to do more than a log message +- :issue:`WT-7842` Remove explicit ulimit -n call in many-collection-test +- :issue:`WT-7860` Improve code coverage reporting +- :issue:`WT-7866` Update cache_hs_insert limits in cppsuite-hs-cleanup-stress +- :issue:`WT-7876` Update rollback to stable test to use correct boolean values and update statistic checking logic +- :issue:`WT-7880` Fix history store record issue when the update following the prepared update is in history store +- :issue:`WT-7891` Remove doc typos +- :issue:`WT-7893` Remove ignored message from wiredtiger_open in test_encrypt08 +- :issue:`WT-7895` Fix arch-data-file.dox documentation build failure +- :issue:`WT-7897` Enable verbose logging for test_backup15 to aid debugging +- :issue:`WT-7900` Fix insertion of new records in test format for column-store +- :issue:`WT-7901` test suite cleanup +- :issue:`WT-7905` Fix incorrect builtin behaviour for builds in CMake +- :issue:`WT-7907` Add dependencies to swig module definition in CMake build +- :issue:`WT-7908` Make variable-length column store work again with the static tests +- :issue:`WT-7909` Create a new method to check for running user transactions before starting rollback-to-stable operation +- :issue:`WT-7918` Support setting a prepare timestamp at current read timestamp +- :issue:`WT-7928` VLCS checkpoint and additional test suite improvements +- :issue:`WT-7931` Evicting modifies using the evict cursor in test_multiple_older_readers_with_multiple_mixed_mode() to ensure that eviction happens. +- :issue:`WT-7934` Upload perf results from many-collection test to Altas +- :issue:`WT-7935` Add arm64 implementation of rdtsc equivalent instruction +- :issue:`WT-7936` Update the format.sh script to run recovery tests +- :issue:`WT-7937` Fix s_docs to use sh, not bash syntax +- :issue:`WT-7938` Fix rollback-to-stable memory leak on error +- :issue:`WT-7940` Update mongod path for many-coll test +- :issue:`WT-7941` Add an Evergreen task to test abort/recovery using test/format +- :issue:`WT-7943` Do not assert timestamps when rolling back a prepared transactions +- :issue:`WT-7945` Move rollback handling to the operation layer in the cppsuite. +- :issue:`WT-7947` Allow CMake to take in a specific Python version +- :issue:`WT-7952` Minor docs build fixes +- :issue:`WT-7953` Teach s_string to not look inside getopt option lists. +- :issue:`WT-7955` Copy format.sh and CONFIG.stress to the test/format build directory with CMake +- :issue:`WT-7956` RTS to skip deleted or stable RLE cells +- :issue:`WT-7961` Sometimes lag oldest timestamp in timestamp_abort. +- :issue:`WT-7964` Fix rollback to stable incorrectly not rolling back updates at snap_max +- :issue:`WT-7965` Update connection base write generation number at the end of recovery checkpoint +- :issue:`WT-7968` In timestamp_abort skip setting timestamps when all_durable moves backwards +- :issue:`WT-7970` Set the stable timestamp before starting the checkpointer and clock threads +- :issue:`WT-7974` More column-store fixes and tests +- :issue:`WT-7984` Fix a bug that could cause a checkpoint to omit a page of data +- :issue:`WT-7994` Add docs compile task to PR testing +- :issue:`WT-7995` Fix the global visibility that it cannot go beyond checkpoint visibility +- :issue:`WT-7996` More column-store C testing +- :issue:`WT-7998` Minor fixes on Cache subpage of Architecture Guide +- :issue:`WT-7999` Fix the assert to handle an update in the middle with max stop timestamp +- :issue:`WT-8005` Fix a prepare commit bug that could leave the history store entry unresolved +- :issue:`WT-8006` sync/checkpoint cleanup code isn't appropriate for VLCS + diff --git a/source/release-notes/5.0-changelog.txt b/source/release-notes/5.0-changelog.txt index ec76b0dc15f..9b5a0741e44 100644 --- a/source/release-notes/5.0-changelog.txt +++ b/source/release-notes/5.0-changelog.txt @@ -10,6 +10,8 @@ :depth: 1 :class: singlecol +.. include:: /includes/changelogs/releases/5.0.3.rst + .. include:: /includes/changelogs/releases/5.0.2.rst .. include:: /includes/changelogs/releases/5.0.1.rst diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index b09a7aea1e2..0355a92cde1 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -17,6 +17,29 @@ Release Notes for MongoDB 5.0 Minor Releases -------------- +.. _5.0.3-release-notes: + +5.0.3 - Upcoming +~~~~~~~~~~~~~~~~ + +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 + `_ + +- :ref:`5.0.3-changelog` + .. _5.0.2-release-notes: 5.0.2 - Aug 4, 2021 From 65c32590d5e48c099e0d203c82b6208db7ba7c3f Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Tue, 31 Aug 2021 11:45:49 -0400 Subject: [PATCH 016/109] (DOCS-14770): Prepare changelog for 4.4.9 --- source/includes/changelogs/releases/4.4.9.rst | 149 ++++++++++++++++++ source/release-notes/4.4-changelog.txt | 2 + source/release-notes/4.4.txt | 23 +++ 3 files changed, 174 insertions(+) create mode 100644 source/includes/changelogs/releases/4.4.9.rst diff --git a/source/includes/changelogs/releases/4.4.9.rst b/source/includes/changelogs/releases/4.4.9.rst new file mode 100644 index 00000000000..c9cda32b12e --- /dev/null +++ b/source/includes/changelogs/releases/4.4.9.rst @@ -0,0 +1,149 @@ +.. _4.4.9-changelog: + +4.4.9 Changelog +--------------- + +Security +~~~~~~~~ + +:issue:`SERVER-57716` Partial certificate chain in PEM causes validation failure in OCSP + +Replication +~~~~~~~~~~~ + +- :issue:`SERVER-34938` Secondary slowdown or hang due to content pinned in cache by single oplog batch +- :issue:`SERVER-36263` Bypassing operation validation in applyOps should require special privilege +- :issue:`SERVER-44316` Log message in InitialSyncer for setting begin applying timestamp is incorrect +- :issue:`SERVER-59212` Make sure node stepped down before waiting for catchup takeover in catchup_takeover_with_higher_config.js +- :issue:`SERVER-59478` Move serverStatus command before taking RSTL in catchup_takeover_with_higher_config.js + +Query +~~~~~ + +:issue:`SERVER-57178` add regression test for multikey compound index + +Storage +~~~~~~~ + +:issue:`SERVER-56877` insert operations may fail to set index to multikey after aborted multikey catalog update + +Build and Packaging +~~~~~~~~~~~~~~~~~~~ + +:issue:`WT-7830` Migrate the python setup scripts to use cmake + +Internals +~~~~~~~~~ + +- :issue:`SERVER-49435` uassert in NetworkInterfaceTL::setTimer can cause server to crash if connection future not immediately ready +- :issue:`SERVER-53069` Disable death tests on address and memory sanitizer variants +- :issue:`SERVER-53479` Wait for mirrored operations in mirror_reads.js +- :issue:`SERVER-53849` Move away from getLog in timestamped_reads_wait_for_prepare_oplog_visibility.js +- :issue:`SERVER-55589` replSetMaintenance command does not take the RSTL +- :issue:`SERVER-56580` Promote build-tools=next to stable +- :issue:`SERVER-57262` Allow nodes to vote for candidates with higher config +- :issue:`SERVER-57268` add multikey query to validate_multikey_restart.js +- :issue:`SERVER-57360` Log additional debug info for the "invariant (_requests.empty());" in ~LockerImpl +- :issue:`SERVER-57630` Enable SSL_OP_NO_RENEGOTIATION on Ubuntu 18.04 when running against OpenSSL 1.1.1 +- :issue:`SERVER-57752` Test terminating mongod during a clean shutdown checkpoint +- :issue:`SERVER-57893` Make rsm_horizon_change.js resilient to network failures +- :issue:`SERVER-58051` Mongod.exe does not release file handles on rotated logs on windows 10 +- :issue:`SERVER-58169` Log timestamps info on hitting invariants around stable timestamp calculation +- :issue:`SERVER-58184` Checkpoint thread causes assertions when raced with recovering prepared transactions on startup +- :issue:`SERVER-58280` initial sync hangs on hiding dropped index when index builds are active +- :issue:`SERVER-58402` Increase timeout of shutdown command in shutdown_primary.js +- :issue:`SERVER-58581` Add SEARCH_META variable that populates from mongot +- :issue:`SERVER-58582` Create $documents stage and implement collectionless unionWith +- :issue:`SERVER-58588` Implement $searchMeta stage +- :issue:`SERVER-58594` ReplicationCoordinatorImpl::handleHeartbeatResponse_forTest doesn't use _mutex when reading _rsConfig +- :issue:`SERVER-58676` Ban pipelines that set SEARCH_META variable in sharded collections +- :issue:`SERVER-58813` Robustify jstests/multiversion/hashed_index_bad_keys_cleanup.js +- :issue:`SERVER-58886` Allow 'vars' result to be returned from a sharded search query but fail on SEARCH_META access +- :issue:`SERVER-59135` Make mongocryptd targets in MSIs depend on libsasl2 +- :issue:`SERVER-59188` Coverity analysis defect 120391: Uninitialized scalar field +- :issue:`SERVER-59197` Delete fam image entries when the corresponding session documents are deleted +- :issue:`SERVER-59242` update to snmp 5.9.1 +- :issue:`SERVER-59262` Remove burn_in_tests tasks from storeFindAndModifyImagesInSideCollection build variants +- :issue:`SERVER-59414` Retry curator setup in powercycle on older branches +- :issue:`SERVER-59469` Add missing space in burn_in_tags list of variants +- :issue:`SERVER-59573` Add setParameter which can be used to restore inactive cursor timeout in sessions +- :issue:`WT-6755` Documentation: populate developer glossary +- :issue:`WT-6902` Metadata subpage for Architecture Guide +- :issue:`WT-6910` Write "history store" subpage for Architecture Guide +- :issue:`WT-6911` Write "block manager" subpage for Architecture Guide +- :issue:`WT-6914` Write "database files" subpage for Architecture Guide +- :issue:`WT-6915` Write "log files" subpage for Architecture Guide +- :issue:`WT-7006` Write Connection subpage for Architecture Guide +- :issue:`WT-7007` Backup architecture guide page +- :issue:`WT-7198` Fix test_backup15 failure with backup mismatch +- :issue:`WT-7352` Fix test_hs01 conflict between concurrent operations in cursor modify +- :issue:`WT-7363` Add support for dumping history store output in hex format +- :issue:`WT-7521` Remove excess ckplist invalidations +- :issue:`WT-7592` Remove log_flush("sync=background") support +- :issue:`WT-7599` Update the CONFIG file based on the release that is about to run for compatibility tests +- :issue:`WT-7663` Change local store extension to allow only readonly FS operations +- :issue:`WT-7673` Investigate and fix manydbs test failure on Windows +- :issue:`WT-7703` Fix timeout in test_checkpoint_snapshot04 +- :issue:`WT-7718` Rename 'build_cmake' +- :issue:`WT-7732` Add a timeout configuration for flush_tier +- :issue:`WT-7758` Force evict a page when the update chain is too long +- :issue:`WT-7787` Don't read pages for checkpoint cleanup when the cache is in aggressive mode +- :issue:`WT-7789` Change tiered python tests to fail without extension library +- :issue:`WT-7817` Make tiered storage address cookies backward compatible +- :issue:`WT-7838` Ability for ordered timestamp assertion to do more than a log message +- :issue:`WT-7842` Remove explicit ulimit -n call in many-collection-test +- :issue:`WT-7860` Improve code coverage reporting +- :issue:`WT-7864` Add support to run.py for running lists/ranges of scenarios in a test +- :issue:`WT-7865` Disable timeout assert while waiting for eviction to quiesce prior to RTS and test +- :issue:`WT-7866` Update cache_hs_insert limits in cppsuite-hs-cleanup-stress +- :issue:`WT-7870` Fix measurement of cyclomatic code complexity +- :issue:`WT-7871` Remove comment that is no longer true +- :issue:`WT-7874` Remove two other stale comments +- :issue:`WT-7876` Update rollback to stable test to use correct boolean values and update statistic checking logic +- :issue:`WT-7880` Fix history store record issue when the update following the prepared update is in history store +- :issue:`WT-7882` Fix discrepancy for wiredtiger.in on mongodb-4.4 branch +- :issue:`WT-7883` Remove incorrect wt_free statement +- :issue:`WT-7889` Find/replace existing uses of WT with WiredTiger in reference guide +- :issue:`WT-7890` Fix CMake syntax error in config_lib +- :issue:`WT-7891` Remove doc typos +- :issue:`WT-7893` Remove ignored message from wiredtiger_open in test_encrypt08 +- :issue:`WT-7895` Fix arch-data-file.dox documentation build failure +- :issue:`WT-7897` Enable verbose logging for test_backup15 to aid debugging +- :issue:`WT-7900` Fix insertion of new records in test format for column-store +- :issue:`WT-7901` test suite cleanup +- :issue:`WT-7905` Fix incorrect builtin behaviour for builds in CMake +- :issue:`WT-7907` Add dependencies to swig module definition in CMake build +- :issue:`WT-7908` Make variable-length column store work again with the static tests +- :issue:`WT-7909` Create a new method to check for running user transactions before starting rollback-to-stable operation +- :issue:`WT-7918` Support setting a prepare timestamp at current read timestamp +- :issue:`WT-7928` VLCS checkpoint and additional test suite improvements +- :issue:`WT-7931` Evicting modifies using the evict cursor in test_multiple_older_readers_with_multiple_mixed_mode() to ensure that eviction happens. +- :issue:`WT-7934` Upload perf results from many-collection test to Altas +- :issue:`WT-7935` Add arm64 implementation of rdtsc equivalent instruction +- :issue:`WT-7936` Update the format.sh script to run recovery tests +- :issue:`WT-7937` Fix s_docs to use sh, not bash syntax +- :issue:`WT-7938` Fix rollback-to-stable memory leak on error +- :issue:`WT-7940` Update mongod path for many-coll test +- :issue:`WT-7941` Add an Evergreen task to test abort/recovery using test/format +- :issue:`WT-7943` Do not assert timestamps when rolling back a prepared transactions +- :issue:`WT-7945` Move rollback handling to the operation layer in the cppsuite. +- :issue:`WT-7947` Allow CMake to take in a specific Python version +- :issue:`WT-7952` Minor docs build fixes +- :issue:`WT-7953` Teach s_string to not look inside getopt option lists. +- :issue:`WT-7955` Copy format.sh and CONFIG.stress to the test/format build directory with CMake +- :issue:`WT-7956` RTS to skip deleted or stable RLE cells +- :issue:`WT-7961` Sometimes lag oldest timestamp in timestamp_abort. +- :issue:`WT-7964` Fix rollback to stable incorrectly not rolling back updates at snap_max +- :issue:`WT-7965` Update connection base write generation number at the end of recovery checkpoint +- :issue:`WT-7968` In timestamp_abort skip setting timestamps when all_durable moves backwards +- :issue:`WT-7970` Set the stable timestamp before starting the checkpointer and clock threads +- :issue:`WT-7974` More column-store fixes and tests +- :issue:`WT-7984` Fix a bug that could cause a checkpoint to omit a page of data +- :issue:`WT-7994` Add docs compile task to PR testing +- :issue:`WT-7995` Fix the global visibility that it cannot go beyond checkpoint visibility +- :issue:`WT-7996` More column-store C testing +- :issue:`WT-7998` Minor fixes on Cache subpage of Architecture Guide +- :issue:`WT-7999` Fix the assert to handle an update in the middle with max stop timestamp +- :issue:`WT-8005` Fix a prepare commit bug that could leave the history store entry unresolved +- :issue:`WT-8006` sync/checkpoint cleanup code isn't appropriate for VLCS + diff --git a/source/release-notes/4.4-changelog.txt b/source/release-notes/4.4-changelog.txt index 928e9003902..4e09bd2aeb8 100644 --- a/source/release-notes/4.4-changelog.txt +++ b/source/release-notes/4.4-changelog.txt @@ -10,6 +10,8 @@ :depth: 1 :class: singlecol +.. include:: /includes/changelogs/releases/4.4.9.rst + .. include:: /includes/changelogs/releases/4.4.8.rst .. include:: /includes/changelogs/releases/4.4.7.rst diff --git a/source/release-notes/4.4.txt b/source/release-notes/4.4.txt index 0a166513f92..0081e3b3a54 100644 --- a/source/release-notes/4.4.txt +++ b/source/release-notes/4.4.txt @@ -13,6 +13,29 @@ Release Notes for MongoDB 4.4 Minor Releases -------------- +.. _4.4.9-release-notes: + +4.4.9 - Upcoming +~~~~~~~~~~~~~~~~ + +Issues fixed: + +- :issue:`SERVER-57630`: Enable SSL_OP_NO_RENEGOTIATION on Ubuntu 18.04 + when running against OpenSSL 1.1.1 +- :issue:`SERVER-34938`: Secondary slowdown or hang due to content + pinned in cache by single oplog batch +- :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 4.4.9 + `_ + +- :ref:`4.4.9-changelog` + .. _4.4.8-release-notes: 4.4.8 - Aug 4, 2021 From a06be75f86b97df4824db50ab6702e57dceb106c Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Mon, 23 Aug 2021 13:54:04 -0400 Subject: [PATCH 017/109] DOCS-14394 Add 64-bit integer limit notes to and pages --- source/reference/operator/aggregation/limit.txt | 8 +++++++- source/reference/operator/aggregation/skip.txt | 8 +++++++- source/release-notes/5.0-compatibility.txt | 12 ++++++++++++ 3 files changed, 26 insertions(+), 2 deletions(-) diff --git a/source/reference/operator/aggregation/limit.txt b/source/reference/operator/aggregation/limit.txt index f252f03f134..bc08a88c2a8 100644 --- a/source/reference/operator/aggregation/limit.txt +++ b/source/reference/operator/aggregation/limit.txt @@ -22,11 +22,17 @@ Definition .. code-block:: javascript - { $limit: } + { $limit: } :pipeline:`$limit` takes a positive integer that specifies the maximum number of documents to pass along. + .. note:: + + Starting in MongoDB 5.0, the :pipeline:`$limit` pipeline aggregation + has a 64-bit integer limit. Values passed to the pipeline which + exceed this limit will return a invalid argument error. + Behavior -------- diff --git a/source/reference/operator/aggregation/skip.txt b/source/reference/operator/aggregation/skip.txt index 63e937ec683..aa6851d8b3a 100644 --- a/source/reference/operator/aggregation/skip.txt +++ b/source/reference/operator/aggregation/skip.txt @@ -23,11 +23,17 @@ Definition .. code-block:: javascript - { $skip: } + { $skip: } :pipeline:`$skip` takes a positive integer that specifies the maximum number of documents to skip. + .. note:: + + Starting in MongoDB 5.0, the :pipeline:`$skip` pipeline aggregation + has a 64-bit integer limit. Values passed to the pipeline which + exceed this limit will return a invalid argument error. + Behavior -------- diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt index 79947e5e49c..def454a00be 100644 --- a/source/release-notes/5.0-compatibility.txt +++ b/source/release-notes/5.0-compatibility.txt @@ -227,6 +227,18 @@ operand expression ( ``{ }`` ): An empty update results in no changes and no :term:`oplog` entry is created (meaning that the operation is a no-op). +Aggregation Pipeline Operator Parameter Limits +---------------------------------------------- + +The following aggregation pipeline operators now have a 64-bit +integer value maximum limit. + +- :pipeline:`$sort` +- :pipeline:`$limit` + +If you pass a value that exceeds this limit, the pipeline returns an +invalid argument error. + ``listDatabases`` Output Changes -------------------------------- From b80d1709fc41b297ea4c903337c5b9142b5b040c Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Tue, 31 Aug 2021 14:43:12 -0400 Subject: [PATCH 018/109] DOCSP-18150 removed blurb on page for 5.0.3 release. --- .../includes/fact-set-global-write-concern-before-reconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/fact-set-global-write-concern-before-reconfig.rst b/source/includes/fact-set-global-write-concern-before-reconfig.rst index 4e09a2139b0..e56e787e6ab 100644 --- a/source/includes/fact-set-global-write-concern-before-reconfig.rst +++ b/source/includes/fact-set-global-write-concern-before-reconfig.rst @@ -1,6 +1,6 @@ Starting in MongoDB 5.0, you must explicitly set the global default :ref:`write concern ` before attempting to reconfigure a -:ref:`non-sharded ` :term:`replica set ` with a +:term:`replica set ` with a :doc:`configuration ` that would change the implicit default write concern. To set the global default write concern, use the :dbcommand:`setDefaultRWConcern` command. From 3d40bbaa88d5bb04073acf1617f846cabcbf98e4 Mon Sep 17 00:00:00 2001 From: jeff-allen-mongo Date: Tue, 31 Aug 2021 17:22:42 -0400 Subject: [PATCH 019/109] (DOCSP-18425): Add Go to Driver Support for DBRefs table (#5767) * (DOCSP-18425): Add Go to Driver Support for DBRefs table * fix alphabetization --- source/reference/database-references.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/reference/database-references.txt b/source/reference/database-references.txt index c738fef7f87..6057eed6b4c 100644 --- a/source/reference/database-references.txt +++ b/source/reference/database-references.txt @@ -221,6 +221,12 @@ Driver Support for DBRefs - Please see the :driver:`C# driver page ` for more information. + * - Go + + - Not Supported + + - You can traverse references manually. + * - Haskell - Not Supported From b74862d7b72241310ea3b5800d782b68ce73abdb Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Wed, 1 Sep 2021 10:51:46 -0400 Subject: [PATCH 020/109] Fix 'date' ref link target on ttl page --- source/core/index-ttl.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/core/index-ttl.txt b/source/core/index-ttl.txt index b636a818af6..c21b185f467 100644 --- a/source/core/index-ttl.txt +++ b/source/core/index-ttl.txt @@ -57,8 +57,9 @@ If the field is an array, and there are multiple date values in the index, MongoDB uses *lowest* (i.e. earliest) date value in the array to calculate the expiration threshold. -If the indexed field in a document is not a :term:`date ` -or an array that holds a date value(s), the document will not expire. +If the indexed field in a document is not a +:ref:`date ` or an array that holds one or +more date values, the document will not expire. If a document does not contain the indexed field, the document will not expire. From 4b16e2c3a5f841b264a68edf0b3ba148fd12cc50 Mon Sep 17 00:00:00 2001 From: jason-price-mongodb Date: Mon, 16 Aug 2021 10:16:57 -0700 Subject: [PATCH 021/109] DOCS-13309 short circuit evaluation --- source/includes/and-or-behavior.rst | 23 ++++++++++ source/reference/operator/aggregation/and.txt | 30 +++++++++---- source/reference/operator/aggregation/or.txt | 20 +++++++-- source/reference/operator/query/and.txt | 45 ++++++++++++------- source/reference/operator/query/or.txt | 17 +++++++ 5 files changed, 107 insertions(+), 28 deletions(-) create mode 100644 source/includes/and-or-behavior.rst diff --git a/source/includes/and-or-behavior.rst b/source/includes/and-or-behavior.rst new file mode 100644 index 00000000000..e4bcb5bd226 --- /dev/null +++ b/source/includes/and-or-behavior.rst @@ -0,0 +1,23 @@ +To allow the query engine to optimize queries, |and-or| handles +errors as follows: + +- If any expression supplied to |and-or| would cause an error when + evaluated alone, the |and-or| containing the expression may cause an + error but an error is not guaranteed. + +- An expression supplied after the first expression supplied to |and-or| + may cause an error even if the first expression evaluates to + |true-false|. + +For example, the following query *always* produces an error if ``$x`` is +``0``: + +.. code-block:: javascript + + db.example.find( { + $expr: { $eq: [ { $divide: [ 1, "$x" ] }, 3 ] } + } ) + +The following query, which contains multiple expressions supplied to +|and-or|, *may* produce an error if there is any document where ``$x`` +is ``0``: diff --git a/source/reference/operator/aggregation/and.txt b/source/reference/operator/aggregation/and.txt index dce19d7d921..ae6f24d64dd 100644 --- a/source/reference/operator/aggregation/and.txt +++ b/source/reference/operator/aggregation/and.txt @@ -16,10 +16,10 @@ Definition .. expression:: $and Evaluates one or more expressions and returns ``true`` if *all* of - the expressions are ``true`` or if evoked with no argument + the expressions are ``true`` or if run with no argument expressions. Otherwise, :expression:`$and` returns ``false``. - :expression:`$and` has the following syntax: + :expression:`$and` syntax: .. code-block:: javascript @@ -33,9 +33,6 @@ Definition Behavior -------- -:expression:`$and` uses short-circuit logic: the operation stops -evaluation after encountering the first ``false`` expression. - .. include:: /includes/extracts/fact-agg-boolean-and.rst .. list-table:: @@ -66,10 +63,27 @@ evaluation after encountering the first ``false`` expression. - ``false`` +Error Handling +-------------- + +.. |and-or| replace:: ``$and`` +.. |true-false| replace:: ``false`` + +.. include:: /includes/and-or-behavior.rst + +.. code-block:: javascript + + db.example.find( { + $and: [ + { x: { $ne: 0 } }, + { $expr: { $eq: [ { $divide: [ 1, "$x" ] }, 3 ] } } + ] + } ) + Example ------- -Create an example ``inventory`` collection with the following documents: +Create an example ``inventory`` collection with these documents: .. code-block:: javascript @@ -81,7 +95,7 @@ Create an example ``inventory`` collection with the following documents: { "_id" : 5, "item" : "VWZ2", description: "product 5", qty: 180 } ]) -The following operation uses the :expression:`$and` operator to +This operation uses the :expression:`$and` operator to determine if ``qty`` is greater than 100 *and* less than ``250``: .. code-block:: javascript @@ -99,7 +113,7 @@ determine if ``qty`` is greater than 100 *and* less than ``250``: ] ) -The operation returns the following results: +The operation returns these results: .. code-block:: javascript diff --git a/source/reference/operator/aggregation/or.txt b/source/reference/operator/aggregation/or.txt index eb9a2e4ada8..4ef0c54e515 100644 --- a/source/reference/operator/aggregation/or.txt +++ b/source/reference/operator/aggregation/or.txt @@ -31,9 +31,6 @@ Definition Behavior -------- -:expression:`$or` uses short-circuit logic: the operation stops -evaluation after encountering the first ``true`` expression. - .. include:: /includes/extracts/fact-agg-boolean-or.rst .. list-table:: @@ -60,6 +57,23 @@ evaluation after encountering the first ``true`` expression. - ``false`` +Error Handling +-------------- + +.. |and-or| replace:: ``$or`` +.. |true-false| replace:: ``true`` + +.. include:: /includes/and-or-behavior.rst + +.. code-block:: javascript + + db.example.find( { + $or: [ + { x: { $eq: 0 } }, + { $expr: { $eq: [ { $divide: [ 1, "$x" ] }, 3 ] } } + ] + } ) + Example ------- diff --git a/source/reference/operator/query/and.txt b/source/reference/operator/query/and.txt index fd5e99dae4b..4c5ccdb1d3b 100644 --- a/source/reference/operator/query/and.txt +++ b/source/reference/operator/query/and.txt @@ -14,40 +14,51 @@ $and *Syntax*: ``{ $and: [ { }, { } , ... , { } ] }`` - :query:`$and` performs a logical ``AND`` operation on an array - of *one or more* expressions (e.g. ````, - ````, etc.) and selects the documents that satisfy - *all* the expressions in the array. The :query:`$and` operator - uses *short-circuit evaluation*. If the first expression - (e.g. ````) evaluates to ``false``, MongoDB will not - evaluate the remaining expressions. + :query:`$and` performs a logical ``AND`` operation on an array of + *one or more* expressions (````, ````, and + so on) and selects the documents that satisfy *all* the expressions. .. note:: MongoDB provides an implicit ``AND`` operation when specifying a comma separated list of expressions. +Behavior +-------- + +.. |and-or| replace:: ``$and`` +.. |true-false| replace:: ``false`` + +.. include:: /includes/and-or-behavior.rst + +.. code-block:: javascript + + db.example.find( { + $and: [ + { x: { $ne: 0 } }, + { $expr: { $eq: [ { $divide: [ 1, "$x" ] }, 3 ] } } + ] + } ) + Examples -------- ``AND`` Queries With Multiple Expressions Specifying the Same Field ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Consider the following example: +Consider this query: .. code-block:: javascript db.inventory.find( { $and: [ { price: { $ne: 1.99 } }, { price: { $exists: true } } ] } ) -This query will select all documents in the ``inventory`` -collection where: +The query selects all documents in the ``inventory`` collection where: - the ``price`` field value is not equal to ``1.99`` **and** - the ``price`` field exists. -This query can be also be constructed with an implicit ``AND`` -operation by combining the operator expressions for the ``price`` -field. For example, this query can be written as: +The query can be rewritten with an implicit ``AND`` operation that +combines the operator expressions for the ``price`` field: .. code-block:: javascript @@ -56,7 +67,7 @@ field. For example, this query can be written as: ``AND`` Queries With Multiple Expressions Specifying the Same Operator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Consider the following example: +Consider this query: .. code-block:: javascript @@ -67,14 +78,14 @@ Consider the following example: ] } ) -This query will select all documents where: +The query selects all documents where: - the ``qty`` field value is less than ``10`` or greater than ``50``, **and** - the ``sale`` field value is equal to ``true`` **or** the ``price`` field value is less than ``5``. -This query cannot be constructed using an implicit ``AND`` operation, -because it uses the :query:`$or` operator more than once. +The query cannot use an implicit ``AND`` operation because it uses the +:query:`$or` operator more than once. .. seealso:: diff --git a/source/reference/operator/query/or.txt b/source/reference/operator/query/or.txt index 1e170d899eb..2fceaa6cc88 100644 --- a/source/reference/operator/query/or.txt +++ b/source/reference/operator/query/or.txt @@ -118,3 +118,20 @@ You may nest :query:`$or` operations. - :method:`~db.collection.find()` - :method:`~cursor.sort()` - :query:`$in` + +Error Handling +~~~~~~~~~~~~~~ + +.. |and-or| replace:: ``$or`` +.. |true-false| replace:: ``true`` + +.. include:: /includes/and-or-behavior.rst + +.. code-block:: javascript + + db.example.find( { + $or: [ + { x: { $eq: 0 } }, + { $expr: { $eq: [ { $divide: [ 1, "$x" ] }, 3 ] } } + ] + } ) From d7adbb9f00662cf08d659f464a86ca6327dd4e6f Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Mon, 30 Aug 2021 12:34:44 -0400 Subject: [PATCH 022/109] DOCS-14433 config.transactions read concern disallowed --- .../fact-5.0-non-transactional-config-reads.rst | 10 ++++++++++ source/reference/config-database.txt | 2 ++ source/release-notes/5.0-compatibility.txt | 5 +++++ source/release-notes/5.0.txt | 5 +++++ 4 files changed, 22 insertions(+) create mode 100644 source/includes/fact-5.0-non-transactional-config-reads.rst diff --git a/source/includes/fact-5.0-non-transactional-config-reads.rst b/source/includes/fact-5.0-non-transactional-config-reads.rst new file mode 100644 index 00000000000..a1fe1c0738c --- /dev/null +++ b/source/includes/fact-5.0-non-transactional-config-reads.rst @@ -0,0 +1,10 @@ +Starting in MongoDB 5.0, non-transaction reads are not allowed on +the :data:`config.transactions` collection with the following +read concerns and options: + +- :readconcern:`"snapshot"` +- :readconcern:`"majority"` and the + :ref:`afterClusterTime` option is set +- When using a :driver:`MongoDB Driver ` + and :readconcern:`"majority"` + within a :ref:`causally consistent session` \ No newline at end of file diff --git a/source/reference/config-database.txt b/source/reference/config-database.txt index e733bc179f1..cafd1e88efa 100644 --- a/source/reference/config-database.txt +++ b/source/reference/config-database.txt @@ -26,6 +26,8 @@ The collections in the ``config`` database support: Restrictions ------------ +.. include:: /includes/fact-5.0-non-transactional-config-reads.rst + .. important:: The schema of the ``config`` database is *internal* and may change between releases of MongoDB. The ``config`` database is not a dependable API, and users should not diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt index def454a00be..41d032dca77 100644 --- a/source/release-notes/5.0-compatibility.txt +++ b/source/release-notes/5.0-compatibility.txt @@ -153,6 +153,11 @@ Replica Sets Starting in MongoDB 5.0, :rsconf:`~members[n].secondaryDelaySecs` replaces ``slaveDelay``. This change is not backwards compatible. +Non-transactional Reads on ``config.transactions`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/fact-5.0-non-transactional-config-reads.rst + Manual Oplog Writes ~~~~~~~~~~~~~~~~~~~ diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 0355a92cde1..39bdcaed208 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -370,6 +370,11 @@ Starting in MongoDB 5.0, these database commands and Replica Sets ------------ +Non-transactional Reads on ``config.transactions`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/fact-5.0-non-transactional-config-reads.rst + ``hello`` Command ~~~~~~~~~~~~~~~~~ From d206f002d7ed16c2b3973538c8163c4bb658cea4 Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Thu, 2 Sep 2021 14:32:08 -0400 Subject: [PATCH 023/109] (DOCS-14776): Prepare changelog for 4.0.27 --- .../includes/changelogs/releases/4.0.27.rst | 51 +++++++++++++++++++ source/release-notes/4.0-changelog.txt | 2 + source/release-notes/4.0.txt | 23 +++++++++ 3 files changed, 76 insertions(+) create mode 100644 source/includes/changelogs/releases/4.0.27.rst diff --git a/source/includes/changelogs/releases/4.0.27.rst b/source/includes/changelogs/releases/4.0.27.rst new file mode 100644 index 00000000000..0f2913f4c59 --- /dev/null +++ b/source/includes/changelogs/releases/4.0.27.rst @@ -0,0 +1,51 @@ +.. _4.0.27-changelog: + +4.0.27 Changelog +---------------- + +Sharding +~~~~~~~~ + +:issue:`SERVER-40170` Increase the default timeout for unit-tests which schedule work through NetworkTestEnv::launchAsync + +Replication +~~~~~~~~~~~ + +- :issue:`SERVER-34938` Secondary slowdown or hang due to content pinned in cache by single oplog batch +- :issue:`SERVER-36263` Bypassing operation validation in applyOps should require special privilege + +Query +~~~~~ + +:issue:`SERVER-58127` Fix benchRun() memory leak for parsing benchRun() args under exception + +Storage +~~~~~~~ + +:issue:`SERVER-40712` Clarify the behaviour of db.dropDatabase and the dropDatabase command + +Build and Packaging +~~~~~~~~~~~~~~~~~~~ + +:issue:`SERVER-54729` MongoDB Enterprise Debian/Ubuntu packages should depend on libsasl2-modules and libsasl2-modules-gssapi-mit + +Internals +~~~~~~~~~ + +- :issue:`SERVER-53726` Platform Support: Remove RHEL6 zSeries +- :issue:`SERVER-53728` Platform Support: Remove SLES12 zSeries +- :issue:`SERVER-55649` Sharding messages being logged for non-sharded clusters +- :issue:`SERVER-56516` Fix undefined behaviour in parsing code for $slice projectional operator +- :issue:`SERVER-57642` Invariant Failure on src/mongo/db/query/plan_yield_policy.cpp 75 | Aborting +- :issue:`SERVER-57798` Direct user to MongoDB Compass download page when failing to install MongoDB Compass due to a connection issue using ./install_compass +- :issue:`SERVER-57983` Integer overflow for $range in Classic Engine +- :issue:`SERVER-58283` Add a new versioning file to set MONGO_VERSION and MONGO_GIT_HASH +- :issue:`SERVER-58402` Increase timeout of shutdown command in shutdown_primary.js +- :issue:`SERVER-59055` Pin oauthlib == 3.1.0 in 4.0 branch +- :issue:`SERVER-59074` Do not acquire storage tickets just to set/wait on oplog visibility +- :issue:`SERVER-59197` Delete fam image entries when the corresponding session documents are deleted +- :issue:`SERVER-59242` update to snmp 5.9.1 +- :issue:`SERVER-59262` Remove burn_in_tests tasks from storeFindAndModifyImagesInSideCollection build variants +- :issue:`SERVER-59414` Retry curator setup in powercycle on older branches +- :issue:`SERVER-59504` Fix formatting in network_test_env.h on v4.0 + diff --git a/source/release-notes/4.0-changelog.txt b/source/release-notes/4.0-changelog.txt index a1e43cd9e28..3ce5d108de6 100644 --- a/source/release-notes/4.0-changelog.txt +++ b/source/release-notes/4.0-changelog.txt @@ -10,6 +10,8 @@ :depth: 1 :class: twocols +.. include:: /includes/changelogs/releases/4.0.27.rst + .. include:: /includes/changelogs/releases/4.0.26.rst .. include:: /includes/changelogs/releases/4.0.25.rst diff --git a/source/release-notes/4.0.txt b/source/release-notes/4.0.txt index 028d439138a..7edb04e8b87 100644 --- a/source/release-notes/4.0.txt +++ b/source/release-notes/4.0.txt @@ -13,6 +13,29 @@ Release Notes for MongoDB 4.0 Minor Releases -------------- +.. _4.0.27-release-notes: + +4.0.27 - Upcoming +~~~~~~~~~~~~~~~~~ + +Issues fixed: + +- :issue:`SERVER-59074` Do not acquire storage tickets just to set/wait + on oplog visibility +- :issue:`SERVER-56516` Fix undefined behavior in parsing code for + $slice projectional operator +- :issue:`SERVER-54729` MongoDB Enterprise Debian/Ubuntu packages + should depend on libsasl2-modules and libsasl2-modules-gssapi-mit +- :issue:`SERVER-40712` Clarify the behavior of db.dropDatabase and + the dropDatabase command +- :issue:`SERVER-34938` Secondary slowdown or hang due to content + pinned in cache by single oplog batch + +- `All JIRA issues closed in 4.0.27 + `_ + +- :ref:`4.0.27-changelog` + .. _4.0.26-release-notes: 4.0.26 - Jul 23, 2021 From 6534d7f5c1bce476609c7eb90cb340d4d2005aab Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Thu, 2 Sep 2021 15:08:49 -0400 Subject: [PATCH 024/109] (DOCS-14775): Prepare changelog for 4.2.16 --- .../includes/changelogs/releases/4.2.16.rst | 83 +++++++++++++++++++ source/release-notes/4.2-changelog.txt | 2 + source/release-notes/4.2.txt | 24 ++++++ 3 files changed, 109 insertions(+) create mode 100644 source/includes/changelogs/releases/4.2.16.rst diff --git a/source/includes/changelogs/releases/4.2.16.rst b/source/includes/changelogs/releases/4.2.16.rst new file mode 100644 index 00000000000..a0bf85ba432 --- /dev/null +++ b/source/includes/changelogs/releases/4.2.16.rst @@ -0,0 +1,83 @@ +.. _4.2.16-changelog: + +4.2.16 Changelog +---------------- + +Security +~~~~~~~~ + +:issue:`SERVER-57727` Race conditions in x509_invalid.js + +Sharding +~~~~~~~~ + +- :issue:`SERVER-55648` Mongos doesn't return top-level batch-write error in case of shutdown +- :issue:`SERVER-58909` Missing versions for "admin" and "config" databases migrating to version 4.2 + +Replication +~~~~~~~~~~~ + +- :issue:`SERVER-34938` Secondary slowdown or hang due to content pinned in cache by single oplog batch +- :issue:`SERVER-36263` Bypassing operation validation in applyOps should require special privilege +- :issue:`SERVER-37904` Allow a node to override the cluster chaining (enabled/disabled) setting +- :issue:`SERVER-39621` Disabled chaining should enforce sync source change when the primary steps down even if the oplog fetcher isn't killed on sync source +- :issue:`SERVER-41875` Should ban "emptyCapped" commands on jstestfuzz_concurrent_replication_continuous__stepdown suite for WiredTiger Storage. +- :issue:`SERVER-50486` invokeWithSessionCheckedOut being called on prepared transactions on secondaries +- :issue:`SERVER-55465` Fix Invariant upon failed request for a vote from the current primary in the election dry-run of catchup takeover +- :issue:`SERVER-58258` Wait for initial sync to clear state before asserting 'replSetGetStatus' reply has no 'initialSync' field + +Query +~~~~~ + +- :issue:`SERVER-55319` [4.2] Invariant failure isVersionInitialized() src/mongo/db/server_options.h 217 after index build completes +- :issue:`SERVER-58127` Fix benchRun() memory leak for parsing benchRun() args under exception + +Build and Packaging +~~~~~~~~~~~~~~~~~~~ + +:issue:`SERVER-54729` MongoDB Enterprise Debian/Ubuntu packages should depend on libsasl2-modules and libsasl2-modules-gssapi-mit + +Internals +~~~~~~~~~ + +- :issue:`SERVER-49237` Add a way for OperationContexts to opt-in to always getting interrupted at stepdown +- :issue:`SERVER-50547` Explore aggregation pipeline length limit +- :issue:`SERVER-52728` Upgrade path from MongoDB 2.4 to 4.2 causes config servers to go down +- :issue:`SERVER-53431` Server should respond running operations with appropriate topologyVersion on stepdown +- :issue:`SERVER-53726` Platform Support: Remove RHEL6 zSeries +- :issue:`SERVER-55649` Sharding messages being logged for non-sharded clusters +- :issue:`SERVER-56489` New pass-through test with random hello server-side delays +- :issue:`SERVER-56516` Fix undefined behaviour in parsing code for $slice projectional operator +- :issue:`SERVER-56839` Index seeks concurrent with recently-committed prepared transactions can return wrong results +- :issue:`SERVER-57033` The AuthorizationManager Cache in 4.2 should use roles as cache key +- :issue:`SERVER-57064` Log create index and dropIndex(es) on mongos +- :issue:`SERVER-57360` Log additional debug info for the "invariant (_requests.empty());" in ~LockerImpl +- :issue:`SERVER-57642` Invariant Failure on src/mongo/db/query/plan_yield_policy.cpp 75 | Aborting +- :issue:`SERVER-57650` Make MigrationChunkClonerSource interruptible when waiting response to recipient commands +- :issue:`SERVER-57798` Direct user to MongoDB Compass download page when failing to install MongoDB Compass due to a connection issue using ./install_compass +- :issue:`SERVER-57983` Integer overflow for $range in Classic Engine +- :issue:`SERVER-58169` Log timestamps info on hitting invariants around stable timestamp calculation +- :issue:`SERVER-58187` Improve Connection Reaper and MongoLDAP performance +- :issue:`SERVER-58191` [Migrate Protocol] Allow delete_during_migrate.js to tolerate chunk migration failures due to timeout in catchup phase in slow variants. +- :issue:`SERVER-58283` Add a new versioning file to set MONGO_VERSION and MONGO_GIT_HASH +- :issue:`SERVER-58313` Fix package test failure caused by SERVER-55460 backport to v4.2 and v4.0 +- :issue:`SERVER-58402` Increase timeout of shutdown command in shutdown_primary.js +- :issue:`SERVER-58623` Shorten the mongos RSM refresh interval in delayed Hello tests +- :issue:`SERVER-58826` [4.2] Disallow compact_keeps_indexes.js and explain_shell_helpers .js to run concurrently on parallel suite +- :issue:`SERVER-59074` Do not acquire storage tickets just to set/wait on oplog visibility +- :issue:`SERVER-59135` Make mongocryptd targets in MSIs depend on libsasl2 +- :issue:`SERVER-59197` Delete fam image entries when the corresponding session documents are deleted +- :issue:`SERVER-59242` update to snmp 5.9.1 +- :issue:`SERVER-59262` Remove burn_in_tests tasks from storeFindAndModifyImagesInSideCollection build variants +- :issue:`SERVER-59388` Revert BACKPORT-10185 +- :issue:`SERVER-59414` Retry curator setup in powercycle on older branches +- :issue:`WT-6568` Fix split generation use +- :issue:`WT-6926` Update WiredTiger source code to include 2021 copyright notices +- :issue:`WT-7065` Add check for WT_DHANDLE_DEAD to assertion +- :issue:`WT-7135` Additional checks to detect when writing corrupted metadata +- :issue:`WT-7437` Upgrade documentation to doxygen 1.8.17 +- :issue:`WT-7675` Query last ckpt timestamp changes without taking checkpoint +- :issue:`WT-7721` Update test-format to reopen an existing database with different config +- :issue:`WT-7776` Add a hard limit on the number of modify updates before we instantiate a complete update +- :issue:`WT-7871` Remove comment that is no longer true + diff --git a/source/release-notes/4.2-changelog.txt b/source/release-notes/4.2-changelog.txt index aeba54fa9a2..7cedaf13e73 100644 --- a/source/release-notes/4.2-changelog.txt +++ b/source/release-notes/4.2-changelog.txt @@ -10,6 +10,8 @@ :depth: 1 :class: singlecol +.. include:: /includes/changelogs/releases/4.2.16.rst + .. include:: /includes/changelogs/releases/4.2.15.rst .. include:: /includes/changelogs/releases/4.2.14.rst diff --git a/source/release-notes/4.2.txt b/source/release-notes/4.2.txt index 71eb784c83e..19cc51c406e 100644 --- a/source/release-notes/4.2.txt +++ b/source/release-notes/4.2.txt @@ -13,6 +13,30 @@ Release Notes for MongoDB 4.2 Minor Releases -------------- +.. _4.2.16-release-notes: + +4.2.16 - Upcoming +~~~~~~~~~~~~~~~~~~ + +Issues fixed in 4.2.16: + +- :issue:`SERVER-59074`: Do not acquire storage tickets just to + set/wait on oplog visibility +- :issue:`SERVER-54729`: MongoDB Enterprise Debian/Ubuntu packages + should depend on libsasl2-modules and libsasl2-modules-gssapi-mit +- :issue:`SERVER-39621`: Disabled chaining should enforce sync source + change when the primary steps down even if the oplog fetcher isn't + killed on sync source +- :issue:`SERVER-34938`: Secondary slowdown or hang due to content + pinned in cache by single oplog batch +- :issue:`WT-7776`: Add a hard limit on the number of modify updates + before we instantiate a complete update + +- `All JIRA issues closed in 4.2.16 + `__ + +- :ref:`4.2.16-changelog` + .. _4.2.15-release-notes: 4.2.15 - Jul 13, 2021 From 81204716a60633392f71e3213f159e61e13dd3c3 Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Mon, 30 Aug 2021 11:52:32 -0400 Subject: [PATCH 025/109] (DOCSP-18316): Improve implicit default write concern docs --- source/core/replica-set-rollbacks.txt | 23 ++++++------ source/includes/5.0-default-wc.rst | 50 +++++++++++++++++++++++---- source/reference/mongodb-defaults.txt | 7 ---- source/reference/write-concern.txt | 4 +-- source/release-notes/5.0.txt | 8 ++--- 5 files changed, 62 insertions(+), 30 deletions(-) diff --git a/source/core/replica-set-rollbacks.txt b/source/core/replica-set-rollbacks.txt index 87eacaf6a0a..c7dd6f32596 100644 --- a/source/core/replica-set-rollbacks.txt +++ b/source/core/replica-set-rollbacks.txt @@ -171,25 +171,26 @@ administrators can decide the next course of action to take. Avoid Replica Set Rollbacks --------------------------- -For replica sets, the :doc:`write concern {w: 1} -` only provides acknowledgement of write -operations on the primary. With the default write concern, data may be -rolled back if the primary steps down before the write operations have -replicated to any of the secondaries. This includes data written in -:doc:`multi-document transactions ` that commit -using :writeconcern:`"w: 1" <\>` write concern. - -.. include:: /includes/5.0-default-wc.rst +For replica sets, the :doc:`write concern ` +:writeconcern:`{ w: 1 } <\>` only provides acknowledgement of write +operations on the primary. Data may be rolled back if the primary steps +down before the write operations have replicated to any of the +secondaries. This includes data written in :doc:`multi-document +transactions ` that commit using +:writeconcern:`{ w: 1 } <\>` write concern. Journaling and Write Concern ``majority`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To prevent rollbacks of data that have been acknowledged to the client, -run all voting members with journaling enabled and use :ref:`w: -majority write concern ` to guarantee that the write operations +run all voting members with journaling enabled and use :ref:`{ w: +"majority" } write concern ` to guarantee that the write operations propagate to a majority of the replica set nodes before returning with acknowledgement to the issuing client. +Starting in MongoDB 5.0, ``{ w: "majority" }`` is the default write concern +for *most* MongoDB deployments. See :ref:`wc-default-behavior`. + .. include:: /includes/extracts/no-journaling-rollback.rst Visibility of Data That Can Be Rolled Back diff --git a/source/includes/5.0-default-wc.rst b/source/includes/5.0-default-wc.rst index dc763006b62..3f51810d3df 100644 --- a/source/includes/5.0-default-wc.rst +++ b/source/includes/5.0-default-wc.rst @@ -3,11 +3,13 @@ Starting in MongoDB 5.0, the implicit default write concern is considerations are made for deployments containing :ref:`arbiters `: -- If the number of data-bearing voting members is not strictly more - than the voting majority, the default write concern is ``w: 1``. +- The voting majority of a replica set is 1 plus half the number of + voting members, rounded down. If the number of data-bearing voting + members is not greater than the voting majority, the default write + concern is ``{ w: 1 }``. -- In all other scenarios, the default write concern is ``w: - "majority"``. +- In all other scenarios, the default write concern is ``{ w: + "majority" }``. Specifically, MongoDB uses the following formula to determine the default write concern: @@ -15,7 +17,43 @@ default write concern: .. code-block:: none :copyable: false - if [(#arbiters > 0) AND (#arbiters >= ½(#voting nodes) - 1)] + if [ (#arbiters > 0) AND (#non-arbiters <= majority(#voting-nodes)) ] defaultWriteConcern = { w: 1 } else - defaultWriteConcern = { w: majority } + defaultWriteConcern = { w: "majority" } + +For example, consider the following deployments and their respective +default write concerns: + +.. list-table:: + :header-rows: 1 + + * - Non-Arbiters + - Arbiters + - Voting Nodes + - Majority of Voting Nodes + - Implicit Default Write Concern + + * - 3 + - 1 + - 4 + - 3 + - ``{ w: 1 }`` + + * - 4 + - 1 + - 5 + - 3 + - ``{ w: "majority" }`` + +- The first example has 3 non-arbiters and 1 arbiter for a total of 4 + voting nodes. The majority of voting nodes (1 plus half of 4) is 3. + The number of non-arbiters (3) is less than or equal to the majority + of voting nodes, resulting in an implicit write concern of + ``{ w: 1 }``. + +- The second example has 4 non-arbiters and 1 arbiter for a total of 5 + voting nodes. The majority of voting nodes (1 plus half of 5, rounded + down) is 3. The number of non-arbiters (4) is greater than the majority + of voting nodes, resulting in an implicit write concern of ``{ w: + "majority" }``. diff --git a/source/reference/mongodb-defaults.txt b/source/reference/mongodb-defaults.txt index ecb8d6035b6..a0b7f91ac00 100644 --- a/source/reference/mongodb-defaults.txt +++ b/source/reference/mongodb-defaults.txt @@ -220,13 +220,6 @@ Default Write Concern .. include:: /includes/5.0-default-wc.rst -.. note:: - - - With the default write concern, data can be rolled back. - - - This write concern :red:`does not` guarantee :ref:`causal - consistency `. - .. _mongodb-default-wc-txns: .. _mongodb-default-wc-outside-transactions: diff --git a/source/reference/write-concern.txt b/source/reference/write-concern.txt index 8eac4aed15d..89782b90693 100644 --- a/source/reference/write-concern.txt +++ b/source/reference/write-concern.txt @@ -82,8 +82,8 @@ available: the :ref:`calculated majority ` of the data-bearing voting members (i.e. primary and secondaries with :rsconf:`members[n].votes` greater than ``0``). - ``w: majority`` is the default write concern for *most* MongoDB - configurations. See :ref:`wc-default-behavior`. + ``{ w: "majority" }`` is the default write concern for *most* MongoDB + deployments. See :ref:`wc-default-behavior`. For example, consider a replica set with 3 voting members, Primary-Secondary-Secondary (P-S-S). For this replica set, diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 39bdcaed208..2b69aa5742b 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -667,12 +667,12 @@ Implicit Default Write Concern .. include:: /includes/5.0-default-wc.rst -This default :doc:`write concern ` provides a -stronger durability guarantee in the event of an election, or if replica -set members become unavailable. +The ``{ w: "majority" }`` default :doc:`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 -peformance since writes will only be acknowledged once a +performance since writes will only be acknowledged once a :ref:`calculated majority ` of replica set members have executed and persisted the write to disk. From aff1d3faa679c5f56ca765241a5cb6ab50af417a Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Thu, 2 Sep 2021 13:57:29 -0400 Subject: [PATCH 026/109] (DOCS-13376): Add performance warnings for validation --- source/reference/command/validate.txt | 18 ++++++++++++++++++ .../method/db.collection.validate.txt | 18 +++++++++++++++--- 2 files changed, 33 insertions(+), 3 deletions(-) diff --git a/source/reference/command/validate.txt b/source/reference/command/validate.txt index cdd3dba2de0..71c88115c86 100644 --- a/source/reference/command/validate.txt +++ b/source/reference/command/validate.txt @@ -28,6 +28,10 @@ Definition The :dbcommand:`validate` command does not support :doc:`views ` and raises an error when run against a view. + The :method:`db.collection.validate()` method in + :binary:`~bin.mongosh` provides a wrapper around + :dbcommand:`validate`. + Syntax ------ @@ -96,6 +100,9 @@ The command takes the following fields: Behavior -------- +Performance +~~~~~~~~~~~ + The :dbcommand:`validate` command can be slow, particularly on larger data sets. @@ -105,6 +112,17 @@ until the operation finishes. When run on a secondary, the :dbcommand:`validate` operation can block all other operations on that secondary until it finishes. +.. warning:: + + Due to the performance impact of validation, consider running + :dbcommand:`validate` only on :term:`secondary` replica set nodes. + You can use :method:`rs.stepDown()` to instruct the current + :term:`primary` node to become a secondary to avoid impacting a live + primary node. + +Data Throughput Metrics +~~~~~~~~~~~~~~~~~~~~~~~ + .. include:: /includes/extracts/4.4-validate-data-throughput.rst Restrictions diff --git a/source/reference/method/db.collection.validate.txt b/source/reference/method/db.collection.validate.txt index c96f46f42f4..d5dad529833 100644 --- a/source/reference/method/db.collection.validate.txt +++ b/source/reference/method/db.collection.validate.txt @@ -97,8 +97,12 @@ following optional document parameter with the fields: Behavior -------- +Performance +~~~~~~~~~~~ + The :method:`db.collection.validate()` method is potentially resource -intensive and may impact the performance of your MongoDB instance. +intensive and may impact the performance of your MongoDB instance, +particularly on larger data sets. The :method:`db.collection.validate()` method obtains an exclusive lock on the collection. This will block all reads and writes on the @@ -106,8 +110,16 @@ collection until the operation finishes. When run on a secondary, the operation can block all other operations on that secondary until it finishes. -The :method:`db.collection.validate()` method can be slow, particularly -on larger data sets. +.. warning:: + + Due to the performance impact of validation, consider running + :method:`db.collection.validate()` only on :term:`secondary` replica + set nodes. You can use :method:`rs.stepDown()` to instruct the + current :term:`primary` node to become a secondary to avoid + impacting a live primary node. + +Data Throughput Metrics +~~~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/extracts/4.4-validate-data-throughput.rst From e45406e102c19a8ff7252178b53c164ea4c9874d Mon Sep 17 00:00:00 2001 From: Dave Cuthbert Date: Thu, 2 Sep 2021 13:56:04 -0400 Subject: [PATCH 027/109] DOCSP-18504-remove-odd-numbered-release-warning --- source/includes/5.0-changes/fact-odd-number-releases.rst | 6 ++++++ .../steps-install-mongodb-enterprise-on-red-hat.yaml | 6 +++--- source/includes/steps-install-mongodb-on-red-hat.yaml | 6 +++--- 3 files changed, 12 insertions(+), 6 deletions(-) create mode 100644 source/includes/5.0-changes/fact-odd-number-releases.rst diff --git a/source/includes/5.0-changes/fact-odd-number-releases.rst b/source/includes/5.0-changes/fact-odd-number-releases.rst new file mode 100644 index 00000000000..b36b0c6a28d --- /dev/null +++ b/source/includes/5.0-changes/fact-odd-number-releases.rst @@ -0,0 +1,6 @@ +Prior to MongoDB 5.0, odd-numbered MongoDB release versions, such as +``4.3``, were development releases. Beginning with MongoDB 5.1, +MongoDB has quarterly rapid releases. For more information on the +differences between rapid and long-term support releases, see +:ref:`release-version-numbers`. + diff --git a/source/includes/steps-install-mongodb-enterprise-on-red-hat.yaml b/source/includes/steps-install-mongodb-enterprise-on-red-hat.yaml index d6c62b5d8e6..e7b4510e5fc 100644 --- a/source/includes/steps-install-mongodb-enterprise-on-red-hat.yaml +++ b/source/includes/steps-install-mongodb-enterprise-on-red-hat.yaml @@ -27,9 +27,9 @@ post: | version (e.g. ``{{distro_num}}``), then MongoDB :doc:`release version ` (e.g. ``{+version+}``), then architecture (e.g. ``x86_64``). - Odd-numbered MongoDB release versions, such as - ``{+version-dev+}``, are development versions and are - unsuitable for production deployment. + + .. include:: /includes/5.0-changes/fact-odd-number-releases.rst + replacement: distro_name: "redhat" distro_link: "`MongoDB repository `_" diff --git a/source/includes/steps-install-mongodb-on-red-hat.yaml b/source/includes/steps-install-mongodb-on-red-hat.yaml index 682703d0a58..c6fb79ab530 100644 --- a/source/includes/steps-install-mongodb-on-red-hat.yaml +++ b/source/includes/steps-install-mongodb-on-red-hat.yaml @@ -20,9 +20,9 @@ post: | version (e.g. ``{{distro_num}}``), then MongoDB :doc:`release version ` (e.g. ``{+version+}``), then architecture (e.g. ``x86_64``). - Odd-numbered MongoDB release versions, such as - ``{+version-dev+}``, are development versions and are - unsuitable for production deployment. + + .. include:: /includes/5.0-changes/fact-odd-number-releases.rst + replacement: distro_name: "redhat" distro_link: "`MongoDB repository `_" From 240f4a29d32245307ebca481713d70ce1d05c39a Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Fri, 27 Aug 2021 15:39:22 -0400 Subject: [PATCH 028/109] DOCS-13838 Add error message notice to enableReadConcern --- source/reference/configuration-options.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/source/reference/configuration-options.txt b/source/reference/configuration-options.txt index cf01997e585..2b30159c712 100644 --- a/source/reference/configuration-options.txt +++ b/source/reference/configuration-options.txt @@ -4205,7 +4205,12 @@ LDAP Parameters Starting in MongoDB 5.0, :setting:`~replication.enableMajorityReadConcern` cannot be changed - and is always set to ``true``. In earlier versions of MongoDB, + and is always set to ``true``. Attempting to start a storage engine + that does not support majority read concern with the + ``--enableMajorityReadConcern`` option will fail and return an error + message. + + In earlier versions of MongoDB, :setting:`~replication.enableMajorityReadConcern` was configurable. .. warning:: From ed09d4185c20e9dab108822b8eded224025883d8 Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Fri, 3 Sep 2021 16:53:54 -0400 Subject: [PATCH 029/109] (DOCSP-18316): Change implicit write concern example --- source/includes/5.0-default-wc.rst | 43 +++++++++++++++++++----------- source/release-notes/5.0.txt | 28 +++++++++---------- 2 files changed, 42 insertions(+), 29 deletions(-) diff --git a/source/includes/5.0-default-wc.rst b/source/includes/5.0-default-wc.rst index 3f51810d3df..65a5befaa29 100644 --- a/source/includes/5.0-default-wc.rst +++ b/source/includes/5.0-default-wc.rst @@ -1,7 +1,8 @@ -Starting in MongoDB 5.0, the implicit default write concern is +Starting in MongoDB 5.0, the implicit default +:ref:`write concern ` is :writeconcern:`w: majority <"majority">`. However, special -considerations are made for deployments containing :ref:`arbiters -`: +considerations are made for deployments containing +:ref:`arbiters `: - The voting majority of a replica set is 1 plus half the number of voting members, rounded down. If the number of data-bearing voting @@ -34,10 +35,10 @@ default write concerns: - Majority of Voting Nodes - Implicit Default Write Concern - * - 3 + * - 2 - 1 - - 4 - 3 + - 2 - ``{ w: 1 }`` * - 4 @@ -46,14 +47,26 @@ default write concerns: - 3 - ``{ w: "majority" }`` -- The first example has 3 non-arbiters and 1 arbiter for a total of 4 - voting nodes. The majority of voting nodes (1 plus half of 4) is 3. - The number of non-arbiters (3) is less than or equal to the majority - of voting nodes, resulting in an implicit write concern of - ``{ w: 1 }``. +- In the first example: -- The second example has 4 non-arbiters and 1 arbiter for a total of 5 - voting nodes. The majority of voting nodes (1 plus half of 5, rounded - down) is 3. The number of non-arbiters (4) is greater than the majority - of voting nodes, resulting in an implicit write concern of ``{ w: - "majority" }``. + - There are 2 non-arbiters and 1 arbiter for a total of 3 voting + nodes. + + - The majority of voting nodes (1 plus half of 3, rounded + down) is 2. + + - The number of non-arbiters (2) is equal to + the majority of voting nodes (2), resulting in an implicit write + concern of ``{ w: 1 }``. + +- In the second example: + + - There are 4 non-arbiters and 1 arbiter for a total of 5 + voting nodes. + + - The majority of voting nodes (1 plus half of 5, rounded + down) is 3. + + - The number of non-arbiters (4) is greater than the majority + of voting nodes (3), resulting in an implicit write concern of + ``{ w: "majority" }``. diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 2b69aa5742b..110a9326f95 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -667,20 +667,20 @@ Implicit Default Write Concern .. include:: /includes/5.0-default-wc.rst -The ``{ w: "majority" }`` default :doc:`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 ` 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 +The :writeconcern:`{ w: "majority" } <"majority">` default +:doc:`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 ` 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 From 2554a15051a54fa47547ee612a86b485d2dfffe0 Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Mon, 30 Aug 2021 16:16:17 -0400 Subject: [PATCH 030/109] DOCS-14765 Add Extra code examples for rs.reconfig() --- source/reference/method/rs.reconfig.txt | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/source/reference/method/rs.reconfig.txt b/source/reference/method/rs.reconfig.txt index 1588a7e4fcd..2ad4bd47de8 100644 --- a/source/reference/method/rs.reconfig.txt +++ b/source/reference/method/rs.reconfig.txt @@ -307,6 +307,9 @@ A replica set named ``rs0`` has the following configuration: } } +Change Replica Set Member Priority +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The following sequence of operations updates the :rsconf:`members[n].priority` of the second member. The operations are issued through a :binary:`~bin.mongosh` session that is connected to @@ -402,6 +405,24 @@ the primary. } } +Change Replica Set Settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also modify the cluster replica set :rsconf:`settings` document. +The :rsconf:`settings` document contains configuration options that +apply to the whole replica set. + +The following sequence of operations updates the +:rsconf:`settings.heartbeatTimeoutSecs` of the cluster to ``15``. +The operations are issued through a :binary:`~bin.mongosh` session +that is connected to the primary. + +.. code-block:: javascript + + cfg = rs.conf(); + cfg.settings.heartbeatTimeoutSecs = 15; + rs.reconfig(cfg); + .. seealso:: - :method:`rs.conf()` From 38178eaf50a961c08f829b571c53d72a20f69f7d Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Mon, 23 Aug 2021 16:18:29 +0200 Subject: [PATCH 031/109] DOCSP-18007: Refactor Enable Access Control page --- source/includes/extracts-5.0-changes.yaml | 11 + .../steps-authorization-create-users.yaml | 184 ++++++++++++ ...eate-admin-then-enable-authentication.yaml | 282 ++++++------------ source/tutorial/create-users.txt | 111 ++++--- source/tutorial/enable-authentication.txt | 78 ++--- 5 files changed, 390 insertions(+), 276 deletions(-) create mode 100644 source/includes/steps-authorization-create-users.yaml diff --git a/source/includes/extracts-5.0-changes.yaml b/source/includes/extracts-5.0-changes.yaml index 7eb11a0ff65..7852eaedbdf 100644 --- a/source/includes/extracts-5.0-changes.yaml +++ b/source/includes/extracts-5.0-changes.yaml @@ -29,4 +29,15 @@ content: | Dropping the :term:`admin database` or the :term:`config database` can leave your cluster in an unusable state. +--- + +ref: mongosh-password-prompt +content: | + + The :method:`passwordPrompt()` method prompts you to enter the + password. You can also specify your password directly as a string. We + recommend to use the :method:`passwordPrompt()` method to avoid the + password being visible on your screen and potentially leaking the + password to your shell history. + ... diff --git a/source/includes/steps-authorization-create-users.yaml b/source/includes/steps-authorization-create-users.yaml new file mode 100644 index 00000000000..43be6ede609 --- /dev/null +++ b/source/includes/steps-authorization-create-users.yaml @@ -0,0 +1,184 @@ +title: Connect and authenticate +level: 4 +stepnum: 1 +ref: auth-as-admin +content: | + Using :binary:`~bin.mongosh`, connect to your primary + :binary:`~bin.mongod` or, in a sharded cluster, connect to your + :binary:`~bin.mongos` and authenticate as a user administrator or a + user with the :ref:`required privileges `: + + .. tabs:: + + tabs: + - id: cmdline + name: Authenticate during Connection + content: | + Start :binary:`~bin.mongosh` with the :option:`-u + \ `, :option:`-p `, and the + :option:`--authenticationDatabase \ ` command line options: + + .. code-block:: bash + + mongosh --port 27017 --authenticationDatabase \ + "admin" -u "myUserAdmin" -p + + Enter your password when prompted. + + - id: authafter + name: Authenticate after Connection + content: | + + Using :binary:`~bin.mongosh`, connect to your database + deployment: + + .. code-block:: bash + + mongosh --port 27017 + + In :binary:`~bin.mongosh`, switch to the + authentication database (in this case, ``admin``), and + use the :method:`db.auth(\, \) + ` method to authenticate: + + .. code-block:: javascript + + use admin + db.auth("myUserAdmin", passwordPrompt()) // or cleartext password + + .. tip:: + + .. include:: /includes/extracts/mongosh-password-prompt.rst + + Enter the password when prompted. +--- +title: Create additional users for your deployment +level: 4 +stepnum: 2 +ref: create-additionalusers +pre: | + + .. note:: + + The following step uses :ref:`authentication-scram` authentication. + For additional information on other authentication mechanisms, see + :ref:`create-users-examples`. + + After authenticating as the user administrator, use the + :method:`db.createUser()` method to create additional users. You can assign + any :doc:`built-in roles ` or + :doc:`user-defined roles ` to the + users. + +action: + pre: | + The following operation adds a user ``myTester`` to the ``test`` + database who has the :authrole:`readWrite` role in the ``test`` + database as well as the :authrole:`read` role in the ``reporting`` + database. + + language: javascript + code: | + use test + db.createUser( + { + user: "myTester", + pwd: passwordPrompt(), // or cleartext password + roles: [ { role: "readWrite", db: "test" }, + { role: "read", db: "reporting" } ] + } + ) + +post: | + + .. tip:: + + .. include:: /includes/extracts/mongosh-password-prompt.rst + + The database where you create the user (in this example, ``test``) is + that user's :ref:`authentication database + `. Although the user authenticates to + this database, the user can have roles in other databases. The + user's authentication database does not limit the user's privileges. + + After creating the additional users, exit :binary:`~bin.mongosh`. + +--- +title: Connect to the instance and authenticate as ``myTester`` +level: 4 +ref: auth-as-mytester +content: | + + .. important:: + + It is not possible to switch between users in the same + :binary:`~bin.mongosh` session. Authenticating as a different user + means the session has the privileges of **both** authenticated + users. To switch between users exit and relaunch + :binary:`~bin.mongosh`. + + After exiting :binary:`~bin.mongosh` as ``myUserAdmin``, reconnect as + ``myTester``: + + .. tabs:: + + tabs: + - id: cmdline2 + name: Authenticate during Connection + content: | + Start :binary:`~bin.mongosh` with the :option:`-u + \ `, :option:`-p `, and the + :option:`--authenticationDatabase \ ` command line options: + + .. code-block:: bash + + mongosh --port 27017 -u "myTester" \ + --authenticationDatabase "test" -p + + Enter the password for the user when prompted. + + - id: authafter2 + name: Authenticate after Connection + content: | + + Using :binary:`~bin.mongosh`, connect to your database + deployment: + + .. code-block:: bash + + mongosh --port 27017 + + In :binary:`~bin.mongosh`, switch to the + authentication database (in this case, ``admin``), and + use the :method:`db.auth(\, \) + ` method to authenticate: + + .. code-block:: javascript + + use test + db.auth("myTester", passwordPrompt()) // or cleartext password + + .. tip:: + + .. include:: /includes/extracts/mongosh-password-prompt.rst + + Enter the password for the user when prompted. +--- +title: Insert a document as ``myTester`` +level: 4 +ref: insert-as-mytester +content: | + + As the user ``myTester``, you have privileges to perform read and + write operations in the ``test`` database (as well as perform read + operations in the ``reporting`` database). Once authenticated as + ``myTester``, insert a document into a collection in the ``test`` + database. For example, you can perform the following insert + operation in the ``test`` database: + + .. code-block:: javascript + + db.foo.insert( { x: 1, y: 1 } ) +... diff --git a/source/includes/steps-create-admin-then-enable-authentication.yaml b/source/includes/steps-create-admin-then-enable-authentication.yaml index 9f70d46eed9..a74e380c674 100644 --- a/source/includes/steps-create-admin-then-enable-authentication.yaml +++ b/source/includes/steps-create-admin-then-enable-authentication.yaml @@ -1,4 +1,4 @@ -title: Start MongoDB without access control. +title: Start MongoDB without access control stepnum: 1 level: 4 ref: start-without-auth @@ -6,119 +6,153 @@ pre: | Start a standalone :binary:`~bin.mongod` instance without access control. - - For example, open a terminal and issue the following: + + Open a terminal and run the following command: action: language: sh code: | mongod --port 27017 --dbpath /var/lib/mongodb +post: | + The :binary:`~bin.mongod` instance in this tutorial uses + :option:`port 27017 ` and the ``/var/lib/mongodb`` + data directory. The tutorial assumes that the ``/var/lib/mongodb`` + directory exists and is the default :setting:`~storage.dbPath`. You + may specify a different data directory or port as needed. + --- stepnum: 2 -title: Connect to the instance. +title: Connect to the instance level: 4 ref: connect pre: | - For example, open a new terminal and connect :binary:`~bin.mongosh` - to the instance: + Open a new terminal and connect to the database deployment with + :binary:`~bin.mongosh`: action: language: sh code: | - mongosh --port 27017 + mongosh --port 27017 post: | - Specify additional command line options as appropriate to connect - :binary:`~bin.mongosh` to your deployment, such as ``--host``. + If you are connecting to an existing deployment, specify additional + command line options, such as ``--host``, as needed to connect. --- stepnum: 3 -title: Create the user administrator. +title: Create the user administrator level: 4 ref: create-user-admin pre: | - From :binary:`~bin.mongosh`, add a user with the - :authrole:`userAdminAnyDatabase` role in the ``admin`` database. Include additional roles as - needed for this user. For example, the following - creates the user ``myUserAdmin`` in the ``admin`` database with the - :authrole:`userAdminAnyDatabase` role and the - :authrole:`readWriteAnyDatabase` role. + .. _create-user-admin: -action: - pre: | + .. important:: Localhost Exception + + You can create the user administrator either before or after + enabling access control. If you enable access control before + creating any user, MongoDB provides a :ref:`localhost exception + ` which allows you to create a user + administrator in the ``admin`` database. Once created, you must + authenticate as the user administrator to create additional users. + + The :authrole:`userAdminAnyDatabase` role allows this user to: - .. tip:: + - create users, + - grant or revoke roles from users, + - and create or modify customs roles. - .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst + You can assign your user additional :ref:`built-in roles + ` or :ref:`user-defined roles ` + as needed. + Using :binary:`~bin.mongosh`, switch to the ``admin`` database and + add the user ``myUserAdmin`` in the ``admin`` database with the + :authrole:`userAdminAnyDatabase` role and the + :authrole:`readWriteAnyDatabase` role: + +action: language: javascript code: | + use admin db.createUser( { user: "myUserAdmin", pwd: passwordPrompt(), // or cleartext password - roles: [ { role: "userAdminAnyDatabase", db: "admin" }, "readWriteAnyDatabase" ] + roles: [ + { role: "userAdminAnyDatabase", db: "admin" }, + { role: "readWriteAnyDatabase", db: "admin" } + ] } ) post: | - .. note:: - The database where you create the user (in this example, - ``admin``) is the user's :ref:`authentication database - `. Although the user would - authenticate to this database, the user can - have roles in other databases; i.e. the user's authentication - database does not limit the user's privileges. + + .. tip:: + + .. include:: /includes/extracts/mongosh-password-prompt.rst + + The database where you create the user (in this example, ``admin``) + is the user's :ref:`authentication database + `. Although the user needs to + authenticate to this database, the user can have roles in other + databases. The user's authentication database doesn't limit the + user's privileges. + --- -title: Re-start the MongoDB instance with access control. +title: Re-start the MongoDB instance with access control level: 4 stepnum: 4 ref: restart-with-auth content: | - - a. Shut down the :binary:`~bin.mongod` instance. For example, from - :binary:`~bin.mongosh`, issue the following command: - .. code-block:: javascript + Shut down the :binary:`~bin.mongod` instance. Using + :binary:`~bin.mongosh`, issue the following command: + + .. code-block:: javascript + + db.adminCommand( { shutdown: 1 } ) - db.adminCommand( { shutdown: 1 } ) + Exit :binary:`~bin.mongosh`. - #. Exit :binary:`~bin.mongosh`. + Start the :binary:`~bin.mongod` with access control enabled. - #. Start the :binary:`~bin.mongod` with access control enabled. + - If you start the :binary:`~bin.mongod` from the command line, add + the :option:`--auth ` command line option: - - If you start the :binary:`~bin.mongod` from the command line, add - the :option:`--auth ` command line option: + .. code-block:: bash - .. code-block:: bash + mongod --auth --port 27017 --dbpath /var/lib/mongodb - mongod --auth --port 27017 --dbpath /var/lib/mongodb + - If you start the :binary:`~bin.mongod` using a + :ref:`configuration file `, add the + :setting:`security.authorization` configuration file setting: - - If you start the :binary:`~bin.mongod` using a - :ref:`configuration file `, add the - :setting:`security.authorization` configuration file setting: + .. code-block:: bash - .. code-block:: bash + security: + authorization: enabled - security: - authorization: enabled + Clients that connect to this instance must now authenticate + themselves and can only perform actions as determined by their + assigned roles. + + .. important:: Localhost Exception + + You can create users either before or after enabling access + control. If you enable access control before creating any user, + MongoDB provides a :ref:`localhost exception + ` which allows you to create a user + administrator in the ``admin`` database. Once created, you must + authenticate as the user administrator to create additional users. - Clients that connect to this instance must now authenticate - themselves as a MongoDB user. Clients can only perform actions as - determined by their assigned roles. --- -title: Connect and authenticate as the user administrator. +title: Connect and authenticate as the user administrator level: 4 stepnum: 5 ref: auth-as-admin content: | Using :binary:`~bin.mongosh`, you can: - - Connect with authentication by passing in user credentials, or - - - Connect first without authentication, and then issue the - :method:`db.auth()` method to authenticate. - .. tabs:: tabs: @@ -132,155 +166,35 @@ content: | .. code-block:: bash - mongosh --port 27017 --authenticationDatabase "admin" -u "myUserAdmin" -p + mongosh --port 27017 --authenticationDatabase \ + "admin" -u "myUserAdmin" -p Enter your password when prompted. - id: authafter name: Authenticate after Connection content: | - - Connect :binary:`~bin.mongosh` to the - :binary:`~bin.mongod`: + + Using :binary:`~bin.mongosh`, connect to your database + deployment: .. code-block:: bash mongosh --port 27017 - In :binary:`~bin.mongosh`, switch to the authentication database (in this case, ``admin``), and - use :method:`db.auth(\, \) ` - method to authenticate: - - .. tip:: - - .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst + use the :method:`db.auth(\, \) + ` method to authenticate: .. code-block:: javascript use admin db.auth("myUserAdmin", passwordPrompt()) // or cleartext password - Enter the password when prompted. ---- -title: Create additional users as needed for your deployment. -level: 4 -stepnum: 6 -ref: create-additionalusers -pre: | - Once authenticated as the user administrator, use - :method:`db.createUser()` to create additional users. You can assign - any :doc:`built-in roles ` or - :doc:`user-defined roles ` to the - users. - -action: - pre: | - The following operation adds a user ``myTester`` to the ``test`` - database who has :authrole:`readWrite` role in the ``test`` - database as well as :authrole:`read` role in the ``reporting`` - database. - - .. tip:: - - .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst - - language: javascript - code: | - use test - db.createUser( - { - user: "myTester", - pwd: passwordPrompt(), // or cleartext password - roles: [ { role: "readWrite", db: "test" }, - { role: "read", db: "reporting" } ] - } - ) - -post: | - - .. note:: - The database where you create the user (in this example, - ``test``) is that user's :ref:`authentication database - `. Although the user would - authenticate to this database, the user can have roles in other - databases; i.e. the user's authentication database does not limit - the user's privileges. - - After creating the additional users, disconnect - :binary:`~bin.mongosh`. ---- -title: Connect to the instance and authenticate as ``myTester``. -level: 4 -ref: auth-as-mytester -content: | - - After disconnecting :binary:`~bin.mongosh` as - ``myUserAdmin``, reconnect as ``myTester``. You can: - - - Connect with authentication by passing in user credentials, or - - - Connect first without authentication, and then issue the - :method:`db.auth()` method to authenticate. - - .. tabs:: - - tabs: - - id: cmdline2 - name: Authenticate during Connection - content: | - Start :binary:`~bin.mongosh` with the :option:`-u - \ `, :option:`-p `, and the - :option:`--authenticationDatabase \ ` command line options: - - .. code-block:: bash - - mongosh --port 27017 -u "myTester" --authenticationDatabase "test" -p - - Enter the password for the user when prompted. - - - id: authafter2 - name: Authenticate after Connection - content: | - - Connect :binary:`~bin.mongosh` to the - :binary:`~bin.mongod`: - - .. code-block:: bash - - mongosh --port 27017 - - In :binary:`~bin.mongosh`, switch to the - authentication database (in this case, ``test``), and use - :method:`db.auth(\, \) ` - method to authenticate: - .. tip:: - .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst + .. include:: /includes/extracts/mongosh-password-prompt.rst - .. code-block:: javascript - - use test - db.auth("myTester", passwordPrompt()) // or cleartext password - - Enter the password for the user when prompted. ---- -title: Insert a document as ``myTester``. -level: 4 -ref: insert-as-mytester -content: | - - As ``myTester``, you have privileges to perform read and write - operations in the ``test`` database (as well as perform read - operations in the ``reporting`` database). Once authenticated as - ``myTester``, insert a document into a collection in ``test`` - database. For example, you can perform the following insert - operation in the ``test`` database: - - .. code-block:: javascript - - db.foo.insert( { x: 1, y: 1 } ) + Enter the password when prompted. ... diff --git a/source/tutorial/create-users.txt b/source/tutorial/create-users.txt index 1ae14e6a128..8c819a7c855 100644 --- a/source/tutorial/create-users.txt +++ b/source/tutorial/create-users.txt @@ -1,46 +1,58 @@ -========= -Add Users -========= +.. _create-users: + +============= +Create a User +============= .. default-domain:: mongodb .. contents:: On this page :local: :backlinks: none - :depth: 2 + :depth: 3 :class: singlecol -Overview --------- - -.. include:: /includes/intro-rbac.rst +With access control enabled, users are required to identify themselves +and can only perform actions that adhere to the permissions granted by +the :ref:`roles ` assigned to their user. .. _add-user-prereq: Prerequisites ------------- -If you have enabled access control for your deployment, you can use -the :ref:`localhost exception ` to create the first -user in the system. This first user must have privileges to create -other users. As of MongoDB 3.0, with the localhost exception, you -can only create users on the ``admin`` database. Once you create the -first user, you must authenticate as that user to add subsequent users. -:doc:`/tutorial/enable-authentication` provides more detail about -adding users when enabling access control for a deployment. +To be able to create users, you need to: + +- :ref:`enable access control ` +- :ref:`create a user administrator ` For routine user creation, you must possess the following permissions: .. include:: /includes/access-create-user.rst -.. _add-new-user: +.. _create-user-procedure: + +Procedure +--------- + +.. note:: -Examples --------- + The following procedure uses :ref:`authentication-scram` + authentication. For additional information on other authentication + mechanisms, see :ref:`create-users-examples`. -To create a user in a MongoDB deployment, you connect to the -deployment, and then use the :method:`db.createUser()` method -or :dbcommand:`createUser` command to add the user. +.. include:: /includes/steps/authorization-create-users.rst + +.. seealso:: + + :doc:`/tutorial/manage-users-and-roles` + + +.. _create-users-examples: +.. _add-new-user: + +Additional Examples +------------------- Username/Password Authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -50,7 +62,7 @@ database with the specified name, password, and roles. .. tip:: - .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst + .. include:: /includes/extracts/mongosh-password-prompt.rst .. code-block:: javascript @@ -68,19 +80,17 @@ database with the specified name, password, and roles. } ) -:doc:`/tutorial/enable-authentication` provides more details about -enforcing authentication for your MongoDB deployment. - Kerberos Authentication ~~~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/extracts/create-user-intro-kerberos.rst -For Kerberos authentication, you must add the Kerberos principal -as the username. You do not need to specify a password. +For Kerberos authentication, you must add the Kerberos principal as the +username. You do not need to specify a password. -The following operation adds the Kerberos principal ``reportingapp@EXAMPLE.NET`` -with read-only access to the ``records`` database. +The following operation adds the Kerberos principal +``reportingapp@EXAMPLE.NET`` with read-only access to the ``records`` +database: .. code-block:: javascript @@ -94,10 +104,13 @@ with read-only access to the ``records`` database. } ) -:doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` -and :doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication` -provide more details about setting up Kerberos authentication for your -MongoDB deployment. +.. seealso:: + + For more information about setting up Kerberos authentication for + your MongoDB deployment, see the following tutorials: + + - :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` + - :doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication` LDAP Authentication ~~~~~~~~~~~~~~~~~~~ @@ -107,8 +120,8 @@ LDAP Authentication For LDAP authentication, you must specify a username. You do not need to specify the password, as that is handled by the LDAP service. -The following operation adds the ``reporting`` user -with read-only access to the ``records`` database. +The following operation adds the ``reporting`` user with read-only +access to the ``records`` database: .. code-block:: javascript @@ -122,9 +135,13 @@ with read-only access to the ``records`` database. } ) -:doc:`/tutorial/configure-ldap-sasl-activedirectory` and -:doc:`/tutorial/configure-ldap-sasl-openldap` provide more detail about -using authenticating using LDAP. +.. seealso:: + + For more information about setting up LDAP authentication for + your MongoDB deployment, see the following tutorials: + + - :doc:`/tutorial/configure-ldap-sasl-activedirectory` + - :doc:`/tutorial/configure-ldap-sasl-openldap` x.509 Client Certificate Authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -152,6 +169,16 @@ user with read-only access to the ``records`` database. } ) -:doc:`/tutorial/configure-x509-client-authentication` provides details -about setting up x.509 Client Certificate authentication for your -MongoDB deployment. +.. seealso:: + + For more information about setting up x.509 Client Certificate + authentication for your MongoDB deployment, see the following + tutorials: + + - :doc:`/tutorial/configure-x509-client-authentication` + +Next Steps +---------- + +To manage users, assign roles, and create custom roles, see +:doc:`/tutorial/manage-users-and-roles`. diff --git a/source/tutorial/enable-authentication.txt b/source/tutorial/enable-authentication.txt index 40888f252b9..e1b96235d36 100644 --- a/source/tutorial/enable-authentication.txt +++ b/source/tutorial/enable-authentication.txt @@ -1,3 +1,5 @@ +.. _enable-access-control: + ===================== Enable Access Control ===================== @@ -7,70 +9,46 @@ Enable Access Control .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol -Overview --------- - -Enabling access control on a MongoDB deployment enforces -authentication, requiring users to identify themselves. When accessing -a MongoDB deployment that has access control enabled, users can only -perform actions as determined by their roles. +Enabling access control on a MongoDB deployment enforces authentication. +With access control enabled, users are required to identify themselves +and can only perform actions that adhere to the permissions granted by +the roles assigned to their user. -The following tutorial enables access control on a standalone +The following tutorial enables access control for a standalone :binary:`~bin.mongod` instance and uses the :ref:`default -authentication mechanism `. For all -supported authentication mechanisms, see +authentication mechanism `. For more +information about other authentication mechanisms, see :ref:`available-authentication-mechanisms`. -User Administrator ------------------- +If you would like to enable access control for a :doc:`replica set +` or a :doc:`sharded cluster `, please refer to +one of the following resources: -With access control enabled, ensure you have a user with -:authrole:`userAdmin` or :authrole:`userAdminAnyDatabase` role in the -``admin`` database. This user can administrate user and roles such as: -create users, grant or revoke roles from users, and create or modify -customs roles. +- :doc:`/tutorial/deploy-replica-set-with-keyfile-access-control` +- :doc:`/tutorial/enforce-keyfile-access-control-in-existing-replica-set` +- :doc:`/tutorial/enforce-keyfile-access-control-in-existing-replica-set-without-downtime` +- :doc:`/tutorial/deploy-sharded-cluster-with-keyfile-access-control` +- :doc:`/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster` +- :doc:`/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime` .. _enable-auth-procedure: -Procedure ---------- - -The following procedure first adds a user administrator to a MongoDB -instance running without access control and then enables access control. - -.. note:: - - The example MongoDB instance uses :option:`port 27017 ` and the data directory ``/var/lib/mongodb`` directory . The - example assumes the existence of the data directory - ``/var/lib/mongodb``. Specify a different data directory as - appropriate. - -.. include:: /includes/steps/create-admin-then-enable-authentication.rst +Enable Access Control for a Standalone ``mongod`` Instance +---------------------------------------------------------- .. seealso:: - :doc:`/tutorial/manage-users-and-roles`. + :ref:`available-authentication-mechanisms` -Additional Considerations -------------------------- - -Replica Sets and Sharded clusters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. include:: /includes/steps/create-admin-then-enable-authentication.rst -Replica sets and sharded clusters require internal authentication -between members when access control is enabled. For more details, -please see :doc:`/core/security-internal-authentication`. +Next Steps +---------- -Localhost Exception -~~~~~~~~~~~~~~~~~~~ +To create additional users, see :doc:`/tutorial/create-users`. -You can create users either before or after enabling access control. If -you enable access control before creating any user, MongoDB provides a -:ref:`localhost exception ` which allows you to -create a user administrator in the ``admin`` database. Once created, -you must authenticate as the user administrator to create additional -users as needed. +To manage users, assign roles, and create custom roles, see +:doc:`/tutorial/manage-users-and-roles`. From d94062843dd7252c89d181cda797c5fc9290ab62 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Wed, 8 Sep 2021 16:27:24 +0200 Subject: [PATCH 032/109] Fix timeseries example data structure --- source/core/timeseries-collections.txt | 24 +++++++++---------- .../timeseries-automatic-removal.txt | 2 +- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/source/core/timeseries-collections.txt b/source/core/timeseries-collections.txt index 9b07a1f8182..3f50a673e01 100644 --- a/source/core/timeseries-collections.txt +++ b/source/core/timeseries-collections.txt @@ -165,51 +165,51 @@ multiple documents at once, issue the following command: .. code-block:: javescript db.weather.insertMany([{ - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-18T00:00:00.000Z"), "temp": 12 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-18T04:00:00.000Z"), "temp": 11 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-18T08:00:00.000Z"), "temp": 11 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-18T12:00:00.000Z"), "temp": 12 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-18T16:00:00.000Z"), "temp": 16 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-18T20:00:00.000Z"), "temp": 15 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-19T00:00:00.000Z"), "temp": 13 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-19T04:00:00.000Z"), "temp": 12 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-19T08:00:00.000Z"), "temp": 11 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-19T12:00:00.000Z"), "temp": 12 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-19T16:00:00.000Z"), "temp": 17 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-19T20:00:00.000Z"), "temp": 12 }]) diff --git a/source/core/timeseries/timeseries-automatic-removal.txt b/source/core/timeseries/timeseries-automatic-removal.txt index 289cd6b6257..f21b7b710cd 100644 --- a/source/core/timeseries/timeseries-automatic-removal.txt +++ b/source/core/timeseries/timeseries-automatic-removal.txt @@ -42,7 +42,7 @@ specified number of seconds. Consider the following document in the .. code-block:: { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-18T10:00:00.000Z"), "temp": 12 } From 54883580930f86835ddb44ff8d68262706f2e5f9 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Tue, 24 Aug 2021 18:06:45 +0200 Subject: [PATCH 033/109] DOCSP-18008: Refactor authentication page --- source/core/authentication.txt | 56 ++++++++++++++++------------------ 1 file changed, 26 insertions(+), 30 deletions(-) diff --git a/source/core/authentication.txt b/source/core/authentication.txt index e5c53de6428..ce36e9da38c 100644 --- a/source/core/authentication.txt +++ b/source/core/authentication.txt @@ -12,46 +12,50 @@ Authentication :depth: 1 :class: singlecol -Authentication is the process of verifying the identity of a client. When -access control, i.e. :doc:`authorization `, is enabled, -MongoDB requires all clients to authenticate themselves in order to determine -their access. +Authentication is the process of verifying the identity of a client. +When access control (:doc:`authorization `) is +enabled, MongoDB requires all clients to authenticate themselves in +order to determine their access. -Although authentication and :doc:`authorization ` are -closely connected, authentication is distinct from authorization. -Authentication verifies the identity of a user; authorization determines the -verified user's access to resources and operations. +Although authentication and :doc:`authorization ` +are closely connected, authentication is distinct from authorization: -Authentication Methods ----------------------- +- **Authentication** verifies the identity of a :ref:`user `. +- **Authorization** determines the verified user's access to resources + and operations. -.. include:: /includes/fact-authenticate.rst +Getting Started +--------------- + +To get started using access control, follow these tutorials: + +- :ref:`enable-access-control` +- :ref:`add-new-user` .. _available-authentication-mechanisms: Authentication Mechanisms ------------------------- -MongoDB supports a number of :ref:`authentication mechanisms +MongoDB Community supports a number of :ref:`authentication mechanisms ` that clients can use to verify -their identity. These mechanisms allow MongoDB to integrate into your -existing authentication system. - -MongoDB supports multiple authentication mechanisms: +their identity: - :ref:`authentication-scram` (*Default*) - - :ref:`x.509 Certificate Authentication `. -In addition to supporting the aforementioned mechanisms, MongoDB Enterprise -also supports the following mechanisms: +In addition to the preceding mechanisms, MongoDB Atlas and MongoDB +Enterprise support the following mechanisms: - :ref:`LDAP proxy authentication `, and - - :ref:`Kerberos authentication `. -Internal Authentication ------------------------ +These mechanisms allow MongoDB to integrate into your +existing authentication system. + + +Internal / Membership Authentication +------------------------------------ In addition to verifying the identity of a client, MongoDB can require members of replica sets and sharded clusters to :ref:`authenticate @@ -59,14 +63,6 @@ their membership ` to their respective replica set or sharded cluster. See :ref:`inter-process-auth` for more information. -Authentication on Sharded Clusters ----------------------------------- - -In sharded clusters, clients generally authenticate directly to the -:binary:`~bin.mongos` instances. However, some maintenance operations may require -authenticating directly to a specific shard. For more information on -authentication and sharded clusters, see :ref:`sharding-security`. - .. toctree:: :titlesonly: :hidden: From 97377243a5766e249c1f4c6ab7c595278b127115 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Tue, 24 Aug 2021 14:54:19 +0200 Subject: [PATCH 034/109] DOCSP-18009: Refactor Security Users section --- source/core/authentication.txt | 4 +- source/core/localhost-exception.txt | 67 ++++++ source/core/security-users.txt | 181 +++++++--------- source/includes/access-create-user.rst | 7 +- .../includes/extracts-create-users-base.yaml | 10 +- source/includes/extracts-create-users.yaml | 4 +- source/includes/extracts-sessions.yaml | 7 +- source/includes/fact-authenticate.rst | 20 -- source/includes/intro-rbac.rst | 10 - ...eate-admin-then-enable-authentication.yaml | 200 +++++++++--------- .../steps-deploy-replica-set-with-auth.yaml | 5 + source/tutorial/authenticate-a-user.txt | 77 +++++++ source/tutorial/create-users.txt | 13 +- 13 files changed, 352 insertions(+), 253 deletions(-) create mode 100644 source/core/localhost-exception.txt delete mode 100644 source/includes/fact-authenticate.rst delete mode 100644 source/includes/intro-rbac.rst create mode 100644 source/tutorial/authenticate-a-user.txt diff --git a/source/core/authentication.txt b/source/core/authentication.txt index ce36e9da38c..10f882b8f12 100644 --- a/source/core/authentication.txt +++ b/source/core/authentication.txt @@ -30,7 +30,8 @@ Getting Started To get started using access control, follow these tutorials: - :ref:`enable-access-control` -- :ref:`add-new-user` +- :ref:`create-users` +- :ref:`authentication-auth-as-user` .. _available-authentication-mechanisms: @@ -71,3 +72,4 @@ for more information. /core/authentication-mechanisms /core/authentication-mechanisms-enterprise /core/security-internal-authentication + /core/localhost-exception diff --git a/source/core/localhost-exception.txt b/source/core/localhost-exception.txt new file mode 100644 index 00000000000..a34955dee50 --- /dev/null +++ b/source/core/localhost-exception.txt @@ -0,0 +1,67 @@ +.. _localhost-exception: + +=================== +Localhost Exception +=================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. important:: + + On a :binary:`~bin.mongod` instance, the localhost exception only + applies when there are **no users or roles** created in the MongoDB + instance. + +The localhost exception allows you to enable access control and then +create the first user or role in the system. After you enable access +control, connect to the localhost interface and create the first user in +the ``admin`` database. + +If you create a user first, the user must have privileges to create +other users. The :authrole:`userAdmin` or +:authrole:`userAdminAnyDatabase` role both confer the privilege to +create other users. + +.. warning:: + + Connections using the localhost exception have access to create + *only* the **first user or role**. + + Once you create any user or role, the localhost exception is + disabled. If you need to create a user and a role, you must create + the user first using one of the builtin :authrole:`userAdmin` or + :authrole:`userAdminAnyDatabase` roles. If you create a role first, + you won't be able to create a user. + +The ability to create a role first with the :method:`db.createRole()` +method is specifically for users authorizing with LDAP. See :ref:`LDAP +Authorization ` for more information. + +Localhost Exception for Sharded Clusters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. important:: + + - On a :binary:`~bin.mongos`, the localhost exception only applies + when there are no :ref:`sharded cluster users ` + or roles created. + - In a sharded cluster, the localhost exception applies to each shard + individually as well as to the cluster as a whole. + +Once you create a sharded cluster and add a :ref:`user administrator +` through the :binary:`~bin.mongos` instance, you +**must** still prevent unauthorized access to the individual shards. To +prevent unauthorized access to individual shards, follow one of the +following steps for each shard in your cluster: + +- :ref:`Create a user administrator ` on the shard's + primary. +- Disable the localhost exception at startup. To disable the localhost + exception, set the :parameter:`enableLocalhostAuthBypass` parameter to + ``0``. diff --git a/source/core/security-users.txt b/source/core/security-users.txt index b1ca89cf9cb..cea3991ac0c 100644 --- a/source/core/security-users.txt +++ b/source/core/security-users.txt @@ -10,90 +10,88 @@ Users .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol -To authenticate a client in MongoDB, you must add a corresponding user to -MongoDB. +To authenticate a client in MongoDB, you must add a corresponding user +to MongoDB. +User Management +--------------- -User Management Interface -------------------------- +You can add a user with the :method:`db.createUser()` method using +:binary:`~bin.mongosh`. The first user you create must have privileges +to create other users. The :authrole:`userAdmin` or +:authrole:`userAdminAnyDatabase` role both confer the privilege to +create other users. -To add a user, MongoDB provides the :method:`db.createUser()` method. -When adding a user, you can assign :doc:`roles ` to -the user in order to grant privileges. - -.. note:: +.. seealso:: - The first user created in the database should be a user administrator - who has the privileges to manage other users. See - :doc:`/tutorial/enable-authentication`. + :doc:`/tutorial/create-users` -You can also update existing users, such as to change password and grant -or revoke roles. For a full list of user management methods, see +You can grant a user privileges by assinging :doc:`roles +` to the user when you create the user. You can +also grant or revoke roles, as well as update passwords, by updating +existing users. For a full list of user management methods, see :ref:`user-management-methods`. +.. seealso:: + + :doc:`/tutorial/manage-users-and-roles` + A user is uniquely identified by the user's name and associated -authentication database. Starting in MongoDB 4.0.9, a users managed by -MongoDB are assigned a unique ``userId``. [#userid]_ +:ref:`authentication database `. MongoDB +associates a user with a unique ``userId`` upon creation in MongoDB. + +LDAP Managed Users +~~~~~~~~~~~~~~~~~~ + +:ref:`LDAP managed users ` created on an LDAP +server do not have an associated document in the :doc:`system.users +` collection, and therefore don't +have a :data:`~admin.system.users.userId` field associated with them. -.. seealso:: - :doc:`/tutorial/create-users` - .. _authentication-database: .. _user-authentication-database: Authentication Database ----------------------- -When adding a user, you create the user in a specific database. This -database is the authentication database for the user. - -A user can have privileges across different databases; that is, a user's -privileges are not limited to their authentication database. By assigning -to the user roles in other databases, a user created in one database can -have permissions to act on other databases. For more information on -roles, see :doc:`/core/authorization`. - -The user's name and authentication database serve as a unique identifier -for that user. [#userid]_ That is, if two users have the same name but are created -in different databases, they are two separate users. If you intend to -have a single user with permissions on multiple databases, create a -single user with roles in the applicable databases instead of creating -the user multiple times in different databases. +When you add a user, you create the user in a specific database. The +database you create the user in is the authentication database for the +user. -.. [#userid] +However, a user's privileges are not limited to their authentication +database. Therefore, a user can have privileges across different +databases. For more information on roles, see +:doc:`/core/authorization`. - Starting in version 4.0.9, MongoDB associates a user with a unique - ``userId`` upon creation in MongoDB. - - :ref:`LDAP managed users ` created on the LDAP server - do not have an associated document in the :doc:`system.users - ` collection, and hence, do not - have a :data:`~admin.system.users.userId` field associated with them. +A user's name and authentication database serve as a unique identifier +for that user. MongoDB associates a user with a unique ``userId`` upon +creation in MongoDB. However, :ref:`LDAP managed users ` +created on an LDAP server do not have an associated document in the +:doc:`system.users ` collection, and +therefore don't have a :data:`~admin.system.users.userId` field +associated with them. -.. _authentication-auth-as-user: - -Authenticate a User -------------------- - -.. include:: /includes/fact-authenticate.rst +If two users have the same name but are created in different databases, +they are two separate users. If you want to have a single user with +permissions on multiple databases, create a single user with a role for +each applicable database. Centralized User Data --------------------- For users created in MongoDB, MongoDB stores all user information, including :data:`name `, :data:`password -`, and the :data:`user's authentication +`, and the user's :data:`authentication database `, in the :doc:`system.users ` collection in the ``admin`` database. -Do not access this collection directly but instead use the :ref:`user -management commands `. - +Do not modify this collection directly. To manage users, use the +designated :ref:`user management commands `. .. _sharding-localhost: .. _sharding-security: @@ -101,9 +99,11 @@ management commands `. Sharded Cluster Users --------------------- -To create users for a sharded cluster, connect to the -:binary:`~bin.mongos` instance and add the users. Clients then -authenticate these users through the :binary:`~bin.mongos` instances. +To create users for a sharded cluster, connect to a +:binary:`~bin.mongos` instance and add the users. To authenticate as a +user created on a :binary:`~bin.mongos` instance, you must authenticate +through a :binary:`~bin.mongos` instance. + In sharded clusters, MongoDB stores user configuration data in the ``admin`` database of the :term:`config servers `. @@ -112,62 +112,33 @@ In sharded clusters, MongoDB stores user configuration data in the Shard Local Users ~~~~~~~~~~~~~~~~~ -However, some maintenance operations, such as :dbcommand:`cleanupOrphaned`, -:dbcommand:`compact`, :method:`rs.reconfig()`, require direct connections to -specific shards in a sharded cluster. To perform these operations, you must -connect directly to the shard and authenticate as a *shard local* -administrative user. - -To create a *shard local* administrative user, connect directly to the shard -and create the user. MongoDB stores *shard local* users in the ``admin`` -database of the shard itself. - -These *shard local* users are completely independent from the users added to -the sharded cluster via :binary:`~bin.mongos`. *Shard local* users are local to the -shard and are inaccessible by :binary:`~bin.mongos`. - -Direct connections to a shard should only be for shard-specific maintenance and -configuration. In general, clients should connect to the sharded cluster -through the :binary:`~bin.mongos`. - -.. _localhost-exception: - -Localhost Exception -------------------- - -The localhost exception allows you to enable access control and then -create the first user in the system. With the localhost exception, after -you enable access control, connect to the localhost interface and create -the first user in the ``admin`` database. The first user must have -privileges to create other users, such as a user with the -:authrole:`userAdmin` or :authrole:`userAdminAnyDatabase` role. -Connections using the localhost exception *only* have access to create -the first user on the ``admin`` database. - -.. versionchanged:: 3.4 - - MongoDB 3.4 extended the localhost exception to permit execution of the - :method:`db.createRole()` method. This method allows users authorizing via - LDAP to create a role inside of MongoDB that maps to a role defined - in LDAP. See :ref:`LDAP Authorization ` for more - information. +Some maintenance operations, such as :dbcommand:`cleanupOrphaned`, +:dbcommand:`compact`, or :method:`rs.reconfig()`, require direct +connections to specific shards in a sharded cluster. To perform these +operations, you must connect directly to the shard and authenticate as a +*shard local* administrative user. -The localhost exception applies only when there are no users created in the -MongoDB instance. +To create a *shard local* administrative user, connect directly to the +primary of the shard and create the user. For instructions on how to +create a shard local user administrator see the +:doc:`/tutorial/deploy-sharded-cluster-with-keyfile-access-control` +tutorial. -In the case of a sharded cluster, the localhost exception applies to each shard -individually as well as to the cluster as a whole. Once you create a sharded -cluster and add a user administrator through the :binary:`~bin.mongos` instance, -you must still prevent unauthorized access to the individual shards. Follow one -of the following steps for each shard in your cluster: +MongoDB stores *shard local* users in the ``admin`` database of the +shard itself. These *shard local* users are independent from +the users added to the sharded cluster through a :binary:`~bin.mongos`. +*Shard local* users are local to the shard and are inaccessible by +:binary:`~bin.mongos`. -- Create an administrative user, or +Direct connections to a shard should only be used for shard-specific +maintenance and configuration or for targeted analytics workloads. In +general, clients should connect to the sharded cluster through the +:binary:`~bin.mongos`. -- Disable the localhost exception at startup. To disable the localhost - exception, set the :parameter:`enableLocalhostAuthBypass` parameter to ``0``. .. toctree:: :titlesonly: :hidden: /tutorial/create-users + /tutorial/authenticate-a-user diff --git a/source/includes/access-create-user.rst b/source/includes/access-create-user.rst index b99dc1352bb..7e22b00aa66 100644 --- a/source/includes/access-create-user.rst +++ b/source/includes/access-create-user.rst @@ -6,7 +6,6 @@ :ref:`action ` on the role's database. The :authrole:`userAdmin` and -:authrole:`userAdminAnyDatabase` built-in roles -provide :authaction:`createUser` and -:authaction:`grantRole` actions on their respective :doc:`resources -`. +:authrole:`userAdminAnyDatabase` built-in roles provide +:authaction:`createUser` and :authaction:`grantRole` actions on their +respective :doc:`resources `. diff --git a/source/includes/extracts-create-users-base.yaml b/source/includes/extracts-create-users-base.yaml index 55df6eea5f0..d7df57c8f5b 100644 --- a/source/includes/extracts-create-users-base.yaml +++ b/source/includes/extracts-create-users-base.yaml @@ -1,10 +1,10 @@ ref: _create-user-intro content: | - Users that will authenticate to MongoDB using an external authentication - mechanism, such as {{mechanism}}, must be created in the ``$external`` database, - which allows :binary:`~bin.mongos` or :binary:`~bin.mongod` to consult an - external source for authentication. - + Users that authenticate to MongoDB using an external authentication + mechanism, such as {{mechanism}}, must be created in the ``$external`` + database, which allows :binary:`~bin.mongos` or :binary:`~bin.mongod` + to consult an external source for authentication. + .. include:: /includes/extracts/sessions-external-username-limit.rst ... \ No newline at end of file diff --git a/source/includes/extracts-create-users.yaml b/source/includes/extracts-create-users.yaml index a519296f8a2..08e9c11156f 100644 --- a/source/includes/extracts-create-users.yaml +++ b/source/includes/extracts-create-users.yaml @@ -2,7 +2,7 @@ ref: create-user-intro-kerberos inherit: ref: _create-user-intro file: extracts-create-users-base.yaml -replacement: +replacement: mechanism: "Kerberos" --- ref: create-user-intro-ldap @@ -18,4 +18,4 @@ inherit: file: extracts-create-users-base.yaml replacement: mechanism: "x.509 Client Certificate Authentication" -... +... diff --git a/source/includes/extracts-sessions.yaml b/source/includes/extracts-sessions.yaml index c5b7ec20130..e98bd15a55e 100644 --- a/source/includes/extracts-sessions.yaml +++ b/source/includes/extracts-sessions.yaml @@ -101,11 +101,10 @@ content: | ref: sessions-external-username-limit content: | - .. versionchanged:: 3.6.3 + To use :ref:`sessions` with ``$external`` authentication users + (Kerberos, LDAP, or x.509 users), the usernames cannot be greater + than 10k bytes. - To use sessions with ``$external`` authentication users (i.e. - Kerberos, LDAP, x.509 users), the usernames cannot be greater - than 10k bytes. --- ref: sessions-cursor-timeout content: | diff --git a/source/includes/fact-authenticate.rst b/source/includes/fact-authenticate.rst deleted file mode 100644 index 1cb3cf469f5..00000000000 --- a/source/includes/fact-authenticate.rst +++ /dev/null @@ -1,20 +0,0 @@ -To authenticate as a user, you must provide a username, password, and -the :ref:`authentication database ` -associated with that user. - -To authenticate using :binary:`~bin.mongosh`, either: - -- Use the :binary:`~bin.mongosh` command-line authentication options - (:option:`--username `, - :option:`--password `, and - :option:`--authenticationDatabase `) - when connecting to the :binary:`~bin.mongod` or - :binary:`~bin.mongos` instance, or - -- Connect first to the :binary:`~bin.mongod` or :binary:`~bin.mongos` - instance, and then run the :dbcommand:`authenticate` command or the - :method:`db.auth()` method against the :ref:`authentication database - `. - -For examples of authenticating using a MongoDB driver, see the -`driver documentation `__. diff --git a/source/includes/intro-rbac.rst b/source/includes/intro-rbac.rst deleted file mode 100644 index 59d30a68acd..00000000000 --- a/source/includes/intro-rbac.rst +++ /dev/null @@ -1,10 +0,0 @@ -MongoDB employs role-based access control (RBAC) to determine access -for users. A user is granted one or more :ref:`roles ` that -determine the user's access or privileges to MongoDB :ref:`resources -` and the :ref:`actions ` -that user can perform. A user should have only the minimal set of -privileges required to ensure a system of :term:`least privilege`. - -Each application and user of a MongoDB system should map to a distinct -user. This *access isolation* facilitates -access revocation and ongoing user maintenance. diff --git a/source/includes/steps-create-admin-then-enable-authentication.yaml b/source/includes/steps-create-admin-then-enable-authentication.yaml index a74e380c674..a3ca858308b 100644 --- a/source/includes/steps-create-admin-then-enable-authentication.yaml +++ b/source/includes/steps-create-admin-then-enable-authentication.yaml @@ -4,21 +4,21 @@ level: 4 ref: start-without-auth pre: | - Start a standalone :binary:`~bin.mongod` instance without access - control. + Start a standalone :binary:`~bin.mongod` instance without access + control. - Open a terminal and run the following command: + Open a terminal and run the following command: action: language: sh code: | mongod --port 27017 --dbpath /var/lib/mongodb post: | - The :binary:`~bin.mongod` instance in this tutorial uses - :option:`port 27017 ` and the ``/var/lib/mongodb`` - data directory. The tutorial assumes that the ``/var/lib/mongodb`` - directory exists and is the default :setting:`~storage.dbPath`. You - may specify a different data directory or port as needed. + The :binary:`~bin.mongod` instance in this tutorial uses + :option:`port 27017 ` and the ``/var/lib/mongodb`` + data directory. The tutorial assumes that the ``/var/lib/mongodb`` + directory exists and is the default :setting:`~storage.dbPath`. You + may specify a different data directory or port as needed. --- stepnum: 2 @@ -27,16 +27,17 @@ level: 4 ref: connect pre: | - Open a new terminal and connect to the database deployment with - :binary:`~bin.mongosh`: + Open a new terminal and connect to the database deployment with + :binary:`~bin.mongosh`: action: language: sh code: | mongosh --port 27017 post: | - If you are connecting to an existing deployment, specify additional - command line options, such as ``--host``, as needed to connect. + If you are connecting to a different deployment, specify additional + command line options, such as :option:`--host `, as + needed to connect. --- stepnum: 3 title: Create the user administrator @@ -44,31 +45,23 @@ level: 4 ref: create-user-admin pre: | - .. _create-user-admin: + .. _create-user-admin: - .. important:: Localhost Exception + .. important:: Localhost Exception - You can create the user administrator either before or after - enabling access control. If you enable access control before - creating any user, MongoDB provides a :ref:`localhost exception - ` which allows you to create a user - administrator in the ``admin`` database. Once created, you must - authenticate as the user administrator to create additional users. + You can create the user administrator either before or after + enabling access control. If you enable access control before + creating any user, MongoDB provides a :ref:`localhost exception + ` which allows you to create a user + administrator in the ``admin`` database. Once created, you must + authenticate as the user administrator to create additional users. - The :authrole:`userAdminAnyDatabase` role allows this user to: + Using :binary:`~bin.mongosh`: - - create users, - - grant or revoke roles from users, - - and create or modify customs roles. - - You can assign your user additional :ref:`built-in roles - ` or :ref:`user-defined roles ` - as needed. - - Using :binary:`~bin.mongosh`, switch to the ``admin`` database and - add the user ``myUserAdmin`` in the ``admin`` database with the - :authrole:`userAdminAnyDatabase` role and the - :authrole:`readWriteAnyDatabase` role: + 1. switch to the ``admin`` database + 2. add the ``myUserAdmin`` user with the + :authrole:`userAdminAnyDatabase` and + :authrole:`readWriteAnyDatabase` roles": action: language: javascript @@ -87,16 +80,26 @@ action: ) post: | - .. tip:: + .. tip:: + + .. include:: /includes/extracts/mongosh-password-prompt.rst + + The :authrole:`userAdminAnyDatabase` role allows this user to: + + - create users + - grant or revoke roles from users + - create or modify customs roles - .. include:: /includes/extracts/mongosh-password-prompt.rst + You can assign your user additional :ref:`built-in roles + ` or :ref:`user-defined roles ` + as needed. - The database where you create the user (in this example, ``admin``) - is the user's :ref:`authentication database - `. Although the user needs to - authenticate to this database, the user can have roles in other - databases. The user's authentication database doesn't limit the - user's privileges. + The database where you create the user, in this example ``admin``, + is the user's :ref:`authentication database + `. Although the user needs to + authenticate to this database, the user can have roles in other + databases. The user's authentication database doesn't limit the + user's privileges. --- title: Re-start the MongoDB instance with access control @@ -105,45 +108,45 @@ stepnum: 4 ref: restart-with-auth content: | - Shut down the :binary:`~bin.mongod` instance. Using - :binary:`~bin.mongosh`, issue the following command: + Shut down the :binary:`~bin.mongod` instance. Using + :binary:`~bin.mongosh`, issue the following command: - .. code-block:: javascript + .. code-block:: javascript - db.adminCommand( { shutdown: 1 } ) + db.adminCommand( { shutdown: 1 } ) - Exit :binary:`~bin.mongosh`. + Exit :binary:`~bin.mongosh`. - Start the :binary:`~bin.mongod` with access control enabled. + Start the :binary:`~bin.mongod` with access control enabled. - - If you start the :binary:`~bin.mongod` from the command line, add - the :option:`--auth ` command line option: + - If you start the :binary:`~bin.mongod` from the command line, add + the :option:`--auth ` command line option: - .. code-block:: bash + .. code-block:: bash - mongod --auth --port 27017 --dbpath /var/lib/mongodb + mongod --auth --port 27017 --dbpath /var/lib/mongodb - - If you start the :binary:`~bin.mongod` using a - :ref:`configuration file `, add the - :setting:`security.authorization` configuration file setting: + - If you start the :binary:`~bin.mongod` using a + :ref:`configuration file `, add the + :setting:`security.authorization` configuration file setting: - .. code-block:: bash + .. code-block:: bash - security: - authorization: enabled + security: + authorization: enabled - Clients that connect to this instance must now authenticate - themselves and can only perform actions as determined by their - assigned roles. + Clients that connect to this instance must now authenticate + themselves and can only perform actions as determined by their + assigned roles. - .. important:: Localhost Exception + .. important:: Localhost Exception - You can create users either before or after enabling access - control. If you enable access control before creating any user, - MongoDB provides a :ref:`localhost exception - ` which allows you to create a user - administrator in the ``admin`` database. Once created, you must - authenticate as the user administrator to create additional users. + You can create users either before or after enabling access + control. If you enable access control before creating any user, + MongoDB provides a :ref:`localhost exception + ` which allows you to create a user + administrator in the ``admin`` database. Once created, you must + authenticate as the user administrator to create additional users. --- title: Connect and authenticate as the user administrator @@ -151,50 +154,49 @@ level: 4 stepnum: 5 ref: auth-as-admin content: | - Using :binary:`~bin.mongosh`, you can: + Using :binary:`~bin.mongosh`, you can: - .. tabs:: + .. tabs:: - tabs: - - id: cmdline - name: Authenticate during Connection - content: | - Start :binary:`~bin.mongosh` with the :option:`-u - \ `, :option:`-p `, and the - :option:`--authenticationDatabase \ ` command line options: + tabs: + - id: cmdline + name: Authenticate during Connection + content: | + Start :binary:`~bin.mongosh` with the :option:`-u + \ `, :option:`-p `, and the + :option:`--authenticationDatabase \ ` command line options: - .. code-block:: bash + .. code-block:: bash - mongosh --port 27017 --authenticationDatabase \ - "admin" -u "myUserAdmin" -p + mongosh --port 27017 --authenticationDatabase \ + "admin" -u "myUserAdmin" -p - Enter your password when prompted. + Enter your password when prompted. - - id: authafter - name: Authenticate after Connection - content: | + - id: authafter + name: Authenticate after Connection + content: | - Using :binary:`~bin.mongosh`, connect to your database - deployment: + Using :binary:`~bin.mongosh`, connect to your database + deployment: - .. code-block:: bash + .. code-block:: bash - mongosh --port 27017 + mongosh --port 27017 - In :binary:`~bin.mongosh`, switch to the - authentication database (in this case, ``admin``), and - use the :method:`db.auth(\, \) - ` method to authenticate: + In :binary:`~bin.mongosh`, switch to the + authentication database (in this case, ``admin``), and + use the :method:`db.auth(\, \) + ` method to authenticate: - .. code-block:: javascript + .. code-block:: javascript - use admin - db.auth("myUserAdmin", passwordPrompt()) // or cleartext password + use admin + db.auth("myUserAdmin", passwordPrompt()) // or cleartext password - .. tip:: + .. tip:: - .. include:: /includes/extracts/mongosh-password-prompt.rst + .. include:: /includes/extracts/mongosh-password-prompt.rst - Enter the password when prompted. -... + Enter the password when prompted. diff --git a/source/includes/steps-deploy-replica-set-with-auth.yaml b/source/includes/steps-deploy-replica-set-with-auth.yaml index 5cae223df0d..9283414a010 100644 --- a/source/includes/steps-deploy-replica-set-with-auth.yaml +++ b/source/includes/steps-deploy-replica-set-with-auth.yaml @@ -3,7 +3,9 @@ title: Create a keyfile. ref: deploy-repset-generate-keyfile level: 4 pre: | + .. include:: /includes/extracts/keyfile-intro-replica-set.rst + action: language: sh code: | @@ -140,7 +142,9 @@ title: Create the user administrator. level: 4 ref: deploy-repset-user-admin pre: | + .. important:: + After you create the first user, the :ref:`localhost exception ` is no longer available. @@ -164,6 +168,7 @@ pre: | :authrole:`userAdminAnyDatabase` role on the ``admin`` database. .. important:: + Passwords should be random, long, and complex to ensure system security and to prevent or delay malicious access. diff --git a/source/tutorial/authenticate-a-user.txt b/source/tutorial/authenticate-a-user.txt new file mode 100644 index 00000000000..e613ac4e47d --- /dev/null +++ b/source/tutorial/authenticate-a-user.txt @@ -0,0 +1,77 @@ +.. _authentication-auth-as-user: + +=================== +Authenticate a User +=================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +To authenticate as a user, you must provide a username, password, and +the :ref:`authentication database ` +associated with that user. + +.. important:: + + It is not possible to switch between users in the same + :binary:`~bin.mongosh` session. Authenticating as a different user + means the session has the privileges of **both** authenticated + users. To switch between users exit and relaunch + :binary:`~bin.mongosh`. + +Using :binary:`~bin.mongosh`, you can: + +.. tabs:: + + tabs: + - id: cmdline + name: Authenticate during Connection + content: | + Start :binary:`~bin.mongosh` with the :option:`-u + \ `, :option:`-p `, and the + :option:`--authenticationDatabase \ ` command line options: + + .. code-block:: bash + + mongosh --port 27017 --authenticationDatabase \ + "admin" -u "myUserAdmin" -p + + Enter your password when prompted. + + - id: authafter + name: Authenticate after Connection + content: | + + Using :binary:`~bin.mongosh`, connect to the + :binary:`~bin.mongod` or :binary:`~bin.mongos` instance: + + .. code-block:: bash + + mongosh --port 27017 + + In :binary:`~bin.mongosh`, switch to the + authentication database (in this case, ``admin``), and + use the :method:`db.auth(\, \) + ` method or the :dbcommand:`authenticate` + command to authenticate against the :ref:`authentication + database `: + + .. code-block:: javascript + + use admin + db.auth("myUserAdmin", passwordPrompt()) // or cleartext password + + .. tip:: + + .. include:: /includes/extracts/mongosh-password-prompt.rst + + Enter the password when prompted. + +For examples using a MongoDB driver, see the +`driver documentation `__. diff --git a/source/tutorial/create-users.txt b/source/tutorial/create-users.txt index 8c819a7c855..044f97611dc 100644 --- a/source/tutorial/create-users.txt +++ b/source/tutorial/create-users.txt @@ -12,9 +12,16 @@ Create a User :depth: 3 :class: singlecol -With access control enabled, users are required to identify themselves -and can only perform actions that adhere to the permissions granted by -the :ref:`roles ` assigned to their user. +With access control enabled, users are required to identify themselves. +You have to grant a user one or more :ref:`roles `. A role grants +a user :ref:`privileges ` to perform certain :ref:`actions +` on MongoDB :ref:`resources +`. + +Each application and user of a MongoDB system should map to a distinct +user. This principle of *access isolation* facilitates access revocation +and ongoing user maintenance. To ensure a system of :term:`least +privilege`, only grant the minimal set of privileges required to a user. .. _add-user-prereq: From b8d2ce2b25384a8347aaf428740e9ed2bf1fee85 Mon Sep 17 00:00:00 2001 From: corryroot <72401712+corryroot@users.noreply.github.com> Date: Thu, 9 Sep 2021 13:15:00 -0400 Subject: [PATCH 035/109] (DOCSP-18602): Backport DOCSP-17931 to v5.0. (#5815) * (DOCSP-17931): Updated link. * Update source/reference/connection-string.txt Co-authored-by: jdestefano-mongo --- source/reference/connection-string.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/reference/connection-string.txt b/source/reference/connection-string.txt index a1952d08277..86be4d2d21f 100644 --- a/source/reference/connection-string.txt +++ b/source/reference/connection-string.txt @@ -130,8 +130,8 @@ Examples your deployment when you click the :atlas:`Connect ` button in the Atlas UI. To register a new Atlas account, start at the - :mdbacct:`MongoDB Atlas registration page - `. To learn more, see + `MongoDB Atlas registration page + `__. To learn more, see :atlas:`Get Started with Atlas `. Your Atlas connection string might resemble the following From 120f781ee894a50094f6e0990f86f0cb5071fd7e Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Mon, 13 Sep 2021 14:39:14 -0400 Subject: [PATCH 036/109] (DOCS-14786): Add release date for 4.2.16 --- source/release-notes/4.2.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/release-notes/4.2.txt b/source/release-notes/4.2.txt index 19cc51c406e..7c19d02a293 100644 --- a/source/release-notes/4.2.txt +++ b/source/release-notes/4.2.txt @@ -15,8 +15,8 @@ Minor Releases .. _4.2.16-release-notes: -4.2.16 - Upcoming -~~~~~~~~~~~~~~~~~~ +4.2.16 - Sep 13, 2021 +~~~~~~~~~~~~~~~~~~~~~ Issues fixed in 4.2.16: From 73250487b1d0a6ff5a506bdd825e3f4c97992a9b Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Tue, 14 Sep 2021 13:59:55 -0400 Subject: [PATCH 037/109] (DOCS-14785): Add release date for 4.0.27 --- source/release-notes/4.0.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/release-notes/4.0.txt b/source/release-notes/4.0.txt index 7edb04e8b87..dbcec7bb35a 100644 --- a/source/release-notes/4.0.txt +++ b/source/release-notes/4.0.txt @@ -15,8 +15,8 @@ Minor Releases .. _4.0.27-release-notes: -4.0.27 - Upcoming -~~~~~~~~~~~~~~~~~ +4.0.27 - Sep 13, 2021 +~~~~~~~~~~~~~~~~~~~~~ Issues fixed: From 65407cb55ae2f72136bfa12c7fea45427c7ccf57 Mon Sep 17 00:00:00 2001 From: Dave Cuthbert Date: Mon, 13 Sep 2021 14:03:25 -0400 Subject: [PATCH 038/109] DOCS-14790 update type for replSetResizeOplog size param --- .../reference/command/replSetResizeOplog.txt | 24 +++++++++++-------- source/release-notes/5.0-compatibility.txt | 3 +++ source/tutorial/change-oplog-size.txt | 9 +++---- 3 files changed, 22 insertions(+), 14 deletions(-) diff --git a/source/reference/command/replSetResizeOplog.txt b/source/reference/command/replSetResizeOplog.txt index 0f0cde4efa1..a5d32474eaa 100644 --- a/source/reference/command/replSetResizeOplog.txt +++ b/source/reference/command/replSetResizeOplog.txt @@ -15,17 +15,16 @@ Definition .. dbcommand:: replSetResizeOplog - .. versionadded:: 3.6 - - Use the :dbcommand:`replSetResizeOplog` administrative command to - change the size of a replica set member's oplog. [#oplog]_ - - .. versionadded:: 4.4 :dbcommand:`replSetResizeOplog` also supports specifying the minimum number of hours to preserve an oplog entry. + .. versionchanged:: 5.0 + + To set the ``replSetOplog`` size in :binary:`~bin.mongosh`, use + the ``Double()`` constructor. + :dbcommand:`replSetResizeOplog` enables you to resize the oplog or its minimum retention period dynamically without restarting the :binary:`~bin.mongod` process. @@ -72,6 +71,10 @@ Definition - The maximum size you can specify is 1 petabytes. + - Explicitly cast the ``size`` as a double in + :binary:`~bin.mongosh` with ``Double()``. See + :ref:`oplog-ex-change-size`. + * - :ref:`minRetentionHours ` - double @@ -119,6 +122,8 @@ You can only use :dbcommand:`replSetResizeOplog` on See the :ref:`tutorial-change-oplog-size` tutorial for a procedure on using :dbcommand:`replSetResizeOplog` command to resize the oplog. +.. include:: /includes/fact-oplog-size.rst + Starting in MongoDB 4.0, MongoDB forbids dropping the ``local.oplog.rs`` collection. For more information on this restriction, see :ref:`oplog-coll-behavior`. @@ -227,6 +232,8 @@ For more information on locking in MongoDB, see :doc:`/faq/concurrency`. Examples -------- +.. _oplog-ex-change-size: + Change the Maximum Oplog Size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -249,7 +256,7 @@ oplog size of this member to 16384 megabytes: .. code-block:: javascript - db.adminCommand({ "replSetResizeOplog": 1, size: 16384}) + db.adminCommand({ "replSetResizeOplog": 1, size: Double(16384)}) To verify the new oplog size, rerun the :method:`db.collection.stats()` method: @@ -269,9 +276,6 @@ The above command returns: may cause replica members syncing with that node to become stale. To resync those members, see :doc:`/tutorial/resync-replica-set-member`. -.. [#oplog] - - .. include:: /includes/fact-oplog-size.rst Change the Minimum Oplog Retention Period ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt index 41d032dca77..c7d9ec95b92 100644 --- a/source/release-notes/5.0-compatibility.txt +++ b/source/release-notes/5.0-compatibility.txt @@ -382,6 +382,9 @@ Starting in MongoDB 5.0: default write concern. To set the global default write concern, use the :dbcommand:`setDefaultRWConcern` command. +- To set the ``replSetOplog`` size in :binary:`~bin.mongosh`, use the + ``Double()`` constructor with the :dbcommand:`replSetResizeOplog` + command. Deprecations ~~~~~~~~~~~~ diff --git a/source/tutorial/change-oplog-size.txt b/source/tutorial/change-oplog-size.txt index 36523f67e50..cd480a95a65 100644 --- a/source/tutorial/change-oplog-size.txt +++ b/source/tutorial/change-oplog-size.txt @@ -69,16 +69,17 @@ The ``maxSize`` field displays the collection size in bytes. C. Change the oplog size of the replica set member -------------------------------------------------- -To resize the oplog, run the :dbcommand:`replSetResizeOplog` command, -passing the desired size in megabytes as the ``size`` parameter. The -specified size must be greater than ``990``, or 990 megabytes. +Resize the oplog with the :dbcommand:`replSetResizeOplog` command. The +``size`` is a double and must be greater than ``990`` megabytes. To +explicitly cast the oplog ``size`` in :binary:`~bin.mongosh`, use the +``Double()`` constructor. The following operation changes the oplog size of the replica set member to 16 gigabytes, or 16000 megabytes. .. code-block:: javascript - db.adminCommand({replSetResizeOplog: 1, size: 16000}) + db.adminCommand({replSetResizeOplog: 1, size: Double(16000)}) .. [#oplog] From fad920c6ba47365b0b2b2c63ac04d6fd39b9851d Mon Sep 17 00:00:00 2001 From: Dave Cuthbert Date: Tue, 7 Sep 2021 14:48:39 -0400 Subject: [PATCH 039/109] DOCS-14757 virtual box not supported with hyper-v --- source/includes/fact-virtualbox-not-supported.rst | 7 +++++++ .../install-mongodb-enterprise-on-windows-unattended.txt | 5 +++++ source/tutorial/install-mongodb-enterprise-on-windows.txt | 5 +++++ source/tutorial/install-mongodb-on-windows-unattended.txt | 5 +++++ source/tutorial/install-mongodb-on-windows.txt | 5 +++++ 5 files changed, 27 insertions(+) create mode 100644 source/includes/fact-virtualbox-not-supported.rst diff --git a/source/includes/fact-virtualbox-not-supported.rst b/source/includes/fact-virtualbox-not-supported.rst new file mode 100644 index 00000000000..f68bf362ba1 --- /dev/null +++ b/source/includes/fact-virtualbox-not-supported.rst @@ -0,0 +1,7 @@ +Oracle offers `experimental support +`__ +for VirtualBox on Windows hosts where Hyper-V is running. However, +Microsoft does not support `VirtualBox on Hyper-V +`__. + +Disable Hyper-V if you want to install MongoDB on Windows using VirtualBox. diff --git a/source/tutorial/install-mongodb-enterprise-on-windows-unattended.txt b/source/tutorial/install-mongodb-enterprise-on-windows-unattended.txt index bc687f45edc..eba04e243a1 100644 --- a/source/tutorial/install-mongodb-enterprise-on-windows-unattended.txt +++ b/source/tutorial/install-mongodb-enterprise-on-windows-unattended.txt @@ -57,6 +57,11 @@ Platform Support .. include:: /includes/fact-platform-support-enterprise-windows.rst +Virtualization +~~~~~~~~~~~~~~ + +.. include:: /includes/fact-virtualbox-not-supported.rst + Production Notes ~~~~~~~~~~~~~~~~ diff --git a/source/tutorial/install-mongodb-enterprise-on-windows.txt b/source/tutorial/install-mongodb-enterprise-on-windows.txt index 2c8a802a829..8e707273438 100644 --- a/source/tutorial/install-mongodb-enterprise-on-windows.txt +++ b/source/tutorial/install-mongodb-enterprise-on-windows.txt @@ -57,6 +57,11 @@ Platform Support .. include:: /includes/fact-platform-support-enterprise-windows.rst +Virtualization +~~~~~~~~~~~~~~ + +.. include:: /includes/fact-virtualbox-not-supported.rst + Production Notes ~~~~~~~~~~~~~~~~ diff --git a/source/tutorial/install-mongodb-on-windows-unattended.txt b/source/tutorial/install-mongodb-on-windows-unattended.txt index 46949679585..969395316a3 100644 --- a/source/tutorial/install-mongodb-on-windows-unattended.txt +++ b/source/tutorial/install-mongodb-on-windows-unattended.txt @@ -52,6 +52,11 @@ Platform Support .. include:: /includes/fact-platform-support-windows.rst +Virtualization +~~~~~~~~~~~~~~ + +.. include:: /includes/fact-virtualbox-not-supported.rst + Production Notes ~~~~~~~~~~~~~~~~ diff --git a/source/tutorial/install-mongodb-on-windows.txt b/source/tutorial/install-mongodb-on-windows.txt index caa736bef3c..f896b2f934c 100644 --- a/source/tutorial/install-mongodb-on-windows.txt +++ b/source/tutorial/install-mongodb-on-windows.txt @@ -52,6 +52,11 @@ Platform Support .. include:: /includes/fact-platform-support-windows.rst +Virtualization +~~~~~~~~~~~~~~ + +.. include:: /includes/fact-virtualbox-not-supported.rst + Production Notes ~~~~~~~~~~~~~~~~ From de5e63698bdcba64ffe884a6326af9a9fbf5fb4a Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Tue, 14 Sep 2021 12:00:11 -0400 Subject: [PATCH 040/109] DOCS-14281 add release notes and update partial index restrictions --- source/core/index-partial.txt | 8 +------- source/includes/fact-5.0-multiple-partial-index.rst | 10 ++++++++++ .../reference/method/db.collection.createIndexes.txt | 8 ++++++-- source/release-notes/5.0.txt | 5 +++++ 4 files changed, 22 insertions(+), 9 deletions(-) create mode 100644 source/includes/fact-5.0-multiple-partial-index.rst diff --git a/source/core/index-partial.txt b/source/core/index-partial.txt index 5805f64981a..eb3c8346160 100644 --- a/source/core/index-partial.txt +++ b/source/core/index-partial.txt @@ -162,17 +162,11 @@ by the filter expression Restrictions ------------ -In MongoDB, you cannot create multiple versions of an index that -differ only in the options. As such, you cannot create multiple -partial indexes that differ only by the filter expression. +.. include:: /includes/fact-5.0-multiple-partial-index.rst You cannot specify both the ``partialFilterExpression`` option and the ``sparse`` option. -MongoDB 3.0 or earlier do not support partial indexes. To use partial -indexes, you must use MongoDB version 3.2 or higher. For sharded -clusters or replica sets, all nodes must be version 3.2 or higher. - ``_id`` indexes cannot be partial indexes. Shard key indexes cannot be partial indexes. diff --git a/source/includes/fact-5.0-multiple-partial-index.rst b/source/includes/fact-5.0-multiple-partial-index.rst new file mode 100644 index 00000000000..9f44b95f3ab --- /dev/null +++ b/source/includes/fact-5.0-multiple-partial-index.rst @@ -0,0 +1,10 @@ +Starting in MongoDB 5.0, multiple +:doc:`partial indexes ` +can be created using the same :ref:`key pattern` as long +as the :ref:`partialFilterExpression ` +fields do not express equivalent filters. + +In earlier versions of MongoDB, creating multiple +:doc:`partial indexes` is not allowed when +using the same key pattern with different +:ref:`partialFilterExpressions `. diff --git a/source/reference/method/db.collection.createIndexes.txt b/source/reference/method/db.collection.createIndexes.txt index 151f400f228..b5db7454f07 100644 --- a/source/reference/method/db.collection.createIndexes.txt +++ b/source/reference/method/db.collection.createIndexes.txt @@ -38,7 +38,9 @@ Definition - document - - An array containing index specification documents. Each document + - .. _key_patterns: + + An array containing index specification documents. Each document contains field and value pairs where the field is the index key and the value describes the type of index for that field. For an ascending index on a field, specify a value of ``1``; for @@ -270,7 +272,9 @@ otherwise specified: - document - - Optional. If specified, the indexes only reference documents that match the + - .. _partialFilterExpression: + + Optional. If specified, the indexes only reference documents that match the filter expression. See :doc:`/core/index-partial` for more information. diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 110a9326f95..4680a33a90f 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -293,6 +293,11 @@ truncations. Indexes ------- +Partial Indexes Behavior Change +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/fact-5.0-multiple-partial-index.rst + Cannot Drop ``Ready`` Indexes During In-Progress Index Builds ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From a6bd836cce0975df3ea8b41350e09f3792bb6f4d Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Thu, 19 Aug 2021 13:57:49 -0400 Subject: [PATCH 041/109] (DOCSP-17930): Update getting started page for Atlas --- source/reference/operator/query.txt | 2 + source/tutorial/getting-started.txt | 258 +++++++++++++++++----------- 2 files changed, 161 insertions(+), 99 deletions(-) diff --git a/source/reference/operator/query.txt b/source/reference/operator/query.txt index f718ac42005..6e2ba2ea8bc 100644 --- a/source/reference/operator/query.txt +++ b/source/reference/operator/query.txt @@ -1,3 +1,5 @@ +.. _query-projection-operators-top: + ============================== Query and Projection Operators ============================== diff --git a/source/tutorial/getting-started.txt b/source/tutorial/getting-started.txt index 0f7ae59c669..6992d11af0d 100644 --- a/source/tutorial/getting-started.txt +++ b/source/tutorial/getting-started.txt @@ -6,16 +6,21 @@ Getting Started .. default-domain:: mongodb - -The following page provides various examples for querying in the -MongoDB Shell. For examples using MongoDB drivers, refer to the links -in the :ref:`gs-additional-examples` section. +This tutorial walks you through inserting test data into a MongoDB +database and querying that data using the documentation's embedded +web shell. You do not need to deploy or install MongoDB to complete +this tutorial. + +The examples in this tutorial use a subset of the +:atlas:`Sample Mflix Dataset `, which is +part of the sample data included in MongoDB's cloud-hosted service, +`MongoDB Atlas `__. +Atlas requires no installation overhead and offers a free tier to get +started. After completing this tutorial, you can use Atlas to +explore additional sample data or host your own data. .. _mongo-web-shell: -Examples --------- - .. include:: /includes/fact-mws.rst Click inside the shell to connect. Once connected, you can run the @@ -23,7 +28,7 @@ examples in the shell above. .. tabs:: - .. tab:: Step 1 + .. tab:: 1. Switch Database :tabid: example-1 Switch Database @@ -60,7 +65,7 @@ examples in the shell above. To create a collection in the database, see the next tab. - .. tab:: Step 2 + .. tab:: 2. Insert :tabid: example-2 Populate a Collection (Insert) @@ -74,21 +79,75 @@ examples in the shell above. The following example uses the :method:`db.collection.insertMany()` method to insert new - :doc:`documents ` into the ``inventory`` + :doc:`documents ` into the ``movies`` collection. You can copy and paste the example into the :ref:`shell ` above. .. code-block:: javascript - db.inventory.insertMany([ - { item: "journal", qty: 25, status: "A", size: { h: 14, w: 21, uom: "cm" }, tags: [ "blank", "red" ] }, - { item: "notebook", qty: 50, status: "A", size: { h: 8.5, w: 11, uom: "in" }, tags: [ "red", "blank" ] }, - { item: "paper", qty: 10, status: "D", size: { h: 8.5, w: 11, uom: "in" }, tags: [ "red", "blank", "plain" ] }, - { item: "planner", qty: 0, status: "D", size: { h: 22.85, w: 30, uom: "cm" }, tags: [ "blank", "red" ] }, - { item: "postcard", qty: 45, status: "A", size: { h: 10, w: 15.25, uom: "cm" }, tags: [ "blue" ] } - ]); - - // MongoDB adds an _id field with an ObjectId value if the field is not present in the document + db.movies.insertMany([ + { + title: 'Titanic', + year: 1997, + genres: [ 'Drama', 'Romance' ], + rated: 'PG-13', + languages: [ 'English', 'French', 'German', 'Swedish', 'Italian', 'Russian' ], + released: ISODate("1997-12-19T00:00:00.000Z"), + awards: { + wins: 127, + nominations: 63, + text: 'Won 11 Oscars. Another 116 wins & 63 nominations.' + }, + cast: [ 'Leonardo DiCaprio', 'Kate Winslet', 'Billy Zane', 'Kathy Bates' ], + directors: [ 'James Cameron' ] + }, + { + title: 'The Dark Knight', + year: 2008, + genres: [ 'Action', 'Crime', 'Drama' ], + rated: 'PG-13', + languages: [ 'English', 'Mandarin' ], + released: ISODate("2008-07-18T00:00:00.000Z"), + awards: { + wins: 144, + nominations: 106, + text: 'Won 2 Oscars. Another 142 wins & 106 nominations.' + }, + cast: [ 'Christian Bale', 'Heath Ledger', 'Aaron Eckhart', 'Michael Caine' ], + directors: [ 'Christopher Nolan' ] + }, + { + title: 'Spirited Away', + year: 2001, + genres: [ 'Animation', 'Adventure', 'Family' ], + rated: 'PG', + languages: [ 'Japanese' ], + released: ISODate("2003-03-28T00:00:00.000Z"), + awards: { + wins: 52, + nominations: 22, + text: 'Won 1 Oscar. Another 51 wins & 22 nominations.' + }, + cast: [ 'Rumi Hiiragi', 'Miyu Irino', 'Mari Natsuki', 'Takashi Naitè' ], + directors: [ 'Hayao Miyazaki' ] + }, + { + title: 'Casablanca', + genres: [ 'Drama', 'Romance', 'War' ], + rated: 'PG', + cast: [ 'Humphrey Bogart', 'Ingrid Bergman', 'Paul Henreid', 'Claude Rains' ], + languages: [ 'English', 'French', 'German', 'Italian' ], + released: ISODate("1943-01-23T00:00:00.000Z"), + directors: [ 'Michael Curtiz' ], + awards: { + wins: 9, + nominations: 6, + text: 'Won 3 Oscars. Another 6 wins & 6 nominations.' + }, + lastupdated: '2015-09-04 00:22:54.600000000', + year: 1942 + } + ]) The operation returns a document that contains the acknowledgement indicator and an array that contains the @@ -97,7 +156,7 @@ examples in the shell above. To verify the insert, you can query the collection (See the next tab). - .. tab:: Step 3 + .. tab:: 3. Find All :tabid: example-3 Select All Documents @@ -109,105 +168,62 @@ examples in the shell above. filter document ` to the method. In the :ref:`shell `, copy and paste the - following to return all documents in the ``inventory`` + following to return all documents in the ``movies`` collection. .. code-block:: javascript - db.inventory.find({}) - - To format the results, append the ``.pretty()`` to the - ``find`` operation: - - .. code-block:: javascript - - db.inventory.find({}).pretty() - - .. note:: + db.movies.find( { } ) - The example assumes that you have populated the - ``inventory`` collection from the previous step. - - .. tab:: Step 4 + .. tab:: 4. Filter Data :tabid: example-4 - Specify Equality Matches - ~~~~~~~~~~~~~~~~~~~~~~~~ + Filter Data with Comparison Operators + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - For an equality match (i.e. ```` equals ````), + For an equality match (```` equals ````), specify ``: `` in the :ref:`query filter document ` and pass to the :method:`db.collection.find()` method. - .. note:: - - The examples assume that you have populated the - ``inventory`` collection. - - - In the :ref:`shell `, copy and paste the - following to return documents where ``status`` field equals - ``"D"``: + - In the :ref:`shell `, run the following + query to find movies that were directed by + ``Christopher Nolan``: .. code-block:: javascript - db.inventory.find( { status: "D" } ); + db.movies.find( { "directors": "Christopher Nolan" } ); - - In the :ref:`shell `, copy and paste the - following to return document where ``qty`` field equals - ``0``: + You can use :ref:`comparison operators ` + to perform more advanced queries: - .. code-block:: javascript - - db.inventory.find( { qty: 0 } ); - - - In the :ref:`shell `, copy and paste the - following to return document where ``qty`` field equals - ``0`` and ``status`` field equals ``"D"``: + - Run the following query to return movies that were released + before the year ``2000``: .. code-block:: javascript - db.inventory.find( { qty: 0, status: "D" } ); + db.movies.find( { "released": { $lt: ISODate("2000-01-01") } } ); - - In the :ref:`shell `, copy and paste the - following to return document where the ``uom`` field, nested - inside the size document, equals ``"in"``: + - Run the following query to return movies that won more than + ``100`` awards: .. code-block:: javascript - db.inventory.find( { "size.uom": "in" } ) + db.movies.find( { "awards.wins": { $gt: 100 } } ); - - In the :ref:`shell `, copy and paste the - following to return document where the ``size`` field equals - the document ``{ h: 14, w: 21, uom: "cm" }``: + - Run the following query to return movies where the + ``languages`` array contains *either* ``Japanese`` or + ``Mandarin``: .. code-block:: javascript - db.inventory.find( { size: { h: 14, w: 21, uom: "cm" } } ) - - Equality matches on the embedded document require an exact - match, including the field order. + db.movies.find( { "languages": { $in: [ "Japanese", "Mandarin" ] } } ) + + .. seealso:: - - In the :ref:`shell `, copy and paste the - following to return documents where the ``tags`` array - contains ``"red"`` as one of its elements: + :ref:`query-projection-operators-top` - .. code-block:: javascript - - db.inventory.find( { tags: "red" } ) - - If the ``tags`` field is a string instead of an array, then - the query is just an equality match. - - - In the :ref:`shell `, copy and paste the - following to return documents where the ``tags`` field - matches the specified array exactly, including the order: - - .. code-block:: javascript - - db.inventory.find( { tags: [ "red", "blank" ] } ) - - - .. tab:: Step 5 + .. tab:: 5. Project Fields :tabid: example-5 Specify Fields to Return (Projection) @@ -222,24 +238,68 @@ examples in the shell above. - ``: 0`` to exclude a field in the returned documents - In the :ref:`shell `, copy and paste the - following to return the ``_id``, ``item``, and the ``status`` - fields from all documents in the ``inventory`` collection: + In the :ref:`shell `, run the following query to + return the ``id``, ``title``, ``directors``, and ``year`` fields + from all documents in the ``movies`` collection: .. code-block:: javascript - db.inventory.find( { }, { item: 1, status: 1 } ); + db.movies.find( { }, { "title": 1, "directors": 1, "year": 1 } ); - You do not have to specify the ``_id`` field to return the - field. It returns by default. To exclude the field, set it to - ``0`` in the projection document. For example, copy and paste - the following to return only the ``item``, and the ``status`` - fields in the matching documents: + You do not have to specify the ``_id`` field to return the field. + It returns by default. To exclude the field, set it to ``0`` in + the projection document. For example, run the following query to + return only the ``title``, and the ``genres`` fields in the + matching documents: .. code-block:: javascript - db.inventory.find( {}, { _id: 0, item: 1, status: 1 } ); + db.movies.find( { }, { "_id": 0, "title": 1, "genres": 1 } ); + + .. tab:: 6. Aggregate + :tabid: example-6 + + Aggregate Data (:pipeline:`$group`) + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + You can use aggregation to group values from multiple documents + together and return a single result. Aggregation in MongoDB + is performed with an :ref:`aggregation pipeline + `. + + While :method:`find()` operations are useful for data + retrieval, the aggregation pipeline allows you to manipulate + data, perform calculations, and write more expressive queries + than simple :ref:`CRUD operations `. + + In the :ref:`shell `, run the following + aggregation pipeline to count the number of occurrences + of each ``genre`` value: + + .. code-block:: javascript + db.movies.aggregate( [ + { $unwind: "$genres" }, + { + $group: { + _id: "$genres", + genreCount: { $count: { } } + } + }, + { $sort: { "genreCount": -1 } } + ] ) + + The pipeline uses: + + - :pipeline:`$unwind` to output a document for each element + in the ``genres`` array. + + - :pipeline:`$group` and the :group:`$count` accumulator + to count the number of occurrences of each ``genre``. This + value is stored in the ``genreCount`` field. + + - :pipeline:`$sort` to sort the resulting documents + by the ``genreCount`` field in descending order. Next Steps ---------- From ae0b52529f09f1513c9d004ee96eca23a97006e0 Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Fri, 17 Sep 2021 15:59:57 -0400 Subject: [PATCH 042/109] DOCS-14804 4.2.17-release notes --- .../includes/changelogs/releases/4.2.17.rst | 19 +++++++++++++++++++ source/release-notes/4.2-changelog.txt | 2 ++ source/release-notes/4.2.txt | 19 +++++++++++++++++++ 3 files changed, 40 insertions(+) create mode 100644 source/includes/changelogs/releases/4.2.17.rst diff --git a/source/includes/changelogs/releases/4.2.17.rst b/source/includes/changelogs/releases/4.2.17.rst new file mode 100644 index 00000000000..4a33e23818e --- /dev/null +++ b/source/includes/changelogs/releases/4.2.17.rst @@ -0,0 +1,19 @@ +.. _4.2.17-changelog: + +4.2.17 Changelog +---------------- + +Storage +~~~~~~~ + +:issue:`SERVER-49521` fix tests in core/txn to use write concern "majority" for createIndexes commands run before starting transactions + +Internals +~~~~~~~~~ + +- :issue:`SERVER-48090` Support python 3.6 for evergreen.py and shrub.py +- :issue:`SERVER-50549` Transform connection-related error codes in proxied commands +- :issue:`SERVER-53726` Platform Support: Remove RHEL6 zSeries +- :issue:`SERVER-59456` Start the LDAPReaper threadpool +- :issue:`SERVER-59876` Large delays in returning from libcrypto.so while establishing egress connections + diff --git a/source/release-notes/4.2-changelog.txt b/source/release-notes/4.2-changelog.txt index 7cedaf13e73..36cd34fa80c 100644 --- a/source/release-notes/4.2-changelog.txt +++ b/source/release-notes/4.2-changelog.txt @@ -10,6 +10,8 @@ :depth: 1 :class: singlecol +.. include:: /includes/changelogs/releases/4.2.17.rst + .. include:: /includes/changelogs/releases/4.2.16.rst .. include:: /includes/changelogs/releases/4.2.15.rst diff --git a/source/release-notes/4.2.txt b/source/release-notes/4.2.txt index 7c19d02a293..f120544e6b4 100644 --- a/source/release-notes/4.2.txt +++ b/source/release-notes/4.2.txt @@ -13,6 +13,25 @@ Release Notes for MongoDB 4.2 Minor Releases -------------- +.. _4.2.17-release-notes: + +4.2.17 - Upcoming +~~~~~~~~~~~~~~~~~ + +- :issue:`SERVER-59876`: Large delays in returning from libcrypto.so + while establishing egress connections +- :issue:`SERVER-59456`: Start the LDAPReaper threadpool +- :issue:`SERVER-50549`: Transform connection-related error codes in + proxied commands +- :issue:`SERVER-49521`: fix tests in core/txn to use write concern + "majority" for createIndexes commands run before starting transactions +- :issue:`SERVER-44152`: Pre-warm connection pools in mongos + +- `All JIRA issues closed in 4.2.17 + `__ + +- :ref:`4.2.17-changelog` + .. _4.2.16-release-notes: 4.2.16 - Sep 13, 2021 From 9d77215772f217483f61d4c7ee459e0c74bb4151 Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Wed, 8 Sep 2021 14:30:40 -0400 Subject: [PATCH 043/109] DOCS-14455 Add references for numHosts targeted in shardingStatistics --- .../fact-server-status-num-hosts-targeted.rst | 18 ++++++ source/reference/command/serverStatus.txt | 55 +++++++++++++++++++ source/release-notes/4.4.txt | 12 ++++ 3 files changed, 85 insertions(+) create mode 100644 source/includes/fact-server-status-num-hosts-targeted.rst diff --git a/source/includes/fact-server-status-num-hosts-targeted.rst b/source/includes/fact-server-status-num-hosts-targeted.rst new file mode 100644 index 00000000000..8f675b436ea --- /dev/null +++ b/source/includes/fact-server-status-num-hosts-targeted.rst @@ -0,0 +1,18 @@ +.. list-table:: + :header-rows: 1 + :widths: 20 40 + + * - Name + - Description + + * - ``allShards`` + - A command targeted all shards + + * - ``manyShards`` + - A command targeted more than one shard + + * - ``oneShard`` + - A command targeted one shard + + * - ``unsharded`` + - A command was run on an unsharded collection \ No newline at end of file diff --git a/source/reference/command/serverStatus.txt b/source/reference/command/serverStatus.txt index d06bc7e4671..9d351f19369 100644 --- a/source/reference/command/serverStatus.txt +++ b/source/reference/command/serverStatus.txt @@ -2774,6 +2774,39 @@ shardingStatistics .. code-block:: javascript "shardingStatistics" : { + "numHostsTargeted": { + "find" : { + "allShards": NumberLong(), + "manyShards": NumberLong(), + "oneShard": NumberLong(), + "unsharded": NumberLong() + }, + "insert": { + "allShards": NumberLong(), + "manyShards": NumberLong(), + "oneShard": NumberLong(), + "unsharded": NumberLong() + }, + "update": { + "allShards": NumberLong(), + "manyShards": NumberLong(), + "oneShard": NumberLong(), + "unsharded": NumberLong() + }, + "delete": { + "allShards": NumberLong(), + "manyShards": NumberLong(), + "oneShard": NumberLong(), + "unsharded": NumberLong() + }, + "aggregate": { + "allShards": NumberLong(), + "manyShards": NumberLong(), + "oneShard": NumberLong(), + "unsharded": NumberLong() + } + } + }, "catalogCache" : { "numDatabaseEntries" : NumberLong(), "numCollectionEntries" : NumberLong(), @@ -3364,6 +3397,28 @@ shardingStatistics .. versionadded:: 5.0 +.. serverstatus:: shardingStatistics.numHostsTargeted + + Indicates the number of shards targeted for ``CRUD`` operations and + aggregation commands. When a ``CRUD`` operation or aggregation + command is run, the following metrics will be incremented. + + .. include:: /includes/fact-server-status-num-hosts-targeted.rst + + .. note:: Running the :dbcommand:`serverStatus` on :binary:`mongos` + will provide insight into the aggregation operations find, + insert, update, delete and aggregate that run on a sharded + cluster. + + Multi-shard operations can either be + :ref:`scatter-gather` + or shard specific. Multi-shard scatter-gather operations can + :ref:`consume more resources`, + by using the + :serverstatus:`shardingStatistics.numHostsTargeted` + metrics you can tune the aggregation queries that run on a + sharded cluster. + .. serverstatus:: shardingStatistics.resharding.coordinatorState State of the resharding coordinator for the current :ref:`resharding diff --git a/source/release-notes/4.4.txt b/source/release-notes/4.4.txt index 0081e3b3a54..d0958cf9373 100644 --- a/source/release-notes/4.4.txt +++ b/source/release-notes/4.4.txt @@ -1915,6 +1915,18 @@ output: - :serverstatus:`shardedIndexConsistency` - :serverstatus:`shardingStatistics.rangeDeleterTasks` - :serverstatus:`shardingStatistics.unfinishedMigrationFromPreviousPrimary` + - :serverstatus:`shardingStatistics.numHostsTargeted` + +``serverStatus`` Sharding Statistics Output Change +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CRUD Operations and Aggregations + +:serverstatus:`shardingStatistics.numHostsTargeted` +which reports the number of shards targeted by CRUD operations and +aggregation commands. The relevant find, insert, update, delete or +aggregate metric will be incremented with each operation on a +cluster. ``replSetGetStatus`` Output Change ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From b790429dc799d58ca6c5abeb3f8f1dd6362dcad7 Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Wed, 8 Sep 2021 14:30:40 -0400 Subject: [PATCH 044/109] DOCS-14455 Add references for numHosts targeted in shardingStatistics --- source/reference/command/serverStatus.txt | 27 ++++++++++++----------- source/release-notes/4.4.txt | 2 -- 2 files changed, 14 insertions(+), 15 deletions(-) diff --git a/source/reference/command/serverStatus.txt b/source/reference/command/serverStatus.txt index 9d351f19369..5222147e02a 100644 --- a/source/reference/command/serverStatus.txt +++ b/source/reference/command/serverStatus.txt @@ -3405,19 +3405,20 @@ shardingStatistics .. include:: /includes/fact-server-status-num-hosts-targeted.rst - .. note:: Running the :dbcommand:`serverStatus` on :binary:`mongos` - will provide insight into the aggregation operations find, - insert, update, delete and aggregate that run on a sharded - cluster. - - Multi-shard operations can either be - :ref:`scatter-gather` - or shard specific. Multi-shard scatter-gather operations can - :ref:`consume more resources`, - by using the - :serverstatus:`shardingStatistics.numHostsTargeted` - metrics you can tune the aggregation queries that run on a - sharded cluster. + .. note:: + + Running the :dbcommand:`serverStatus` command on :binary:`mongos` + will provide insight into the CRUD and aggregation operations that + run on a sharded cluster. + + Multi-shard operations can either be + :ref:`scatter-gather` + or shard specific. Multi-shard scatter-gather operations can + :ref:`consume more resources`. + By using the + :serverstatus:`shardingStatistics.numHostsTargeted` + metrics you can tune the aggregation queries that run on a + sharded cluster. .. serverstatus:: shardingStatistics.resharding.coordinatorState diff --git a/source/release-notes/4.4.txt b/source/release-notes/4.4.txt index d0958cf9373..12b6fda9298 100644 --- a/source/release-notes/4.4.txt +++ b/source/release-notes/4.4.txt @@ -1920,8 +1920,6 @@ output: ``serverStatus`` Sharding Statistics Output Change ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -CRUD Operations and Aggregations - :serverstatus:`shardingStatistics.numHostsTargeted` which reports the number of shards targeted by CRUD operations and aggregation commands. The relevant find, insert, update, delete or From 9ddebce2b7dc191ee4421992b26581a6b5c0006b Mon Sep 17 00:00:00 2001 From: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> Date: Mon, 20 Sep 2021 11:48:21 -0400 Subject: [PATCH 045/109] =?UTF-8?q?DOCS-14695-Upgrading=20language=20stren?= =?UTF-8?q?gth=20with=20regards=20to=20hidden=20delayed=E2=80=A6=20(#5788)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * DOCS-14695-Upgrading language strength with regards to hidden delayed members * DOCS-14695-Upgrading language strength with regards to hidden delayed members --- source/core/replica-set-delayed-member.txt | 9 +++-- source/core/replica-set-hidden-member.txt | 6 ++-- .../important-delayed-replica-set-members.rst | 34 +++++++++++++++++++ 3 files changed, 45 insertions(+), 4 deletions(-) create mode 100644 source/includes/important-delayed-replica-set-members.rst diff --git a/source/core/replica-set-delayed-member.txt b/source/core/replica-set-delayed-member.txt index bdd5a61c384..df8406cba12 100644 --- a/source/core/replica-set-delayed-member.txt +++ b/source/core/replica-set-delayed-member.txt @@ -39,11 +39,16 @@ Delayed members: members. Set the priority to 0 to prevent a delayed member from becoming primary. -- **Should be** :ref:`hidden ` +- **Must be** :ref:`hidden ` members. Always prevent applications from seeing and querying delayed members. -- *Do* vote in :term:`elections ` for primary, if :rsconf:`members[n].votes` is set to 1. +- *Do* vote in :term:`elections ` for primary, if + :rsconf:`members[n].votes` is set to 1. Ensuring that delayed members + are non-voting by setting :rsconf:`members[n].votes` to 0 can help + improve performance. + +.. include:: /includes/important-delayed-replica-set-members.rst Behavior ~~~~~~~~ diff --git a/source/core/replica-set-hidden-member.txt b/source/core/replica-set-hidden-member.txt index e26261655ab..3fd2d10e999 100644 --- a/source/core/replica-set-hidden-member.txt +++ b/source/core/replica-set-hidden-member.txt @@ -39,8 +39,10 @@ Clients will not distribute reads with the appropriate :doc:`read preference ` to hidden members. As a result, these members receive no traffic other than basic replication. Use hidden members for dedicated tasks such as reporting and -backups. :doc:`Delayed members ` -should be hidden. +backups. + +.. include:: /includes/important-delayed-replica-set-members.rst + In a sharded cluster, :binary:`~bin.mongos` do not interact with hidden members. diff --git a/source/includes/important-delayed-replica-set-members.rst b/source/includes/important-delayed-replica-set-members.rst new file mode 100644 index 00000000000..46fae1f58d9 --- /dev/null +++ b/source/includes/important-delayed-replica-set-members.rst @@ -0,0 +1,34 @@ +.. important:: + + If your replica set contains :doc:`delayed members + ` ensure that the delayed + members are hidden and non-voting. + + Hiding delayed replica set members prevents applications from seeing + and querying delayed data without a direct connection to that member. + Making delayed replica set members non-voting means they will not + count towards acknowledging write operations with write concern + :writeconcern:`"majority"`. + + If you do not hide delayed members and one or more nodes + become unavailable, the replica set has to wait for the delayed + member and the commit point lags. A lagged commit point can lead to + performance issues. + + For example, consider a Primary-Secondary-Delayed replica set + configuration where the delayed secondary is voting with a 10 + minute delay. + + With one non-delayed secondary unavailable, the degraded configuration + of Primary-Delayed must wait at least 10 minutes to acknowledge a write + operation with :writeconcern:`"majority"`.The majority commit point + will take longer to advance, leading to cache pressure similar + performance issues with a + :ref:`Primary with a Secondary and an Arbiter` + (PSA) replica set. + + For more information on the majority commit point, see + :doc:`Causal Consistency and Read and Write Concerns + `. For additional + details on resolving performance issues see the + :ref:`replica set maintenance tutorial`. From 8e9e4e3b14b126ba1ca4cbe00a604666250682c7 Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Mon, 20 Sep 2021 14:24:55 -0400 Subject: [PATCH 046/109] (DOCS-14803): Clarification for range deletes --- source/core/sharding-balancer-administration.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/core/sharding-balancer-administration.txt b/source/core/sharding-balancer-administration.txt index 9fa3fe6dde5..b88c1d31e96 100644 --- a/source/core/sharding-balancer-administration.txt +++ b/source/core/sharding-balancer-administration.txt @@ -329,6 +329,12 @@ with :parameter:`rangeDeleterBatchSize` and :parameter:`rangeDeleterBatchDelayMS` above the current default of ``20`` milliseconds. +.. note:: + + If there are ongoing read operations or open cursors on the + collection targeted for deletes, range deletion processes may + not proceed. + .. _sharding-shard-size: Shard Size From 04f94a490b4e8e22f089ff6919f17093af0265f4 Mon Sep 17 00:00:00 2001 From: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> Date: Tue, 21 Sep 2021 10:29:56 -0400 Subject: [PATCH 047/109] DOCSP-18514 Added Atlas shoutout to main intro page (#5838) * DOCSP-18514 Added Atlas shoutout to main intro page * DOCSP-18514 Added Atlas shoutout to main intro page --- source/includes/fact-mongodb-intro.rst | 24 +++++++++++++++++++++ source/index.txt | 29 ++++---------------------- source/introduction.txt | 18 +--------------- 3 files changed, 29 insertions(+), 42 deletions(-) create mode 100644 source/includes/fact-mongodb-intro.rst diff --git a/source/includes/fact-mongodb-intro.rst b/source/includes/fact-mongodb-intro.rst new file mode 100644 index 00000000000..838af6cb1c2 --- /dev/null +++ b/source/includes/fact-mongodb-intro.rst @@ -0,0 +1,24 @@ +Welcome to the MongoDB {+version+} Manual! MongoDB is a +document database designed for ease of development +and scaling. The Manual introduces key concepts in MongoDB, presents the +query language, and provides operational and administrative +considerations and procedures as well as a comprehensive reference +section. + +MongoDB offers both local and cloud-hosted deployment options: + +- For locally hosted deployments, MongoDB offers both a *Community* + and an *Enterprise* version of the database: + + - MongoDB Community is the {+source-available+} edition of MongoDB. + + - MongoDB Enterprise is available as part of the MongoDB Enterprise + Advanced subscription and includes comprehensive support for your + MongoDB deployment. MongoDB Enterprise also adds enterprise-focused + features such as LDAP and Kerberos support, on-disk encryption, + and auditing. + +- `MongoDB Atlas `__ + is a hosted MongoDB Enterprise service option in the cloud which + requires no installation overhead and offers a free tier to get + started. diff --git a/source/index.txt b/source/index.txt index f6afd19f37b..462d9c4e784 100644 --- a/source/index.txt +++ b/source/index.txt @@ -13,31 +13,10 @@ The MongoDB |version| Manual To download MongoDB 5.0, go to the `MongoDB Download Center `_. -Welcome to the MongoDB |version| Manual! MongoDB is a -document database designed for ease of development -and scaling. The Manual introduces key concepts in MongoDB, presents the -query language, and provides operational and administrative -considerations and procedures as well as a comprehensive reference -section. - -MongoDB offers both a *Community* and an *Enterprise* version of the -database: - -- MongoDB Community is the {+source-available+} edition of MongoDB. - -- MongoDB Enterprise is available as part of the MongoDB Enterprise - Advanced subscription and includes comprehensive support for your - MongoDB deployment. MongoDB Enterprise also adds enterprise-focused - features such as LDAP and Kerberos support, on-disk encryption, - and auditing. - -MongoDB also offers -`Atlas `__, -a hosted MongoDB Enterprise service option in the cloud which requires -no installation overhead and offers a free tier to get started. - -The Manual documents both MongoDB Community and Enterprise features and -functionality. +.. include:: /includes/fact-mongodb-intro.rst + +The Manual documents features and functionality for MongoDB Community, +Enterprise, and Atlas deployments. Getting Started --------------- diff --git a/source/introduction.txt b/source/introduction.txt index 55409b60083..8741eaed4b9 100644 --- a/source/introduction.txt +++ b/source/introduction.txt @@ -10,23 +10,7 @@ Introduction to MongoDB :depth: 1 :class: singlecol -Welcome to the MongoDB |version| Manual! MongoDB is a -document database designed for ease of development -and scaling. The Manual introduces key concepts in MongoDB, presents the -query language, and provides operational and administrative -considerations and procedures as well as a comprehensive reference -section. - -MongoDB offers both a *Community* and an *Enterprise* version of the -database: - -- MongoDB Community is the {+source-available+} edition of MongoDB. - -- MongoDB Enterprise is available as part of the MongoDB Enterprise - Advanced subscription and includes comprehensive support for your - MongoDB deployment. MongoDB Enterprise also adds enterprise-focused - features such as LDAP and Kerberos support, on-disk encryption, - and auditing. +.. include:: /includes/fact-mongodb-intro.rst Document Database ----------------- From 41e55387a619c5f206d0a6b2735cd114ae498965 Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Mon, 20 Sep 2021 15:27:29 -0400 Subject: [PATCH 048/109] DOCS-14806 Added suggested edit for location of service script referenced --- source/reference/ulimit.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/source/reference/ulimit.txt b/source/reference/ulimit.txt index c2eb8b0073c..591e2c3e872 100644 --- a/source/reference/ulimit.txt +++ b/source/reference/ulimit.txt @@ -257,11 +257,12 @@ form: Linux distributions using ``systemd`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For Linux distributions that use ``systemd``, you can specify -limits within the ``[Service]`` sections of service scripts if you -start :binary:`~bin.mongod` and/or -:binary:`~bin.mongos` instances as ``systemd`` services. You can do this -by using `resource limit directives +If you start a :binary:`~bin.mongod` and/or :binary:`~bin.mongos` +instance as a ``systemd`` service, you can specify limits within the +``[Service]`` section of its service file. The service file has a +location like ``/etc/systemd/system/.service``. + +You can set limits by using `resource limit directives `_. Specify the :ref:`recommended-ulimit-settings`, as in the following From ec706e106b0862ba89b0e6836937db939201192d Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Wed, 8 Sep 2021 12:56:19 -0400 Subject: [PATCH 049/109] (DOCSP-18484): Fix confusing repl set resync step --- source/tutorial/resync-replica-set-member.txt | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/source/tutorial/resync-replica-set-member.txt b/source/tutorial/resync-replica-set-member.txt index b7d3883d84b..30e7d80fe58 100644 --- a/source/tutorial/resync-replica-set-member.txt +++ b/source/tutorial/resync-replica-set-member.txt @@ -84,18 +84,17 @@ perform an initial sync by restarting the instance without the contents of the method from :binary:`~bin.mongosh` or on Linux systems, the :option:`mongod --shutdown` option. -2. (Optional) Make a backup of all data and sub-directories from the +#. (Optional) Make a backup of all data and sub-directories from the member's :setting:`~storage.dbPath` directory. If a full backup is not required, consider backing up just the ``diagnostic.data`` directory to preserve potentially-useful troubleshooting data in the event of an issue. See :ref:`ftdc-stub` for more information. -3. Delete all data and sub-directories from the member's +#. Delete all data and sub-directories from the member's :setting:`~storage.dbPath` directory. -4. :doc:`Start the mongod process `, - specifying :ref:`cli-mongod-replica-set` with a new - :rsconf:`members[n]._id`. +#. :doc:`Restart the mongod process + `. At this point, the :binary:`~bin.mongod` performs an initial sync. The length of the initial sync process depends on the size of the database and the network From a0530c52d24e5fdc7537697f3a3b63cf0b689eab Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Wed, 22 Sep 2021 16:36:57 -0400 Subject: [PATCH 050/109] (DOCS-14807): Add release date for 4.4.9 --- source/release-notes/4.4.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/release-notes/4.4.txt b/source/release-notes/4.4.txt index 12b6fda9298..4a387113464 100644 --- a/source/release-notes/4.4.txt +++ b/source/release-notes/4.4.txt @@ -15,8 +15,8 @@ Minor Releases .. _4.4.9-release-notes: -4.4.9 - Upcoming -~~~~~~~~~~~~~~~~ +4.4.9 - Sep 21, 2021 +~~~~~~~~~~~~~~~~~~~~ Issues fixed: From 098d150ffd9575aeb59c05a9eed8993f257efc75 Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Wed, 22 Sep 2021 16:39:24 -0400 Subject: [PATCH 051/109] (DOCS-14808): Add release date for 5.0.3 --- source/release-notes/5.0.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 4680a33a90f..ca377da1c14 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -19,8 +19,8 @@ Minor Releases .. _5.0.3-release-notes: -5.0.3 - Upcoming -~~~~~~~~~~~~~~~~ +5.0.3 - Sep 21, 2021 +~~~~~~~~~~~~~~~~~~~~ Issues fixed: From 573297ec272c441ca64b9d5205f0474ba25e1f0a Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Wed, 22 Sep 2021 16:53:50 -0400 Subject: [PATCH 052/109] Fix build errors --- source/tutorial/getting-started.txt | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/source/tutorial/getting-started.txt b/source/tutorial/getting-started.txt index 6992d11af0d..5ffaf4975d7 100644 --- a/source/tutorial/getting-started.txt +++ b/source/tutorial/getting-started.txt @@ -32,7 +32,7 @@ examples in the shell above. :tabid: example-1 Switch Database - ~~~~~~~~~~~~~~~ + --------------- Within the :ref:`shell `, ``db`` refers to your current database. Type ``db`` to display the current @@ -69,7 +69,7 @@ examples in the shell above. :tabid: example-2 Populate a Collection (Insert) - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ------------------------------ MongoDB stores documents in :doc:`collections `. Collections are analogous to @@ -160,7 +160,7 @@ examples in the shell above. :tabid: example-3 Select All Documents - ~~~~~~~~~~~~~~~~~~~~ + -------------------- To select the documents from a collection, you can use the :method:`db.collection.find()` method. To select all documents @@ -179,7 +179,7 @@ examples in the shell above. :tabid: example-4 Filter Data with Comparison Operators - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ------------------------------------- For an equality match (```` equals ````), specify ``: `` in the :ref:`query filter @@ -227,7 +227,7 @@ examples in the shell above. :tabid: example-5 Specify Fields to Return (Projection) - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ------------------------------------- To specify fields to return, pass a projection document to the :method:`db.collection.find(\, \`. - While :method:`find()` operations are useful for data - retrieval, the aggregation pipeline allows you to manipulate - data, perform calculations, and write more expressive queries - than simple :ref:`CRUD operations `. + While :method:`~db.collection.find()` operations are useful for + data retrieval, the aggregation pipeline allows you to manipulate + data, perform calculations, and write more expressive queries than + simple :ref:`CRUD operations `. In the :ref:`shell `, run the following aggregation pipeline to count the number of occurrences From 301fc3b5f7a590cc0fcb479122de2c20a8966d8d Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Wed, 22 Sep 2021 17:19:32 -0400 Subject: [PATCH 053/109] (DOCSP-18806): Add minor release warnings for 4.4.2-4.4.8, 5.0.0-5.0.2 --- source/release-notes/4.4.txt | 44 +++++++++++++++++++++++++++++++----- source/release-notes/5.0.txt | 20 +++++++++++----- 2 files changed, 52 insertions(+), 12 deletions(-) diff --git a/source/release-notes/4.4.txt b/source/release-notes/4.4.txt index 4a387113464..f5687cf4685 100644 --- a/source/release-notes/4.4.txt +++ b/source/release-notes/4.4.txt @@ -41,6 +41,12 @@ Issues fixed: 4.4.8 - Aug 4, 2021 ~~~~~~~~~~~~~~~~~~~ +.. warning:: + + MongoDB version 4.4.8 is not recommended for production use due to + critical issues :issue:`WT-7984` and :issue:`WT-7995`, fixed in later + versions. Use the latest available patch release version. + Issues fixed: - :issue:`SERVER-58936`: Unique index constraints may not be enforced @@ -66,9 +72,10 @@ Issues fixed: .. warning:: - MongoDB version 4.4.7 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. + MongoDB version 4.4.7 is not recommended for production use due to + critical issues :issue:`SERVER-58936`, :issue:`WT-7984`, and + :issue:`WT-7995`, fixed in later versions. Use the latest + available patch release version. Issues fixed: @@ -93,6 +100,12 @@ Issues fixed: 4.4.6 - May 10, 2021 ~~~~~~~~~~~~~~~~~~~~ +.. warning:: + + MongoDB version 4.4.6 is not recommended for production use due to + critical issues :issue:`WT-7984` and :issue:`WT-7995`, fixed in later + versions. Use the latest available patch release version. + Issues fixed: - :issue:`SERVER-53604`: Include original aws iam arn in authenticate @@ -117,9 +130,10 @@ Issues fixed: .. warning:: - MongoDB version 4.4.5 is not recommended for production use due to a - critical issue, :issue:`WT-7426`, fixed in later versions. - Use the latest available patch release version. + MongoDB version 4.4.5 is not recommended for production use due to + critical issues :issue:`WT-7426`, :issue:`WT-7984`, and + :issue:`WT-7995`, fixed in later versions. Use the latest available + patch release version. Issues fixed: @@ -142,6 +156,12 @@ Issues fixed: 4.4.4 - Feb 16, 2021 ~~~~~~~~~~~~~~~~~~~~ +.. warning:: + + MongoDB version 4.4.4 is not recommended for production use due to + critical issues :issue:`WT-7984` and :issue:`WT-7995`, fixed in later + versions. Use the latest available patch release version. + Issues fixed: - :issue:`SERVER-48471`: Hashed indexes may be incorrectly marked @@ -164,6 +184,12 @@ Issues fixed: 4.4.3 - Jan 4, 2021 ~~~~~~~~~~~~~~~~~~~ +.. warning:: + + MongoDB version 4.4.3 is not recommended for production use due to + critical issues :issue:`WT-7984` and :issue:`WT-7995`, fixed in later + versions. Use the latest available patch release version. + Issues fixed: - :issue:`SERVER-33966`: redundant $sort in aggregation prevents best @@ -184,6 +210,12 @@ Issues fixed: 4.4.2 - Nov 18, 2020 ~~~~~~~~~~~~~~~~~~~~ +.. warning:: + + MongoDB version 4.4.2 is not recommended for production use due to + critical issues :issue:`WT-7984` and :issue:`WT-7995`, fixed in later + versions. Use the latest available patch release version. + Issues fixed: - :issue:`SERVER-48067`: Reduce memory consumption for unique index diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index ca377da1c14..5d185a7d151 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -45,6 +45,12 @@ Issues fixed: 5.0.2 - Aug 4, 2021 ~~~~~~~~~~~~~~~~~~~ +.. warning:: + + MongoDB version 5.0.2 is not recommended for production use due to + critical issues :issue:`WT-7984` and :issue:`WT-7995`, fixed in later + versions. Use the latest available patch release version. + Issues fixed: @@ -70,9 +76,10 @@ Issues fixed: .. 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. + MongoDB version 5.0.1 is not recommended for production use due to + critical issues :issue:`SERVER-58936`, :issue:`WT-7984`, and + :issue:`WT-7995`, fixed in later versions. Use the latest + available patch release version. Issues fixed: @@ -91,9 +98,10 @@ Issues fixed: .. 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. + MongoDB version 5.0.0 is not recommended for production use due to + critical issues :issue:`SERVER-58936`, :issue:`WT-7984`, and + :issue:`WT-7995`, fixed in later versions. Use the latest + available patch release version. The rest of this page provides the 5.0.0 release notes: From e22a6c7c63856f768bacf8b895eb7e886fdc99ca Mon Sep 17 00:00:00 2001 From: Dave Cuthbert Date: Wed, 22 Sep 2021 13:43:05 -0400 Subject: [PATCH 054/109] DOCSP-18660 Remove redundant note from serverStatus --- ...xtracts-server-status-projection-base.yaml | 188 ------------------ .../extracts-server-status-projection.yaml | 14 -- source/reference/command/serverStatus.txt | 4 - 3 files changed, 206 deletions(-) diff --git a/source/includes/extracts-server-status-projection-base.yaml b/source/includes/extracts-server-status-projection-base.yaml index c0388a1ac2c..0df4b243298 100644 --- a/source/includes/extracts-server-status-projection-base.yaml +++ b/source/includes/extracts-server-status-projection-base.yaml @@ -11,192 +11,4 @@ content: | field and set it to ``1`` in the command. To exclude fields that are included by default, specify the top-level field and set to ``0`` in the command. ---- -ref: _serverStatus-output-changes -content: | - - - Starting in MongoDB 5.0, {{operationName}}: - - - Added new metrics to track use of Aggregation Pipeline methods: - - - :serverstatus:`metrics.commands.update.pipeline` - - - :serverstatus:`metrics.commands.findAndModify.pipeline` - - - Added new metrics to track use of arrayFilter methods: - - - :serverstatus:`metrics.commands.update.arrayFilters` - - - :serverstatus:`metrics.commands.findAndModify.arrayFilters` - - - Added new metric to track number of times ``newlyAdded`` fields - were automatically removed: - - - :serverstatus:`metrics.repl.reconfig.numAutoReconfigsForRemovalOfNewlyAddedFields` - - - Replaced :serverstatus:`opReadConcernCounters` with - :serverstatus:`readConcernCounters` to track use of read concern - levels specified by query operations - - - Added new metric to track number of incoming connections: - - - :serverstatus:`connections.threaded` - - - Added new metric to track resharding operations: - - - :serverstatus:`shardingStatistics.resharding` - - - Added new metric to track service executors: - - - :serverstatus:`network.serviceExecutors` - - - Added new metrics to track cursors: - - - :serverstatus:`metrics.cursor.moreThanOneBatch` - - - :serverstatus:`metrics.cursor.totalOpened` - - - Added new metric to track hello commands: - - - :serverstatus:`connections.exhaustHello` - - - Starting in MongoDB 4.4, {{operationName}}: - - - Added new metrics to track write concern failures caused - by a custom global default write concern: - - - :serverstatus:`metrics.getLastError.default` - - - :serverstatus:`metrics.getLastError.default.unsatisfiable` - - - :serverstatus:`metrics.getLastError.default.wtimeouts` - - - Added new metrics to track authentication mechanism usage: - - - :serverstatus:`security.authentication.mechanisms` - - Each field in :serverstatus:`security.authentication.mechanisms` - represents an authentication mechanism supported by your - :binary:`~bin.mongod` / :binary:`~bin.mongos` instance, and - includes information on the number of times that mechanism - has been used. - - These metrics are also available starting in MongoDB - 4.2.6 and 4.0.19. - - - Added new topology metrics in :serverstatus:`connections`: - - - :serverstatus:`connections.exhaustIsMaster` - - - :serverstatus:`connections.awaitingTopologyChanges` - - - Added new metrics to track slow DNS and SSL handshake operations - in :serverstatus:`network`: - - - :serverstatus:`network.numSlowDNSOperations` - - - :serverstatus:`network.numSlowSSLOperations` - - - Added new sync source metrics in :serverstatus:`metrics.repl`: - - - :serverstatus:`metrics.repl.network.oplogGetMoresProcessed` - - - :serverstatus:`metrics.repl.network.oplogGetMoresProcessed.num` - - - :serverstatus:`metrics.repl.network.oplogGetMoresProcessed.totalMillis` - - - :serverstatus:`metrics.repl.network.replSetUpdatePosition.num` - - - :serverstatus:`metrics.repl.syncSource.numSelections` - - - :serverstatus:`metrics.repl.syncSource.numTimesChoseSame` - - - :serverstatus:`metrics.repl.syncSource.numTimesChoseDifferent` - - - :serverstatus:`metrics.repl.syncSource.numTimesCouldNotFind` - - - Added new metrics to track aggregation pipeline stage use in - :serverstatus:`metrics.aggStageCounters`. - - - Added new metrics to track queries that perform a collection scan: - - - :serverstatus:`metrics.queryExecutor.collectionScans` - - :serverstatus:`metrics.queryExecutor.collectionScans.nonTailable` - - :serverstatus:`metrics.queryExecutor.collectionScans.total` - - - Added new :serverstatus:`range deletion metrics - ` in - :serverstatus:`shardingStatistics`. - - - Starting in MongoDB 4.2.2, {{operationName}}: - - - Added new transaction metrics in :serverstatus:`transactions` for - :binary:`~bin.mongos`: - - - :serverstatus:`transactions.currentOpen` - - - :serverstatus:`transactions.currentActive` - - - :serverstatus:`transactions.currentInactive` - - - Starting in MongoDB 4.2.1 (and 4.0.13), {{operationName}} includes: - - - :ref:`electionMetrics ` - - - Starting in MongoDB 4.2, {{operationName}}: - - - Returns :serverstatus:`opcounters` and - :serverstatus:`opcountersRepl` metrics as 64-bit integers (i.e. - NumberLong) instead of 32-bit integers (i.e. NumberInt). - - - Includes ``trafficRecording`` metrics in its output. - - - Added new document count (``countDocs``) metrics in - :serverstatus:`shardingStatistics`. - - - Added new unacknowledged writes counts to - :serverstatus:`metrics.repl.network`. - - - Added new user operations counts to - :serverstatus:`metrics.repl.stepDown`. - - - Added new transaction metrics in :serverstatus:`transactions` for - :binary:`~bin.mongod`. - - - Includes :serverstatus:`transactions` metrics for - :binary:`~bin.mongos`. - - - Added - :serverstatus:`~logicalSessionRecordCache.sessionCatalogSize` - metric to :serverstatus:`logicalSessionRecordCache`. - - - Added - :serverstatus:`~shardingStatistics.countDonorMoveChunkLockTimeout` - metric to :serverstatus:`shardingStatistics`. - - - Added ``ReplicationStateTransition`` lock information to - :serverstatus:`locks`. - - - Reports ``ParallelBatchWriterMode`` lock information separately from - ``Global`` lock information. See :serverstatus:`locks`. - - - Starting in MongoDB 4.0.6, {{operationName}} includes: - - - :serverstatus:`opReadConcernCounters` - - - :serverstatus:`opWriteConcernCounters` (Requires - :parameter:`reportOpWriteConcernCountersInServerStatus` parameter - set to ``true``). - - - :serverstatus:`metrics.repl.apply.batchSize` - - - Starting in MongoDB 4.0, {{operationName}} includes - :serverstatus:`shardingStatistics` in its output. - - - Starting in MongoDB 3.6, {{operationName}} no longer outputs the - ``rangeDeleter`` section. - - - Starting in MongoDB 3.0, {{operationName}} no longer outputs the - ``workingSet``, ``indexCounters``, and ``recordStats`` sections. - ... diff --git a/source/includes/extracts-server-status-projection.yaml b/source/includes/extracts-server-status-projection.yaml index b201db4d4e4..f12a1e59904 100644 --- a/source/includes/extracts-server-status-projection.yaml +++ b/source/includes/extracts-server-status-projection.yaml @@ -12,20 +12,6 @@ inherit: replacement: operationName: ":method:`db.serverStatus()`" --- -ref: serverStatus-command-output-change -inherit: - ref: _serverStatus-output-changes - file: extracts-server-status-projection-base.yaml -replacement: - operationName: ":dbcommand:`serverStatus`" ---- -ref: serverStatus-method-output-change -inherit: - ref: _serverStatus-output-changes - file: extracts-server-status-projection-base.yaml -replacement: - operationName: ":method:`db.serverStatus()`" ---- ref: serverStatus-opWriteConcernCounters content: | diff --git a/source/reference/command/serverStatus.txt b/source/reference/command/serverStatus.txt index 5222147e02a..c131d2c8379 100644 --- a/source/reference/command/serverStatus.txt +++ b/source/reference/command/serverStatus.txt @@ -5672,7 +5672,3 @@ watchdog The value set by :parameter:`watchdogPeriodSeconds`. This is the period between status checks. -Output Changelog ----------------- - -.. include:: /includes/extracts/serverStatus-command-output-change.rst From 3f535ce5dc19db3fd5a813669cbb44eacd205e5e Mon Sep 17 00:00:00 2001 From: ianf-mongodb <85948430+ianf-mongodb@users.noreply.github.com> Date: Fri, 24 Sep 2021 15:52:44 -0400 Subject: [PATCH 055/109] DOCS-13871 Add REPL output to serverStatus command (#5874) * DOCS-13871 Add REPL output to serverStatus command * DOCS-13871 Add REPL output to serverStatus command --- source/reference/command/serverStatus.txt | 76 +++++++++++++++++++++++ source/release-notes/5.0.txt | 7 +++ 2 files changed, 83 insertions(+) diff --git a/source/reference/command/serverStatus.txt b/source/reference/command/serverStatus.txt index c131d2c8379..9827cac2c2b 100644 --- a/source/reference/command/serverStatus.txt +++ b/source/reference/command/serverStatus.txt @@ -2391,6 +2391,12 @@ repl "primary" : , "me" : , "electionId" : ObjectId(""), + "primaryOnlyServices": { + "ReshardingRecipientService": { "state": , "numInstances": }, + "RenameCollectionParticipantService": { "state": , "numInstances": }, + "ShardingDDLCoordinator": { "state": , "numInstances": }, + "ReshardingDonorService": { "state": , "numInstances": } + }, "rbid" : , "replicationProgress" : [ { @@ -2441,6 +2447,76 @@ repl The hostname and port information (``"host:port"``) for the current member of the replica set. +.. serverstatus:: repl.primaryOnlyServices + + Document that contains the number and status of + instances of each primary service active on the server. Primary + services can only start when a server is primary but can continue running to + completion after the server changes state. + + .. versionadded:: 5.0 + +.. serverstatus:: repl.primaryOnlyServices.ReshardingRecipientService + + Document that contains the state and number of instances of the + ``ReshardingRecipientService``. + + Recipients are the shards,that would own the chunks after as a + result of the resharding operation, according to the new + :manual:`shard key` and + :manual:`zones`. + + The resharding coordinator instructs each donor and recipient shard + primary, to rename the temporary sharded collection. + The temporary collection becomes the new resharded collection. + + .. versionadded:: 5.0 + +.. serverstatus:: repl.primaryOnlyServices.RenameCollectionParticipantService + + Document that contains the state and number of instances of the + ``RenameCollectionParticipantService``. + + The ``RenameCollectionParticipantService`` ensures that, after a shard + receives a + :manual:`renameCollection` + request, the shard is able to resume the local rename in case of + system failure. + + .. versionadded:: 5.0 + +.. serverstatus:: repl.primaryOnlyServices.ShardingDDLCoordinator + + Document that contains the state and number of instances of the + ``ShardingDDLCoordinator``. + + The ``ShardingDDLCoordinator`` service manages DDL operations for + :manual:`primary` + databases such as: + :manual:`create database`, + :manual:`drop database`, + :manual:`renameCollection`. + + The ``ShardingDDLCoordinator`` ensures that one DDL operation for + each database can happen at any one specific point in time within a + sharded cluster. + + .. versionadded:: 5.0 + +.. serverstatus:: repl.primaryOnlyServices.ReshardingDonorService + + Document that contains the state and number of instances of the + ``ReshardingDonorService``. + + Donors are the shards that own chunks of the sharded collection + before the rename operation completes. + + The resharding coordinator instructs each donor and recipient shard + primary, to rename the temporary sharded collection. + The temporary collection becomes the new resharded collection. + + .. versionadded:: 5.0 + .. serverstatus:: repl.rbid :term:`Rollback ` identifier. Used to determine if a rollback has diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 5d185a7d151..9a9a0b24198 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -909,6 +909,13 @@ Security Counter which reports the number of times a :dbcommand:`hello` request includes a valid :data:`hello.saslSupportedMechs` field. +Repl + - :serverstatus:`repl` now includes a + :serverstatus:`~repl.primaryOnlyServices` document that + contains additional information about services that only run on + replica set primaries. + + Plan Cache Debug Info Size Limit ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 2b1f4ce3d099e697cdb64af21548b301d04aa68c Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Thu, 23 Sep 2021 15:54:56 -0400 Subject: [PATCH 056/109] DOCS-18789 Correcting case sensitivity limitation blurb --- .../fact-case-sensitivity-limitation-code.rst | 31 +++++++++++++++++++ source/reference/limits.txt | 7 +++-- 2 files changed, 36 insertions(+), 2 deletions(-) create mode 100644 source/includes/fact-case-sensitivity-limitation-code.rst diff --git a/source/includes/fact-case-sensitivity-limitation-code.rst b/source/includes/fact-case-sensitivity-limitation-code.rst new file mode 100644 index 00000000000..ea35a2174af --- /dev/null +++ b/source/includes/fact-case-sensitivity-limitation-code.rst @@ -0,0 +1,31 @@ + +.. example:: + + If the database ``salesDB`` already exists MongoDB will + return an error if if you attempt to create a database named ``salesdb``. + + .. code-block:: javascript + + mixedCase = db.getSiblingDB('salesDB') + lowerCase = db.getSiblingDB('salesdb') + + mixedCase.retail.insertOne({ "widgets": 1, "price": 50 }) + + The operation succeeds and :method:`~db.collection.insertOne()` implicitly + creates the ``SalesDB`` database. + + .. code-block:: javascript + + lowerCase.retail.insertOne({ "widgets": 1, "price": 50 }) + + The operation fails. :method:`~db.collection.insertOne()` tries to + create a ``salesdb`` database and is blocked by the naming + restriction. Database names must differ on more than just case. + + .. code-block:: javascript + + lowerCase.retail.find() + + This operation does not return any results because the database names are case + sensitive. There is no error because :method:`~db.collection.find()` doesn't + implicitly create a new database. \ No newline at end of file diff --git a/source/reference/limits.txt b/source/reference/limits.txt index 79d7c45ac32..154f673564e 100644 --- a/source/reference/limits.txt +++ b/source/reference/limits.txt @@ -36,8 +36,11 @@ Naming Restrictions .. limit:: Database Name Case Sensitivity - Since database names are case *insensitive* in MongoDB, database - names cannot differ only by the case of the characters. + Database names are case-sensitive in MongoDB. They also have an + additional restriction, case cannot be the only difference between + database names. + + .. include:: /includes/fact-case-sensitivity-limitation-code.rst .. limit:: Restrictions on Database Names for Windows From 25de225344593ac1057c496823d11b233e8a1b65 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Thu, 26 Aug 2021 14:10:58 +0200 Subject: [PATCH 057/109] DOCSP-18010: Refactor Authentication mechanisms --- snooty.toml | 1 + source/core/authentication-mechanisms.txt | 42 +- .../core/security-internal-authentication.txt | 4 +- source/core/security-scram.txt | 81 ++- source/core/security-x.509.txt | 83 +-- source/includes/extracts-ssl-facts.yaml | 16 +- .../includes/extracts-x509-certificate.yaml | 137 ++--- .../fact-ssl-certificate-authorities.rst | 6 +- .../list-table-3.0-driver-compatibility.rst | 38 +- .../steps-use-x509-authentication.yaml | 268 +++++++++ .../configure-scram-client-authentication.txt | 32 ++ .../configure-x509-client-authentication.txt | 508 +----------------- source/tutorial/enable-authentication.txt | 33 +- 13 files changed, 499 insertions(+), 750 deletions(-) create mode 100644 source/includes/steps-use-x509-authentication.yaml create mode 100644 source/tutorial/configure-scram-client-authentication.txt diff --git a/snooty.toml b/snooty.toml index 54803e778f2..8062db85771 100644 --- a/snooty.toml +++ b/snooty.toml @@ -67,6 +67,7 @@ toc_landing_pages = [ "/core/security-hardening", "/core/security-internal-authentication", "/core/security-ldap", + "/core/security-scram", "/core/security-transport-encryption", "/core/security-users", "/core/security-x.509", diff --git a/source/core/authentication-mechanisms.txt b/source/core/authentication-mechanisms.txt index 2a58a277451..88166e441cf 100644 --- a/source/core/authentication-mechanisms.txt +++ b/source/core/authentication-mechanisms.txt @@ -12,14 +12,10 @@ Authentication Mechanisms :depth: 1 :class: singlecol -.. note:: - - Starting in version 4.0, MongoDB removes support for the deprecated - MongoDB Challenge-Response (``MONGODB-CR``) authentication mechanism. MongoDB supports the following authentication mechanisms: -- :doc:`/core/security-scram` (*Default*) +- :doc:`SCRAM Authentication ` (*Default*) - :doc:`x.509 Certificate Authentication `. @@ -30,24 +26,36 @@ authentication mechanisms supported by MongoDB Enterprise. .. _authentication-mechanism-default: -Default Authentication Mechanism --------------------------------- +SCRAM Authentication +-------------------- + +Salted Challenge Response Authentication Mechanism (SCRAM) is the +default authentication mechanism for MongoDB. -As of MongoDB 3.0, :ref:`Salted Challenge Response Authentication -Mechanism (SCRAM) ` is the default -authentication mechanism for MongoDB. +For more information on SCRAM and MongoDB, see: +- :doc:`SCRAM Authentication ` +- :ref:`scram-client-authentication` -Specify Authentication Mechanism +.. _authentication-mechanism-x509: + +x.509 Certificate Authentication -------------------------------- -To specify the authentication mechanism to use, set the -:parameter:`authenticationMechanisms` parameter for :binary:`~bin.mongod` and -:binary:`~bin.mongos`. +MongoDB supports x.509 certificate authentication for client +authentication and internal authentication of the members of replica +sets and sharded clusters. x.509 certificate authentication requires a +secure :doc:`TLS/SSL connection `. + +To use MongoDB with x.509, you must use valid certificates generated and +signed by a certificate authority. The client x.509 certificates +must meet the :ref:`client certificate requirements +`. + +For more information on x.509 and MongoDB, see: -Clients specify the authentication mechanism in the :method:`db.auth()` method. -For :binary:`~bin.mongosh` and the MongoDB tools, you can also specify the -authentication mechanism from the command line. +- :doc:`x.509 Certificate Authentication ` +- :ref:`x509-client-authentication` .. toctree:: :titlesonly: diff --git a/source/core/security-internal-authentication.txt b/source/core/security-internal-authentication.txt index 2066e0c73d7..bb1b0634f27 100644 --- a/source/core/security-internal-authentication.txt +++ b/source/core/security-internal-authentication.txt @@ -67,7 +67,7 @@ For example, .. tabs:: tabs: - + - id: single-key name: Single key content: | @@ -175,10 +175,10 @@ see :doc:`/tutorial/upgrade-keyfile-to-x509`. /tutorial/deploy-replica-set-with-keyfile-access-control /tutorial/enforce-keyfile-access-control-in-existing-replica-set /tutorial/enforce-keyfile-access-control-in-existing-replica-set-without-downtime - /tutorial/rotate-key-replica-set /tutorial/deploy-sharded-cluster-with-keyfile-access-control /tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster /tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime + /tutorial/rotate-key-replica-set /tutorial/rotate-key-sharded-cluster /tutorial/configure-x509-member-authentication /tutorial/upgrade-keyfile-to-x509 diff --git a/source/core/security-scram.txt b/source/core/security-scram.txt index aea924f3d1b..dbab88bcbff 100644 --- a/source/core/security-scram.txt +++ b/source/core/security-scram.txt @@ -1,7 +1,5 @@ .. _authentication-scram: - - ===== SCRAM ===== @@ -14,33 +12,22 @@ SCRAM :depth: 1 :class: singlecol -.. note:: +Salted Challenge Response Authentication Mechanism (SCRAM) is the +default authentication mechanism for MongoDB. - Starting in version 4.0, MongoDB removes support for the deprecated - MongoDB Challenge-Response (``MONGODB-CR``) authentication mechanism. +When a user :ref:`authenticates ` +themselves, MongoDB uses SCRAM to verify the supplied user credentials +against the user's :data:`name `, +:data:`password ` and +:data:`authentication database `. - If your deployment has user credentials stored in ``MONGODB-CR`` - schema, you must upgrade to SCRAM **before** you upgrade to version - 4.0. For information on upgrading to ``SCRAM``, see - :doc:`/release-notes/3.0-scram`. - -Salted Challenge Response Authentication Mechanism (SCRAM) is the -default authentication mechanism for MongoDB. SCRAM is based on the -IETF `RFC 5802 `_ standard that -defines best practices for implementation of challenge-response -mechanisms for authenticating users with passwords. - -Using SCRAM, MongoDB verifies the supplied user credentials against the -user's :data:`name `, :data:`password -` and :data:`authentication database -`. The authentication database is the database -where the user was created, and together with the user's name, serves -to identify the user. +SCRAM is based on the IETF `RFC 5802 +`_ standard that defines best +practices for the implementation of challenge-response mechanisms for +authenticating users with passwords. .. _authentication-scram-sha-1: - .. _authentication-scram-sha-256: - .. _scram-features: Features @@ -48,12 +35,9 @@ Features MongoDB's implementation of SCRAM provides: -- A tunable work factor (i.e. the iteration count), - -- Per-user random salts, and - -- Authentication of the server to the client as well as the client to the - server. +- A tunable work factor (the iteration count) +- Per-user random salts +- Bi-directional authentication between server and client .. _scram-mechanisms: @@ -69,35 +53,34 @@ MongoDB supports the following SCRAM mechanisms: * - SCRAM Mechanism - Description - * - ``SCRAM-SHA-1`` + * - ``SCRAM-SHA-1`` - Uses the SHA-1 hashing function. To modify the iteration count for ``SCRAM-SHA-1``, see :parameter:`scramIterationCount`. - * - ``SCRAM-SHA-256`` + * - ``SCRAM-SHA-256`` - - Uses the SHA-256 hashing function and requires - featureCompatibilityVersion (``fcv``) set to ``4.0``. + - Uses the SHA-256 hashing function. To modify the iteration count for ``SCRAM-SHA-256``, see :parameter:`scramSHA256IterationCount`. - .. versionadded:: 4.0 -When creating or updating a SCRAM user, you can indicate the specific -SCRAM mechanism as well as indicate whether the server or the client -digests the password. When using ``SCRAM-SHA-256``, MongoDB requires -server-side password hashing, i.e. the server digests the password. For -details, see :method:`db.createUser()` and :method:`db.updateUser()`. +When you create or update a SCRAM user, you can indicate: + +- the SCRAM mechanism to use +- whether the server or the client digests the password + +When you use ``SCRAM-SHA-256``, MongoDB requires server-side password +hashing, which means that the server digests the password. For more +information, see :method:`db.createUser()` and +:method:`db.updateUser()`. Driver Support -------------- -To use SCRAM, you must upgrade your driver if your current driver -version does not support ``SCRAM``. - The minimum driver versions that support ``SCRAM`` are: .. |driver-compatibility-heading| replace:: Version @@ -107,12 +90,16 @@ The minimum driver versions that support ``SCRAM`` are: Additional Information ---------------------- -- `Blog Post: Improved Password-Based Authentication in MongoDB 3.0: SCRAM - Explained (Part 1) +- `Blog Post: Improved Password-Based Authentication: SCRAM Explained (Part 1) `_ -- `Blog Post: Improved Password-Based Authentication in MongoDB 3.0: SCRAM - Explained (Part 2) +- `Blog Post: Improved Password-Based Authentication: SCRAM Explained (Part 2) `_ + +.. toctree:: + :titlesonly: + :hidden: + + /tutorial/configure-scram-client-authentication diff --git a/source/core/security-x.509.txt b/source/core/security-x.509.txt index 7c6b127b030..fb55f75a576 100644 --- a/source/core/security-x.509.txt +++ b/source/core/security-x.509.txt @@ -12,17 +12,12 @@ x.509 :depth: 1 :class: singlecol -MongoDB supports x.509 certificate authentication for client authentication and -internal authentication of the members of replica sets and sharded clusters. +MongoDB supports x.509 certificate authentication for client +authentication and internal authentication of the members of replica +sets and sharded clusters. -x.509 certificate authentication requires a secure :doc:`TLS/SSL connection -`. - -.. note:: - - .. include:: /includes/fact-tls-1.0.rst - -.. |binary| replace:: MongoDB +x.509 certificate authentication requires a secure :doc:`TLS/SSL +connection `. Certificate Authority --------------------- @@ -37,6 +32,8 @@ Client x.509 Certificates To authenticate to servers, clients can use x.509 certificates instead of usernames and passwords. +.. _client-x509-certificates-requirements: + Client Certificate Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -49,63 +46,21 @@ MongoDB User and ``$external`` Database To authenticate with a client certificate, you must first add the value of the ``subject`` from the client certificate as a MongoDB user. Each -unique x.509 client certificate corresponds to a single MongoDB user; -i.e. you cannot use a single client certificate to authenticate more -than one MongoDB user. +unique x.509 client certificate corresponds to a single MongoDB user. +You cannot use a single client certificate to authenticate more than one +MongoDB user. -Add the user in the ``$external`` database; i.e. the -:ref:`authentication-database` is the ``$external`` database +Add the user in the ``$external`` database. The ``$external`` database +is the :ref:`authentication-database` for the user. .. include:: /includes/extracts/sessions-external-username-limit.rst -Authenticate -~~~~~~~~~~~~ - -To connect and authenticate using x.509 client certificate: - -- For MongoDB 4.2 or greater, include the following options for the client: - - - :option:`--tls ` (or the deprecated ``--ssl`` option) - - - :option:`--tlsCertificateKeyFile ` - (or the deprecated ``--sslPEMKeyFile`` option) - - - :option:`--tlsCertificateKeyFilePassword ` - (or the deprecated ``--sslPEMKeyPassword`` option) if the - certificate key file is encrypted - - - :option:`--authenticationDatabase '$external' - ` - - - :option:`--authenticationMechanism MONGODB-X509 - ` - -- For MongoDB 4.0 and earlier, include the following options for the client: - - - ``--ssl`` - - - ``--sslPEMKeyFile`` - - - ``--sslPEMKeyPassword`` option if - the ``--sslPEMKeyFile`` is encrypted. - - - :option:`--authenticationDatabase '$external' - ` - - - :option:`--authenticationMechanism MONGODB-X509 ` - -You can also make the TLS/SSL connection first, and then use -:method:`db.auth()` in the ``$external`` database to authenticate. - -For examples of both cases, see the :ref:`authenticate-with-x509-cert` -section in :doc:`/tutorial/configure-x509-client-authentication` - Member x.509 Certificates --------------------------- +------------------------- -For internal authentication, members of sharded clusters and replica sets -can use x.509 certificates instead of keyfiles, which use the -:doc:`/core/security-scram` authentication mechanism. +For internal authentication between members of sharded clusters and +replica sets you can use x.509 certificates instead of keyfiles, which +use the :doc:`/core/security-scram` authentication mechanism. .. _x509-member-certificate-requirements: @@ -119,12 +74,6 @@ MongoDB Configuration for Membership Authentication .. include:: /includes/extracts/x509-member-auth-configuration.rst -Next Steps -~~~~~~~~~~ - -For an example of x.509 internal authentication, see -:doc:`/tutorial/configure-x509-member-authentication`. - .. toctree:: :titlesonly: :hidden: diff --git a/source/includes/extracts-ssl-facts.yaml b/source/includes/extracts-ssl-facts.yaml index 22bc149360e..3304090e1a1 100644 --- a/source/includes/extracts-ssl-facts.yaml +++ b/source/includes/extracts-ssl-facts.yaml @@ -1,13 +1,11 @@ ref: ssl-facts-x509-invalid-certificate content: | - Starting in MongoDB 4.0, if you specify - ``--sslAllowInvalidCertificates`` or - ``net.ssl.allowInvalidCertificates: true`` (or in MongoDB 4.2, the - alias ``--tlsAllowInvalidateCertificates`` or - ``net.tls.allowInvalidCertificates: true``) when using x.509 + Starting in MongoDB 4.2, if you specify + ``--tlsAllowInvalidateCertificates`` or + ``net.tls.allowInvalidCertificates: true`` when using x.509 authentication, an invalid certificate is only sufficient to - establish a TLS/SSL connection but is *insufficient* for + establish a TLS connection but it is *insufficient* for authentication. --- @@ -28,10 +26,8 @@ ref: ssl-facts-x509-ca-file content: | To use x.509 authentication, ``--tlsCAFile`` or ``net.tls.CAFile`` - must be specified unless using ``--tlsCertificateSelector`` or - ``--net.tls.certificateSelector``. Or if using the ``ssl`` aliases, - ``--sslCAFile`` or ``net.ssl.CAFile`` must be specified unless using - ``--sslCertificateSelector`` or ``net.ssl.certificateSelector``. + must be specified unless you are using ``--tlsCertificateSelector`` + or ``--net.tls.certificateSelector``. --- ref: ssl-facts-see-more diff --git a/source/includes/extracts-x509-certificate.yaml b/source/includes/extracts-x509-certificate.yaml index 81736beabd9..f34f1411057 100644 --- a/source/includes/extracts-x509-certificate.yaml +++ b/source/includes/extracts-x509-certificate.yaml @@ -1,7 +1,7 @@ ref: x509-certificate-client content: | - The client certificate must have the following - properties: + + Client certificates must have the following properties: - A single Certificate Authority (CA) must issue the certificates for both the client and the server. @@ -16,65 +16,63 @@ content: | - Each unique MongoDB user must have a unique certificate. - A client x.509 certificate's subject, which contains the - Distinguished Name (``DN``), must **differ** from that of a - :ref:`x509-member-certificate`. - + Distinguished Name (``DN``), must **differ** from the subjects of + :ref:`member x.509 certificates `. + At least one of the Organization (``O``), Organizational Unit (``OU``), or Domain Component (``DC``) attributes in the client certificate must differ from those in the :setting:`net.tls.clusterFile` and - :setting:`net.tls.certificateKeyFile` server certificates. - + :setting:`net.tls.certificateKeyFile` server certificates. If a + client x.509 certificate's subject has the same ``O``, ``OU``, and + ``DC`` combination as the :ref:`x509-member-certificate` (or + :parameter:`tlsX509ClusterAuthDNOverride` if set), the client + connection is rejected. Only :ref:`cluster member x509 certificates + ` should use same ``O``, ``OU``, and + ``DC`` combinations as this grants full permissions. + If the MongoDB deployment has - :parameter:`tlsX509ClusterAuthDNOverride` set (available starting - in MongoDB 4.2), the client x.509 certificate's subject must also + :parameter:`tlsX509ClusterAuthDNOverride` set (*available starting + in MongoDB 4.2*), the client x.509 certificate's subject must also differ from that value. - .. warning:: - - If a client x.509 certificate's subject has the same ``O``, - ``OU``, and ``DC`` combination as the - :ref:`x509-member-certificate` (or - :parameter:`tlsX509ClusterAuthDNOverride` if set), the client - connection is rejected. Only - :ref:`cluster member x509 certificates ` - should use same ``O``, ``OU``, and ``DC`` combinations as this - grants full permissions. + - The x.509 certificate must *not* be expired. - - The x.509 certificate must *not* be expired. - .. include:: /includes/extracts/4.4-changes-certificate-expiry-warning.rst --- ref: x509-certificate-member content: | - The member certificate (:setting:`net.tls.clusterFile`, if - specified, and :setting:`net.tls.certificateKeyFile`), used to - verify membership to the sharded cluster or a replica set, must have - the following properties: + Member certificates which you use to verify membership to a sharded + cluster or a replica set (:setting:`net.tls.clusterFile`, if + specified, and :setting:`net.tls.certificateKeyFile`), must have the + following properties: - A single Certificate Authority (CA) must issue all the x.509 certificates for the members of a sharded cluster or a replica set. - The Distinguished Name (``DN``), found in the member certificate's - ``subject``, must specify a non-empty value for *at least one* of the - following attributes: Organization (``O``), the Organizational Unit - (``OU``) or the Domain Component (``DC``). - + ``subject``, must specify a non-empty value for *at least one* of + the following attributes: + + - the Organization (``O``) + - the Organizational Unit (``OU``) + - the Domain Component (``DC``) + - The Organization attributes (``O``\'s), the Organizational Unit attributes (``OU``\'s), and the Domain Components (``DC``\'s) must match those from both the :setting:`net.tls.clusterFile` and :setting:`net.tls.certificateKeyFile` certificates for the other cluster members (or the :parameter:`tlsX509ClusterAuthDNOverride` value, if set). - + To match, the certificate must match all specifications of these - attributes, or even the non-specification of these attributes. The + attributes, even the non-specification of these attributes. The order of the attributes does not matter. In the following example, the two ``DN``\'s contain matching - specifications for ``O``, ``OU`` as well as the non-specification of - the ``DC`` attribute. + specifications for ``O``, ``OU`` as well as the non-specification + of the ``DC`` attribute. .. code-block:: none @@ -97,8 +95,8 @@ content: | names or IP addresses. In previous versions, MongoDB only supports comparisons of DNS names. - For example, the certificates for a cluster could have the following - subjects: + For example, the certificates for a cluster could have the + following subjects: .. code-block:: bash @@ -106,68 +104,49 @@ content: | subject= CN=,OU=Dept1,O=MongoDB,ST=NY,C=US subject= CN=,OU=Dept1,O=MongoDB,ST=NY,C=US - - *If* the certificate includes the Extended Key Usage (``extendedKeyUsage``) - setting, the value must include ``clientAuth`` ("TLS Web Client - Authentication"). + - *If* the certificate includes the Extended Key Usage + (``extendedKeyUsage``) setting, the value must include + ``clientAuth`` ("TLS Web Client Authentication"). .. code-block:: none extendedKeyUsage = clientAuth - - You can also use a certificate that does not include the Extended - Key Usage (EKU). - - The x.509 certificate must *not* be expired. - + - The x.509 certificate must *not* be expired. + .. include:: /includes/extracts/4.4-changes-certificate-expiry-warning.rst --- ref: x509-member-auth-configuration content: | - In addition to any TLS/SSL configurations as appropriate for your - deployment, include the following to specify x.509 for internal - authentication for each member of your replica set (i.e. the - :binary:`~bin.mongod` instances) or sharded cluster (i.e. the - :binary:`~bin.mongod` and :binary:`~bin.mongos` instances): + You can use TLS for internal authentication between each member of + your replica set (each :binary:`~bin.mongod` instance) or sharded + cluster (each :binary:`~bin.mongod` and :binary:`~bin.mongos` + instance). + + To use TLS for internal authentication, use the following settings: - :setting:`security.clusterAuthMode` or :option:`--clusterAuthMode ` set to ``x509`` - :setting:`net.tls.clusterFile` or :option:`--tlsClusterFile - ` (*both new in MongoDB 4.2*) - - However, if no cluster file is specified, members can use their - certificate key file specified in + ` (*available starting in MongoDB 4.2*) + + :binary:`~bin.mongod` and :option:`mongos ` instances use their certificate key file to + prove their identity to clients, but it can also be used for + membership authentication. If you do not specify a cluster file, + members use their certificate key file for membership authentication. + The certificate key file is the file you specify with :setting:`net.tls.certificateKeyFile` or :option:`--tlsCertificateKeyFile ` - (*both new in MongoDB 4.2*) for membership authentication. This - :setting:`certificate key file ` is used - by :binary:`~bin.mongod` (and :option:`mongos - `) instances to prove their identity - to clients, but can also be used for membership authentication. To - use for both client authentication and membership authentication, - the certificate must either: + (*available starting in MongoDB 4.2*). - - Omit ``extendedKeyUsage`` or + To use the :setting:`certificate key file + ` for both client authentication and + membership authentication, the certificate must either: - - Specify ``extendedKeyUsage`` values - - .. note:: - - Athough still available, :setting:`net.ssl.clusterFile` (and the - correponding :option:`--sslClusterFile `) and :setting:`net.ssl.PEMKeyFile` (and the - corresponding :option:`--sslPEMKeyFile `) - are :ref:`deprecated as of MongoDB 4.2 <4.2-tls>`. - - For deployments using MongoDB version 4.0 and earlier, use - :setting:`net.ssl.clusterFile` (or the corresponding - :option:`--sslClusterFile `) and - :setting:`net.ssl.PEMKeyFile` (or the corresponding - :option:`--sslPEMKeyFile `). - - - The x.509 certificate must *not* be expired. - - .. include:: /includes/extracts/4.4-changes-certificate-expiry-warning.rst + - Omit ``extendedKeyUsage`` or + - Specify ``extendedKeyUsage = serverAuth, clientAuth`` ... diff --git a/source/includes/fact-ssl-certificate-authorities.rst b/source/includes/fact-ssl-certificate-authorities.rst index 904b71469e3..eacaf18f476 100644 --- a/source/includes/fact-ssl-certificate-authorities.rst +++ b/source/includes/fact-ssl-certificate-authorities.rst @@ -1,6 +1,6 @@ For production use, your MongoDB deployment should use valid certificates generated and signed by a certificate authority. You or your organization can generate and maintain an independent certificate -authority, or use certificates generated by third-party TLS/SSL -vendors. Obtaining and managing certificates is beyond the scope of -this documentation. +authority, or use certificates generated by third-party TLS vendors. +Obtaining and managing certificates is beyond the scope of this +documentation. diff --git a/source/includes/list-table-3.0-driver-compatibility.rst b/source/includes/list-table-3.0-driver-compatibility.rst index e3420c82239..71c85c68203 100644 --- a/source/includes/list-table-3.0-driver-compatibility.rst +++ b/source/includes/list-table-3.0-driver-compatibility.rst @@ -9,35 +9,41 @@ * - :driver:`C ` - `1.1.0 `_ - - :driver:`Perl ` - - `1.0.0 `__ + - :driver:`PHP ` + - `1.0 `_ - * - `C++ `_ + * - :driver:`C++ ` - `1.0.0 `__ - - :driver:`PHP ` - - `1.0 `_ + - :driver:`Python ` + - `2.8 `_ * - :driver:`C# ` - `1.10 `_ - - :driver:`Python ` - - `2.8 `_ + - :driver:`Perl ` + - `1.0.0 `__ + + * - :driver:`Go ` + - `1.0.0 `__ + + - :driver:`Ruby ` + - `1.12 `_ * - :driver:`Java ` - `2.13 `_ - - :driver:`Motor ` + - :driver:`Rust ` + - `1.0.0 `__ + + * - :driver:`Motor ` - `0.4 `_ + - :driver:`Scala ` + - `2.8.0 `_ + * - :driver:`Node.js ` - `1.4.29 `_ - - :driver:`Ruby ` - - `1.12 `_ - - * - - - - - - :driver:`Scala ` - - `2.8.0 `_ + - :driver:`Swift ` + - `1.0.0 `__ diff --git a/source/includes/steps-use-x509-authentication.yaml b/source/includes/steps-use-x509-authentication.yaml new file mode 100644 index 00000000000..9086bbeb208 --- /dev/null +++ b/source/includes/steps-use-x509-authentication.yaml @@ -0,0 +1,268 @@ +stepnum: 1 +level: 4 +title: Deploy with x.509 Authentication +stepnum: 2 +level: 4 +ref: deploy-x509 +content: | + + .. _x509-deploy-tls: + + .. tabs:: + + tabs: + + - id: cmdline + name: Command Options + content: | + + You can configure a :binary:`~bin.mongod` instance for x.509 + authentication from the command-line. + + To configure a standalone :binary:`~bin.mongod` instance, run + the following command: + + .. code-block:: bash + + mongod --tlsMode requireTLS \ + --tlsCertificateKeyFile \ + --tlsCAFile --bind_ip + + Include additional options as required for your configuration. + + The x.509 configuration requires: + + .. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Option + - Notes + + * - :option:`--tlsMode ` + + - Specify ``requireTLS``. + + * - :option:`--tlsCertificateKeyFile ` + + - Specify the instance's x.509 certificate to present to + clients. + + * - :option:`--tlsCAFile ` + + - Specify the Certificate Authority file to verify the + certificates presented to the instance. + + - id: cfg + name: Configuration File + content: | + + You can configure a :binary:`~bin.mongod` for x.509 + authentication in the :doc:`configuration file + `. + + To configure a standalone :binary:`~bin.mongod` instance, add + the following configuration options to your configuration + file: + + .. code-block:: yaml + + net: + tls: + mode: requireTLS + certificateKeyFile: + CAFile: + + Include additional options as required for your configuration. + + The x.509 configuration requires: + + .. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Option + - Notes + + * - :setting:`net.tls.mode` + + - Specify ``requireTLS``. + + * - :setting:`net.tls.certificateKeyFile` + - Specify the instance's x.509 certificate to present to + clients. + + * - :setting:`net.tls.CAFile` + + - Specify the Certificate Authority file to verify the + certificates presented to the instance. + + To set up x.509 authentication for replica sets or sharded clusters, + see :ref:`x509-internal-authentication`. + +--- +title: Add x.509 Certificate ``subject`` as a User +stepnum: 2 +level: 4 +ref: x509-add-user +content: | + + .. _addX509SubjectUser: + + To authenticate with a client certificate, you must first add the value + of the ``subject`` from the client certificate as a MongoDB user to the + ``$external`` database. Each unique x.509 client certificate + corresponds to a single MongoDB user. You cannot use a single client + certificate to authenticate more than one MongoDB user. + + .. note:: Username Requirements + + - .. include:: /includes/extracts/sessions-external-username-limit.rst + + - The RDNs in the ``subject`` string must be compatible with the + `RFC2253 `_ standard. + + #. You can retrieve the ``RFC2253`` formatted ``subject`` from the + client certificate with the following command: + + .. code-block:: bash + + openssl x509 -in -inform PEM -subject -nameopt RFC2253 + + The command returns the ``subject`` string and the certificate: + + .. code-block:: bash + + subject= CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry + -----BEGIN CERTIFICATE----- + # ... + -----END CERTIFICATE----- + + + #. Add the ``RFC2253`` compliant value of the ``subject`` as a user. + Omit spaces as needed. + + The following example adds a user and grants the user + :authrole:`readWrite` role in the ``test`` database and the + :authrole:`userAdminAnyDatabase` role: + + .. code-block:: javascript + + db.getSiblingDB("$external").runCommand( + { + createUser: "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry", + roles: [ + { role: "readWrite", db: "test" }, + { role: "userAdminAnyDatabase", db: "admin" } + ], + writeConcern: { w: "majority" , wtimeout: 5000 } + } + ) + + See :doc:`/tutorial/manage-users-and-roles` for details on adding a user + with roles. +--- +title: Authenticate with a x.509 Certificate +stepnum: 3 +level: 4 +ref: x509-authenticate +content: | + + .. _authenticate-with-x509-cert: + + After you have :ref:`added the x.509 client certificate subject as a + corresponding MongoDB user `, you can + authenticate with the client certificate: + + .. tabs:: + + tabs: + + - id: connect + name: Connect with Authentication + content: | + + To authenticate during connection, run the following command: + + .. code-block:: bash + + mongosh --tls --tlsCertificateKeyFile \ + --tlsCAFile \ + --authenticationDatabase '$external' \ + --authenticationMechanism MONGODB-X509 + + .. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Option + - Notes + + * - :option:`--tls ` + - + + * - :option:`--tlsCertificateKeyFile ` + - Specify the client's x.509 file. + + * - :option:`--tlsCAFile ` + + - Specify the Certificate Authority file to verify the + certificate presented by the :binary:`~bin.mongod` + instance. + + * - :option:`--authenticationDatabase ` + - Specify ``'$external'``. + + * - :option:`--authenticationMechanism ` + - Specify ``MONGODB-X509``. + + - id: authafter + name: Authenticate after Connection + content: | + + You can connect without authentication and use the + :method:`db.auth()` method to authenticate after + connection. + + For example, if using :binary:`~bin.mongosh`, + + 1. Connect :binary:`~bin.mongosh` to the + :binary:`~bin.mongod`: + + .. code-block:: bash + + mongosh --tls --tlsCertificateKeyFile \ + --tlsCAFile + + .. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Option + - Notes + + * - :option:`--tls ` + - + + * - :option:`--tlsCertificateKeyFile ` + - Specify the client's x.509 file. + + * - :option:`--tlsCAFile ` + + - Specify the Certificate Authority file to verify + the certificate presented by the + :binary:`~bin.mongod` or :binary:`~bin.mongos` + instance. + + #. To authenticate, use the :method:`db.auth()` method in + the ``$external`` database. For the ``mechanism`` field, + specify ``"MONGODB-X509"``. + + .. code-block:: javascript + + db.getSiblingDB("$external").auth( + { + mechanism: "MONGODB-X509" + } + ) +... diff --git a/source/tutorial/configure-scram-client-authentication.txt b/source/tutorial/configure-scram-client-authentication.txt new file mode 100644 index 00000000000..b77ad4702a4 --- /dev/null +++ b/source/tutorial/configure-scram-client-authentication.txt @@ -0,0 +1,32 @@ +.. _scram-client-authentication: + +================================= +Use SCRAM to Authenticate Clients +================================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +The following procedure sets up SCRAM for client authentication on a +standalone :binary:`~bin.mongod` instance. + +To use SCRAM authentication for replica sets or sharded clusters, see +:doc:`/tutorial/deploy-replica-set-with-keyfile-access-control`. + +.. _enable-auth-procedure: + +Procedure +--------- + +.. include:: /includes/steps/create-admin-then-enable-authentication.rst + +Next Steps +---------- + +To use SCRAM authentication for replica sets or sharded clusters, see +:doc:`/tutorial/deploy-replica-set-with-keyfile-access-control`. diff --git a/source/tutorial/configure-x509-client-authentication.txt b/source/tutorial/configure-x509-client-authentication.txt index 2ea6152a09f..a50d75ad2fc 100644 --- a/source/tutorial/configure-x509-client-authentication.txt +++ b/source/tutorial/configure-x509-client-authentication.txt @@ -1,4 +1,4 @@ -.. _ x509-client-authentication: +.. _x509-client-authentication: ============================================== Use x.509 Certificates to Authenticate Clients @@ -12,18 +12,9 @@ Use x.509 Certificates to Authenticate Clients :depth: 1 :class: singlecol -.. |binary| replace:: MongoDB - -.. note:: - - .. include:: /includes/fact-tls-1.0.rst -MongoDB supports x.509 certificate authentication for use with a secure -:doc:`TLS/SSL connection `. The x.509 client -authentication allows :ref:`clients to authenticate to servers with -certificates ` rather than with a username -and password. The following tutorial outlines the steps to use x.509 -for client authentication with a standalone :binary:`~bin.mongod` instance. +The following procedure sets up x.509 certificate authentication for +client authentication on a standalone :binary:`~bin.mongod` instance. To use x.509 authentication for replica sets or sharded clusters, see :doc:`/tutorial/configure-x509-member-authentication`. @@ -31,9 +22,7 @@ To use x.509 authentication for replica sets or sharded clusters, see Prerequisites ------------- -.. important:: - - .. include:: /includes/extracts/security-prereq-configure-x509-client-authentication.rst +.. include:: /includes/extracts/security-prereq-configure-x509-client-authentication.rst Certificate Authority @@ -41,492 +30,25 @@ Certificate Authority .. include:: /includes/fact-ssl-certificate-authorities.rst -.. important:: - - .. include:: /includes/extracts/ssl-facts-x509-ca-file.rst +.. include:: /includes/extracts/ssl-facts-x509-ca-file.rst -.. _x509-client-authentication: Client x.509 Certificate ~~~~~~~~~~~~~~~~~~~~~~~~ -.. note:: - - You must have valid x.509 certificates. - - .. include:: /includes/extracts/ssl-facts-x509-invalid-certificate.rst - -.. include:: /includes/extracts/x509-certificate-client.rst - -.. _x509-deploy-tls: - -MongoDB Deployment Configured for x.509 (Using TLS Options) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - The procedures in this section use the ``tls`` settings/option - (Available in MongoDB 4.2). For procedures using their ``ssl`` - aliases, see :ref:`x509-deploy-ssl`. - - The ``tls`` settings/options provide **identical** functionality - as the ``ssl`` options since MongoDB has always supported TLS 1.0 - and later. - -.. tabs:: - - tabs: - - - id: cmdline - name: Command-Options - content: | - - You can configure a :binary:`~bin.mongod` instance - for x.509 authentication from the command-line. For example, - to configure a standalone :binary:`~bin.mongod` instance: - - .. code-block:: bash - - mongod --tlsMode requireTLS --tlsCertificateKeyFile --tlsCAFile --bind_ip - - .. include:: /includes/extracts/default-bind-ip-security-additional-command-line.rst - - The x.509 configuration requires: - - .. list-table:: - :header-rows: 1 - :widths: 25 75 - - * - Option - - Notes - - * - :option:`--tlsMode ` - - - Specify ``requireTLS``. - - * - :option:`--tlsCertificateKeyFile ` - - The instance's x.509 certificate to present to clients. - - * - :option:`--tlsCAFile ` - - - Certificate Authority file to verify the certificates - presented to the instance. - - - id: cfg - name: Configuration File - content: | - - You can configure :binary:`~bin.mongod` for x.509 - authentication in the :doc:`configuration file - `. For example, to - configure a standalone :binary:`~bin.mongod` instance: - - .. code-block:: yaml - - net: - tls: - mode: requireTLS - certificateKeyFile: - CAFile: - - .. include:: /includes/extracts/default-bind-ip-security-additional-config-file.rst - - The x.509 configuration requires: - - .. list-table:: - :header-rows: 1 - :widths: 25 75 - - * - Option - - Notes - - * - :setting:`net.tls.mode` - - - Specify ``requireTLS``. - - * - :setting:`net.tls.certificateKeyFile` - - The instance's x.509 certificate. - - * - :setting:`net.tls.CAFile` - - - Certificate Authority file to verify the certificates - presented to the instance. +You must have valid x.509 certificates. The client x.509 certificates +must meet the :ref:`client certificate requirements +`. -To set up x.509 authentication for replica sets or sharded clusters, -see :doc:`configure-x509-member-authentication`. +.. include:: /includes/extracts/ssl-facts-x509-invalid-certificate.rst +Procedure +--------- -.. _x509-deploy-ssl: +.. include:: /includes/steps/use-x509-authentication.rst -MongoDB Deployment Configured for x.509 (Using SSL Options) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - The procedures in this section use the ``ssl`` settings/option. For - procedures using their ``tls`` aliases (Available in MongoDB 4.2), - see :ref:`x509-deploy-tls`. - - The ``tls`` settings/options provide **identical** functionality - as the ``ssl`` options since MongoDB has always supported TLS 1.0 - and later. - -.. tabs:: - - tabs: - - - id: cmdline - name: Command-Options - content: | - - You can configure a :binary:`~bin.mongod` instance - for x.509 authentication from the command-line. For example, - to configure a standalone :binary:`~bin.mongod` instance: - - .. code-block:: bash - - mongod --sslMode requireSSL --sslPEMKeyFile --sslCAFile --bind_ip - - .. include:: /includes/extracts/default-bind-ip-security-additional-command-line.rst - - The x.509 configuration for a standalone requires: - - .. list-table:: - :header-rows: 1 - :widths: 25 75 - - * - Option - - Notes - - * - :option:`--sslMode ` - - - Specify ``requireSSL``. - - * - :option:`--sslPEMKeyFile ` - - The instance's x.509 certificate. - - * - :option:`--sslCAFile ` - - - Certificate Authority file to verify the certificate - presented to the instance. - - - id: cfg - name: Configuration File - content: | - - You can configure :binary:`~bin.mongod` - for x.509 authentication in the :doc:`configuration file - `. For example, - to configure a standalone :binary:`~bin.mongod` instance: - - .. code-block:: yaml - - net: - ssl: - mode: requireSSL - PEMKeyFile: - CAFile: - - .. include:: /includes/extracts/default-bind-ip-security-additional-config-file.rst - - The x.509 configuration for a standalone requires: - - .. list-table:: - :header-rows: 1 - :widths: 25 75 - - * - Option - - Notes - - * - :setting:`net.ssl.mode` - - - Specify ``requireSSL``. - - * - :setting:`net.ssl.PEMKeyFile` - - The instance's x.509 certificate. - - * - :setting:`net.ssl.CAFile` - - - Certificate Authority file to verify the certificate - presented to the instance. - -To set up x.509 authentication for replica sets or sharded clusters, -see :doc:`configure-x509-member-authentication`. - -Procedures +Next Steps ---------- -.. _addX509SubjectUser: - -Add x.509 Certificate ``subject`` as a User -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To authenticate with a client certificate, you must first add the value -of the ``subject`` from the client certificate as a MongoDB user to the -``$external`` database. Each unique x.509 client certificate -corresponds to a single MongoDB user; i.e. you cannot use a single -client certificate to authenticate more than one MongoDB user. - -.. include:: /includes/extracts/sessions-external-username-limit.rst - -.. note:: - - The RDNs in the ``subject`` string must be compatible with the - `RFC2253 `_ standard. - -#. You can retrieve the ``RFC2253`` formatted ``subject`` from the client - certificate with the following command: - - .. code-block:: bash - - openssl x509 -in -inform PEM -subject -nameopt RFC2253 - - The command returns the ``subject`` string as well as certificate: - - .. code-block:: bash - - subject= CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry - -----BEGIN CERTIFICATE----- - # ... - -----END CERTIFICATE----- - - - -#. Add the ``RFC2253`` compliant value of the ``subject`` as a user. - Omit spaces as needed. - - For example, the following adds a user and grants the user - :authrole:`readWrite` role in the ``test`` database and the - :authrole:`userAdminAnyDatabase` role: - - .. code-block:: javascript - - db.getSiblingDB("$external").runCommand( - { - createUser: "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry", - roles: [ - { role: "readWrite", db: "test" }, - { role: "userAdminAnyDatabase", db: "admin" } - ], - writeConcern: { w: "majority" , wtimeout: 5000 } - } - ) - -See :doc:`/tutorial/manage-users-and-roles` for details on adding a user -with roles. - -.. _authenticate-with-x509-cert: - -Authenticate with a x.509 Certificate (Using ``tls`` Options) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - The procedures in this section use the ``tls`` settings/option - (Available in MongoDB 4.2). For procedures using their ``ssl`` - aliases, see :ref:`authenticate-with-x509-cert-ssl`. - - The ``tls`` settings/options provide **identical** functionality - as the ``ssl`` options since MongoDB has always supported TLS 1.0 - and later. - -After you have :ref:`added the x.509 client certificate subject as a -corresponding MongoDB user `, you can -authenticate with the client certificate. - -.. tabs:: - - tabs: - - - id: connect - name: Connect with Authentication - content: | - - To authenticate during connection: - - .. code-block:: bash - - mongosh --tls --tlsCertificateKeyFile --tlsCAFile --authenticationDatabase '$external' --authenticationMechanism MONGODB-X509 - - .. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Option - - Notes - - * - :option:`--tls ` - - - - * - :option:`--tlsCertificateKeyFile ` - - Client's x.509 file. - - * - :option:`--tlsCAFile ` - - - Certificate Authority file to verify the - certificate presented by the - :binary:`~bin.mongod` - instance. - - * - :option:`--authenticationDatabase ` - - Specify ``'$external'``. - - * - :option:`--authenticationMechanism ` - - Specify ``MONGODB-X509``. - - - id: authafter - name: Authenticate after Connection - content: | - - You can connect without authentication and use the - :method:`db.auth()` method to authenticate after - connection. - - For example, if using :binary:`~bin.mongosh`, - - 1. Connect :binary:`~bin.mongosh` to the :binary:`~bin.mongod` set up for - TLS/SSL: - - .. code-block:: bash - - mongosh --tls --tlsCertificateKeyFile --tlsCAFile - - .. list-table:: - :header-rows: 1 - :widths: 25 75 - - * - Option - - Notes - - * - :option:`--tls ` - - - - * - :option:`--tlsCertificateKeyFile ` - - Client's x.509 file. - - * - :option:`--tlsCAFile ` - - - Certificate Authority file to verify the - certificate presented by - :binary:`~bin.mongod`/:binary:`~bin.mongos` - instance. - - #. To perform the authentication, use the :method:`db.auth()` method in - the ``$external`` database. For the ``mechanism`` - field, specify ``"MONGODB-X509"``. - - .. code-block:: javascript - - db.getSiblingDB("$external").auth( - { - mechanism: "MONGODB-X509" - } - ) - -.. _authenticate-with-x509-cert-ssl: - -Authenticate with a x.509 Certificate (Using ``ssl`` Options) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - The procedures in this section use the ``ssl`` settings/options. For - procedures using their ``tls`` (Available in MongoDB 4.2) aliases, - see :ref:`authenticate-with-x509-cert`. - - The ``tls`` settings/options provide **identical** functionality - as the ``ssl`` options since MongoDB has always supported TLS 1.0 - and later. - -After you have :ref:`added the x.509 client certificate subject as a -corresponding MongoDB user `, you can -authenticate with the client certificate. - -.. tabs:: - - tabs: - - - id: connect - name: Connect with Authentication - content: | - - To authenticate during connection: - - .. code-block:: bash - - mongosh --ssl --sslPEMKeyFile --sslCAFile --authenticationDatabase '$external' --authenticationMechanism MONGODB-X509 - - .. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Option - - Notes - - * - ``--ssl`` - - - - * - ``--sslPEMKeyFile`` - - Client's x.509 file. - - * - ``--sslCAFile`` - - - Certificate Authority file to verify the - certificate presented by - :binary:`~bin.mongod`/:binary:`~bin.mongos` - instance. - - * - :option:`--authenticationDatabase ` - - Specify ``'$external'``. - - * - :option:`--authenticationMechanism ` - - Specify ``MONGODB-X509``. - - - id: authafter - name: Authenticate after Connection - content: | - - You can connect without authentication and use the - :method:`db.auth()` method to authenticate after - connection. - - For example, if using :binary:`~bin.mongosh`, - - 1. Connect :binary:`~bin.mongosh` to the :binary:`~bin.mongod` set up for - TLS/SSL: - - .. code-block:: bash - - mongosh --ssl --sslPEMKeyFile --sslCAFile - - .. list-table:: - :header-rows: 1 - :widths: 25 75 - - * - Option - - Notes - - * - ``--ssl`` - - - - * - ``--sslPEMKeyFile`` - - Client's x.509 file. - - * - ``--sslCAFile`` - - - Certificate Authority file to verify the - certificate presented by - :binary:`~bin.mongod`/:binary:`~bin.mongos` - instance. - - #. To perform the authentication, use the :method:`db.auth()` method in - the ``$external`` database. For the ``mechanism`` - field, specify ``"MONGODB-X509"``. - - .. code-block:: javascript - - db.getSiblingDB("$external").auth( - { - mechanism: "MONGODB-X509" - } - ) +To use x.509 authentication for replica sets or sharded clusters, see +:doc:`/tutorial/configure-x509-member-authentication`. diff --git a/source/tutorial/enable-authentication.txt b/source/tutorial/enable-authentication.txt index e1b96235d36..99da6affbaf 100644 --- a/source/tutorial/enable-authentication.txt +++ b/source/tutorial/enable-authentication.txt @@ -17,11 +17,17 @@ With access control enabled, users are required to identify themselves and can only perform actions that adhere to the permissions granted by the roles assigned to their user. -The following tutorial enables access control for a standalone -:binary:`~bin.mongod` instance and uses the :ref:`default -authentication mechanism `. For more -information about other authentication mechanisms, see -:ref:`available-authentication-mechanisms`. +If you would like to enable access control for a standalone MongoDB +instance, please refer to one of the following resources: + +- :doc:`/tutorial/configure-scram-client-authentication` +- :doc:`/tutorial/configure-x509-client-authentication` +- :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` +- :doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication` +- :doc:`/tutorial/kerberos-auth-activedirectory-authz` +- :doc:`/tutorial/configure-ldap-sasl-activedirectory` +- :doc:`/tutorial/configure-ldap-sasl-openldap` +- :doc:`/tutorial/authenticate-nativeldap-activedirectory` If you would like to enable access control for a :doc:`replica set ` or a :doc:`sharded cluster `, please refer to @@ -33,17 +39,12 @@ one of the following resources: - :doc:`/tutorial/deploy-sharded-cluster-with-keyfile-access-control` - :doc:`/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster` - :doc:`/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime` - -.. _enable-auth-procedure: - -Enable Access Control for a Standalone ``mongod`` Instance ----------------------------------------------------------- - -.. seealso:: - - :ref:`available-authentication-mechanisms` - -.. include:: /includes/steps/create-admin-then-enable-authentication.rst +- :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` +- :doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication` +- :doc:`/tutorial/kerberos-auth-activedirectory-authz` +- :doc:`/tutorial/configure-ldap-sasl-activedirectory` +- :doc:`/tutorial/configure-ldap-sasl-openldap` +- :doc:`/tutorial/authenticate-nativeldap-activedirectory` Next Steps ---------- From f7496beaa9178df8572c505667efb0dad9328086 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Thu, 26 Aug 2021 14:04:28 +0200 Subject: [PATCH 058/109] DOCSP-18271: Add list users page --- source/core/security-users.txt | 1 + source/tutorial/list-users.txt | 42 ++++++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 source/tutorial/list-users.txt diff --git a/source/core/security-users.txt b/source/core/security-users.txt index cea3991ac0c..4ac929a0021 100644 --- a/source/core/security-users.txt +++ b/source/core/security-users.txt @@ -142,3 +142,4 @@ general, clients should connect to the sharded cluster through the /tutorial/create-users /tutorial/authenticate-a-user + /tutorial/list-users diff --git a/source/tutorial/list-users.txt b/source/tutorial/list-users.txt new file mode 100644 index 00000000000..622ced8fcdb --- /dev/null +++ b/source/tutorial/list-users.txt @@ -0,0 +1,42 @@ +.. _list-users: + +========== +List Users +========== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 3 + :class: singlecol + +To list all users, use :binary:`~bin.mongosh` to query the +:doc:`system.users ` collection: + +.. code-block:: sh + + use admin + db.system.users.find() + +.. important:: + + Do not modify the :doc:`system.users + ` collection directly. To manage + users, use the designated :ref:`user management commands + `. + +To list all users of a :doc:`sharded cluster ` that were +created through a :binary:`~bin.mongos`, connect to a +:binary:`~bin.mongos` and run the preceding command. MongoDB stores +users that are created through a :binary:`~bin.mongos` in the ``admin`` +database of the :term:`config servers `. + +To list all :ref:`shard local users +`, connect to the respective shard directly and run +the preceding command. MongoDB stores *shard local* users in the +``admin`` database of the shard itself. These *shard local* users are +independent from the users added to the sharded cluster through a +:binary:`~bin.mongos`. *Shard local* users are local to the shard and +are inaccessible to :binary:`~bin.mongos`. From c8e4adac6aa9f3f46b6e5992b9789094cfada4d0 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Fri, 3 Sep 2021 16:34:13 +0200 Subject: [PATCH 059/109] DOCSP-18011: Refactor Enterprise Auth structure --- config/redirects | 8 ++ .../authentication-mechanisms-enterprise.txt | 89 ------------------ source/core/authentication-mechanisms.txt | 65 ------------- source/core/authentication.txt | 94 ++++++++++++++++--- source/core/authorization.txt | 11 +++ 5 files changed, 101 insertions(+), 166 deletions(-) delete mode 100644 source/core/authentication-mechanisms-enterprise.txt delete mode 100644 source/core/authentication-mechanisms.txt diff --git a/config/redirects b/config/redirects index 0794caeb3df..c9f079850bf 100644 --- a/config/redirects +++ b/config/redirects @@ -1879,6 +1879,14 @@ raw: /manual/core/wildcard -> ${base}/manual/core/index-wildcard/ [v5.0-*]: /${version}/reference/read-concern-majority/#disable-read-concern-majority -> ${base}/${version}/reference/read-concern-majority/#primary-secondary-arbiter-replica-sets + +# +# Redirects for 5.1 and greater (if pages are removed in 5.0 that used to exist in earlier versions) +# + +[v5.0-*]: /${version}/core/core/authentication-mechanisms -> ${base}/${version}/core/authentication + + # # Upgrade / Downgrade redirects # diff --git a/source/core/authentication-mechanisms-enterprise.txt b/source/core/authentication-mechanisms-enterprise.txt deleted file mode 100644 index d4f02d35bc5..00000000000 --- a/source/core/authentication-mechanisms-enterprise.txt +++ /dev/null @@ -1,89 +0,0 @@ -==================================== -Enterprise Authentication Mechanisms -==================================== - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -In addition to the authentication mechanisms offered in MongoDB -Community, MongoDB Enterprise provides integration with the following -external authentication mechanisms. - -.. _security-auth-kerberos: - -Kerberos Authentication ------------------------ - -`MongoDB Enterprise `_ -supports authentication using a Kerberos service. Kerberos is an industry -standard authentication protocol for large client/server systems. - -To use MongoDB with Kerberos, you must have a properly configured -Kerberos deployment, configured :ref:`Kerberos service principals -` for MongoDB, and added :ref:`Kerberos -user principal ` to MongoDB. - -For more information on Kerberos and MongoDB, see: - -- :doc:`/core/kerberos`, - -- :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` and - -- :doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication`. - -.. _security-auth-ldap: - -LDAP Proxy Authentication -------------------------- - - -`MongoDB Enterprise -`_ supports -proxy authentication through a Lightweight Directory Access Protocol -(LDAP) service. - -.. versionchanged:: 3.4 - - MongoDB 3.4 supports using operating system libraries instead of the - `saslauthd `_ - daemon, allowing MongoDB 3.4 servers running on Linux and Microsoft Windows - to connect to LDAP servers. Linux MongoDB deployments continue to support - ``saslauthd``. - -Previous versions of MongoDB support authentication against an LDAP server -using simple and SASL binding via ``saslauthd``. This restricted LDAP -authentication support to only Linux MongoDB deployments. - -See :doc:`/core/security-ldap` for more information. - -LDAP Authorization -~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 3.4 - -MongoDB Enterprise supports querying an LDAP server for the LDAP groups the -authenticated user is a member of. MongoDB maps the Distinguished Names (DN) -of each returned group to :ref:`roles ` on the ``admin`` database. -MongoDB authorizes the user based on the mapped roles and their associated -privileges. See :ref:`LDAP Authorization ` for more -information. - -.. seealso:: - - - :doc:`/core/security-ldap` - - :doc:`/tutorial/configure-ldap-sasl-openldap` - - :doc:`/tutorial/configure-ldap-sasl-activedirectory` - -.. toctree:: - :titlesonly: - :hidden: - - /core/kerberos - /core/security-ldap - /core/security-ldap-external - diff --git a/source/core/authentication-mechanisms.txt b/source/core/authentication-mechanisms.txt deleted file mode 100644 index 88166e441cf..00000000000 --- a/source/core/authentication-mechanisms.txt +++ /dev/null @@ -1,65 +0,0 @@ -.. _security-authentication-mechanisms: - -========================= -Authentication Mechanisms -========================= - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - - -MongoDB supports the following authentication mechanisms: - -- :doc:`SCRAM Authentication ` (*Default*) - -- :doc:`x.509 Certificate Authentication `. - -In addition, MongoDB Enterprise provides integration with a number of -external authentication mechanisms, including Kerberos and LDAP. See -:doc:`/core/authentication-mechanisms-enterprise` for the additional -authentication mechanisms supported by MongoDB Enterprise. - -.. _authentication-mechanism-default: - -SCRAM Authentication --------------------- - -Salted Challenge Response Authentication Mechanism (SCRAM) is the -default authentication mechanism for MongoDB. - -For more information on SCRAM and MongoDB, see: - -- :doc:`SCRAM Authentication ` -- :ref:`scram-client-authentication` - -.. _authentication-mechanism-x509: - -x.509 Certificate Authentication --------------------------------- - -MongoDB supports x.509 certificate authentication for client -authentication and internal authentication of the members of replica -sets and sharded clusters. x.509 certificate authentication requires a -secure :doc:`TLS/SSL connection `. - -To use MongoDB with x.509, you must use valid certificates generated and -signed by a certificate authority. The client x.509 certificates -must meet the :ref:`client certificate requirements -`. - -For more information on x.509 and MongoDB, see: - -- :doc:`x.509 Certificate Authentication ` -- :ref:`x509-client-authentication` - -.. toctree:: - :titlesonly: - :hidden: - - /core/security-scram - /core/security-x.509 diff --git a/source/core/authentication.txt b/source/core/authentication.txt index 10f882b8f12..d4230bc36ab 100644 --- a/source/core/authentication.txt +++ b/source/core/authentication.txt @@ -34,22 +34,90 @@ To get started using access control, follow these tutorials: - :ref:`authentication-auth-as-user` .. _available-authentication-mechanisms: +.. _security-authentication-mechanisms: Authentication Mechanisms ------------------------- -MongoDB Community supports a number of :ref:`authentication mechanisms -` that clients can use to verify -their identity: +.. _authentication-mechanism-default: -- :ref:`authentication-scram` (*Default*) -- :ref:`x.509 Certificate Authentication `. +SCRAM Authentication +~~~~~~~~~~~~~~~~~~~~ -In addition to the preceding mechanisms, MongoDB Atlas and MongoDB -Enterprise support the following mechanisms: +:doc:`Salted Challenge Response Authentication Mechanism (SCRAM) +` is the default authentication mechanism for +MongoDB. -- :ref:`LDAP proxy authentication `, and -- :ref:`Kerberos authentication `. +For more information on SCRAM and MongoDB, see: + +- :doc:`SCRAM Authentication ` +- :ref:`scram-client-authentication` + +.. _authentication-mechanism-x509: + +x.509 Certificate Authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MongoDB supports :doc:`x.509 certificate authentication +` for client authentication and internal +authentication of the members of replica sets and sharded clusters. +x.509 certificate authentication requires a secure :doc:`TLS/SSL +connection `. + +To use MongoDB with x.509, you must use valid certificates generated and +signed by a certificate authority. The client x.509 certificates +must meet the :ref:`client certificate requirements +`. + +For more information on x.509 and MongoDB, see: + +- :doc:`x.509 Certificate Authentication ` +- :ref:`x509-client-authentication` + +.. _security-auth-kerberos: + +Kerberos Authentication +~~~~~~~~~~~~~~~~~~~~~~~ + +`MongoDB Enterprise +`_ +and `MongoDB Atlas +`__ support +:doc:`Kerberos Authentication `. Kerberos is an industry +standard authentication protocol for large client/server systems that +provides authentication using short-lived tokens that are called +tickets. + +To use MongoDB with Kerberos, you must have a properly configured +Kerberos deployment, configured :ref:`Kerberos service principals +` for MongoDB, and a :ref:`Kerberos user +principal ` added to MongoDB. + +For more information on Kerberos and MongoDB, see: + +- :doc:`Kerberos Authentication ` +- :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` +- :doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication` + +.. _security-auth-ldap: + +LDAP Proxy Authentication +~~~~~~~~~~~~~~~~~~~~~~~~~ + +`MongoDB Enterprise +`_ +and `MongoDB Atlas +`__ support +:doc:`LDAP Proxy Authentication ` proxy +authentication through a Lightweight Directory Access Protocol (LDAP) +service. + +For more information on Kerberos and MongoDB, see: + +- :doc:`LDAP Proxy Authentication ` +- :doc:`/tutorial/configure-ldap-sasl-activedirectory` +- :doc:`/tutorial/configure-ldap-sasl-openldap` +- :doc:`/tutorial/authenticate-nativeldap-activedirectory` These mechanisms allow MongoDB to integrate into your existing authentication system. @@ -68,8 +136,10 @@ for more information. :titlesonly: :hidden: - /core/security-users - /core/authentication-mechanisms - /core/authentication-mechanisms-enterprise + /core/security-scram + /core/security-x.509 + /core/kerberos + /core/security-ldap /core/security-internal-authentication /core/localhost-exception + /core/security-users diff --git a/source/core/authorization.txt b/source/core/authorization.txt index 45ad2fbe4e4..9e3d13d2f4a 100644 --- a/source/core/authorization.txt +++ b/source/core/authorization.txt @@ -103,6 +103,16 @@ If these built-in-roles cannot provide the desired set of privileges, MongoDB provides methods to create and modify :doc:`user-defined roles `. +LDAP Authorization +------------------ + +MongoDB Enterprise supports querying an LDAP server for the LDAP groups the +authenticated user is a member of. MongoDB maps the Distinguished Names (DN) +of each returned group to :ref:`roles ` on the ``admin`` database. +MongoDB authorizes the user based on the mapped roles and their associated +privileges. See :ref:`LDAP Authorization ` for more +information. + .. toctree:: :titlesonly: :hidden: @@ -112,3 +122,4 @@ MongoDB provides methods to create and modify :doc:`user-defined roles /tutorial/manage-users-and-roles /tutorial/change-own-password-and-custom-data /core/collection-level-access-control + /core/security-ldap-external From ae0e219fc95da8a4e853a840f3cf80e07cdd2822 Mon Sep 17 00:00:00 2001 From: jason-price-mongodb Date: Mon, 20 Sep 2021 16:20:50 -0700 Subject: [PATCH 060/109] DOCS-14609 SBE order projection fields --- source/core/document.txt | 31 +++++++++++++++++++++ source/includes/fact-update-field-order.rst | 4 +-- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/source/core/document.txt b/source/core/document.txt index b0761476f9c..605220c32d4 100644 --- a/source/core/document.txt +++ b/source/core/document.txt @@ -199,6 +199,37 @@ Document Size Limit Document Field Order ~~~~~~~~~~~~~~~~~~~~ +Unlike JavaScript objects, the fields in a BSON document are ordered. + +Field Order in Queries +`````````````````````` + +For queries, the field order behavior is as follows: + +- When comparing documents, field ordering is significant. For + example, when comparing documents with fields ``a`` and ``b`` in a + query: + + - ``{a: 1, b: 1}`` is equal to ``{a: 1, b: 1}`` + + - ``{a: 1, b: 1}`` is not equal to ``{b: 1, a: 1}`` + +- For efficient query execution, the query engine may reorder fields + during query processing. Among other cases, reordering fields may + occur when processing these projection operators: + :pipeline:`$project`, :pipeline:`$addFields`, :pipeline:`$set`, and + :pipeline:`$unset`. + + - Field reordering may occur in intermediate results as well as the + final results returned by a query. + + - Because some operations may reorder fields, you should not rely on + specific field ordering in the results returned by a query that + uses the projection operators listed earlier. + +Field Order in Write Operations +``````````````````````````````` + .. include:: /includes/fact-update-field-order.rst :start-after: order-of-document-fields diff --git a/source/includes/fact-update-field-order.rst b/source/includes/fact-update-field-order.rst index 179752df4d6..c87dd51cd83 100644 --- a/source/includes/fact-update-field-order.rst +++ b/source/includes/fact-update-field-order.rst @@ -1,7 +1,7 @@ .. order-of-document-fields -MongoDB preserves the order of the document fields following write -operations *except* for the following cases: +For write operations, MongoDB preserves the order of the document fields +*except* for the following cases: - The ``_id`` field is always the first field in the document. From 015e130e9302c2c590f654ae47adc425a28e9645 Mon Sep 17 00:00:00 2001 From: Dave Cuthbert Date: Tue, 24 Aug 2021 14:13:47 -0400 Subject: [PATCH 061/109] DOCSP-16018 install guide for online audit --- ...act-enable-runtime-audit-configuration.rst | 27 +++++++ .../includes/steps-5.0-downgrade-mongod.yaml | 11 ++- source/release-notes/5.0-compatibility.txt | 3 +- .../5.0-downgrade-replica-set.txt | 30 +++++++- .../5.0-downgrade-sharded-cluster.txt | 9 ++- .../5.0-downgrade-standalone.txt | 10 ++- .../release-notes/5.0-upgrade-replica-set.txt | 2 +- source/release-notes/5.0.txt | 9 ++- source/tutorial/configure-audit-filters.txt | 13 +--- source/tutorial/configure-auditing.txt | 77 ++++++++++++++++++- source/tutorial/upgrade-revision.txt | 12 ++- 11 files changed, 172 insertions(+), 31 deletions(-) create mode 100644 source/includes/fact-enable-runtime-audit-configuration.rst diff --git a/source/includes/fact-enable-runtime-audit-configuration.rst b/source/includes/fact-enable-runtime-audit-configuration.rst new file mode 100644 index 00000000000..21f3e16c7df --- /dev/null +++ b/source/includes/fact-enable-runtime-audit-configuration.rst @@ -0,0 +1,27 @@ +Starting in MongoDB 5.0, audit configurations for :binary:`~bin.mongod` +and :binary:`~bin.mongos` nodes can be configured at runtime. A group +of these nodes can take part in a distributed audit configuration. + +To include a node in a distributed audit configuration, update the +node's configuration file as follows and restart the server. + +.. list-table:: + :header-rows: 1 + + * - Parameter + - Value + * - :setting:`auditLog.runtimeConfiguration` + - ``true`` + * - :setting:`auditLog.filter` + - Unset + * - :parameter:`auditAuthorizationSuccess` + - Unset + +The server logs an error and fails to start if: + +- ``runtimeConfiguration`` is ``true`` and +- either :setting:`auditLog.filter` or :parameter:`auditAuthorizationSuccess` is set. + +To modify audit filters and the :parameter:`auditAuthorizationSuccess` parameter at +runtime, see :dbcommand:`setAuditConfig`. + diff --git a/source/includes/steps-5.0-downgrade-mongod.yaml b/source/includes/steps-5.0-downgrade-mongod.yaml index c3364828113..a5edf657a7e 100644 --- a/source/includes/steps-5.0-downgrade-mongod.yaml +++ b/source/includes/steps-5.0-downgrade-mongod.yaml @@ -26,6 +26,15 @@ content: | :binary:`~bin.mongod` completes all pending operations, flushes all data to data files, and closes all data files. --- +title: "Update configuration files." +level: 4 +ref: 5.0-downgrade-configuration-files +content: | + + Disable any configurable |newversion| features by updating the + :binary:`~bin.mongod` instance's configuration file before + restarting. +--- title: "Restart with the latest |oldversion| ``mongod`` instance." level: 4 ref: 5.0-downgrade-restart-instance @@ -33,5 +42,5 @@ content: | Replace the |newversion| binary with the downloaded |oldversion| :binary:`~bin.mongod` binary and restart. - + ... diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt index c7d9ec95b92..974cc155ca1 100644 --- a/source/release-notes/5.0-compatibility.txt +++ b/source/release-notes/5.0-compatibility.txt @@ -483,7 +483,8 @@ features include: - Creation of :ref:`time series collections ` requires fCV set to 5.0+. -- Configuring Runtime Audit Filter Management requires fCV set to 5.0+. +- :ref:`Configuring Runtime Audit Filter Management + ` requires fCV set to 5.0+. - Usage of ``.`` and ``$`` in field names requires fCV set to 5.0+. diff --git a/source/release-notes/5.0-downgrade-replica-set.txt b/source/release-notes/5.0-downgrade-replica-set.txt index 471a0e3da4b..3cc159574f4 100644 --- a/source/release-notes/5.0-downgrade-replica-set.txt +++ b/source/release-notes/5.0-downgrade-replica-set.txt @@ -151,9 +151,33 @@ Time-series Collections `. Runtime Audit Filter Management - Disable runtime audit filter management by setting the - ``auditLog.runtimeConfiguration`` configuration file setting to - ``false``. + +- Reset the defaults on the :term:`primary` server in the group with + ``db.admin.runCommand``. The primary should be the last + configuration server in the group to be updated. + + .. code-block:: javascript + + db.admin.runCommand( + { + setAuditConfig: 1, + filter: {}, + auditAuthorizationSuccess: false + } + ) + + The configuration document can also be removed after downgrade: + + .. code-block:: javascript + + config.settings.remove({_id: 'audit'}); + +- Disable Runtime Audit Filter Management on each node by setting + ``auditLog.runtimeConfiguration`` to ``false`` in the node's + configuration file. + +- Update the audit filters for this instance in the local + configuration file. .. |binary| replace:: any replica set member diff --git a/source/release-notes/5.0-downgrade-sharded-cluster.txt b/source/release-notes/5.0-downgrade-sharded-cluster.txt index 55e7a02cb0b..ddb7deffa6f 100644 --- a/source/release-notes/5.0-downgrade-sharded-cluster.txt +++ b/source/release-notes/5.0-downgrade-sharded-cluster.txt @@ -179,9 +179,12 @@ Time-series Collections `. Runtime Audit Filter Management - Disable runtime audit filter management by setting the - ``auditLog.runtimeConfiguration`` configuration file setting to - ``false``. + - Disable Runtime Audit Filter Management by setting + ``auditLog.runtimeConfiguration`` to ``false`` in the node's + configuration file. + + - Update the audit filters for this :binary:`~bin.mongod` or + :binary:`~bin.mongos` instance in the local configuration file. 7. Remove |newversion| Features ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/release-notes/5.0-downgrade-standalone.txt b/source/release-notes/5.0-downgrade-standalone.txt index 575c105c176..092e9010679 100644 --- a/source/release-notes/5.0-downgrade-standalone.txt +++ b/source/release-notes/5.0-downgrade-standalone.txt @@ -107,9 +107,12 @@ Time-series Collections `. Runtime Audit Filter Management - Disable runtime audit filter management by setting the - ``auditLog.runtimeConfiguration`` configuration file setting to - ``false``. + - Disable Runtime Audit Filter Management by setting + ``auditLog.runtimeConfiguration`` to ``false`` in the node's + configuration file. + + - Update the audit filters for this instance in the local + configuration file. .. |binary| replace:: the :binary:`~bin.mongod` instance @@ -132,3 +135,4 @@ Procedure prerequisites have been completed. .. include:: /includes/steps/5.0-downgrade-mongod.rst + diff --git a/source/release-notes/5.0-upgrade-replica-set.txt b/source/release-notes/5.0-upgrade-replica-set.txt index 2ff72aba373..7b60c666438 100644 --- a/source/release-notes/5.0-upgrade-replica-set.txt +++ b/source/release-notes/5.0-upgrade-replica-set.txt @@ -35,7 +35,7 @@ All Members Version All replica set members must be running version |oldversion|. To upgrade a replica set from an |olderseries| and earlier, *first* :doc:`upgrade all members of the replica set to the latest -4.2-series release `, and +5.0-series release `, and then follow the procedure to upgrade from MongoDB |oldversion| to |newversion|. diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 9a9a0b24198..bb327ed48c3 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -242,7 +242,11 @@ See :ref:`lookup-uncorrelated-subquery`. Auditing -------- -MongDB 5.0 adds the ability to configure auditing filters at runtime. +Runtime Audit Filter Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MongoDB 5.0 adds the ability to :ref:`configure auditing filters +` at runtime. .. list-table:: :header-rows: 1 @@ -262,6 +266,9 @@ MongDB 5.0 adds the ability to configure auditing filters at runtime. - Sets new audit configurations for :binary:`~bin.mongod` and :binary:`~bin.mongos` instances at runtime. +General Auditing Updates +~~~~~~~~~~~~~~~~~~~~~~~~ + Starting in MongoDB 5.0: - :ref:`System event auditing ` has: diff --git a/source/tutorial/configure-audit-filters.txt b/source/tutorial/configure-audit-filters.txt index b09d9bed348..7e1dbf83bbd 100644 --- a/source/tutorial/configure-audit-filters.txt +++ b/source/tutorial/configure-audit-filters.txt @@ -39,18 +39,7 @@ configured to allow Filter Configuration at Runtime ------------------------------- -Starting in MongDB 5.0, a :binary:`~bin.mongod` or -:binary:`~bin.mongos` instance can be part of a distributed audit -configuration. Audit filters on these nodes can be configured at -runtime using the :dbcommand:`setAuditConfig` command. A node will be -included in the distributed audit configuration if: - -- :setting:`auditLog.runtimeConfiguration` is ``true``, -- :setting:`auditLog.filter` is not set, and -- :parameter:`auditAuthorizationSuccess` is not set - -When ``runtimeConfiguration`` is ``true``, the server will log an error -and fail to start if either one of the other variables is set. +.. include:: /includes/fact-enable-runtime-audit-configuration.rst .. _configure-audit-filters-at-startup: diff --git a/source/tutorial/configure-auditing.txt b/source/tutorial/configure-auditing.txt index 7390770b9c8..93714b76a49 100644 --- a/source/tutorial/configure-auditing.txt +++ b/source/tutorial/configure-auditing.txt @@ -228,16 +228,87 @@ You may also specify these options in the :doc:`configuration file format: BSON path: data/db/auditLog.bson -To view the contents of the file, pass the file to the MongoDB utility -:binary:`~bin.bsondump`. For example, the following converts the audit log -into a human-readable form and output to the terminal: +The following example converts the audit log into readable form using +:binary:`~bin.bsondump` and outputs the result: .. code-block:: bash bsondump data/db/auditLog.bson +.. _runtime-audit-configuration: + +Runtime Audit Filter Management +------------------------------- + +Starting in MongoDB 5.0, audit filters can be configured at runtime. +Runtime Audit Filter Management provides three benefits compared to +audit filter configurations that are specified in a local +:binary:`~bin.mongod` or :binary:`~bin.mongos` configuration file: + +- :ref:`rafm-separation` +- :ref:`rafm-configurability` +- :ref:`rafm-consistency` + +.. _rafm-separation: + +Separation of Concerns +~~~~~~~~~~~~~~~~~~~~~~ + +Prior to MongoDB 5.0, anyone auditing a MongoDB :binary:`~bin.mongod` +or :binary:`~bin.mongos` instance had to have write access to the host +server's file system in order to update audit filters. Runtime Audit +Filter Management improves security by separating audit access from +administrative access. + +Using Runtime Audit Filter Management instead of editing configuration +files directly means: + +- File system access is not required so an auditor does not need access + to the :binary:`~bin.mongod` or :binary:`~bin.mongos` host server. + +- There is no direct access to the :binary:`~bin.mongod` or + :binary:`~bin.mongos` instance's configuration file. + +- Runtime Audit Filter Management only exposes :ref:`audit filters + ` and the :parameter:`auditAuthorizationSuccess` + parameter. + +.. _rafm-configurability: + +Runtime Configurability +~~~~~~~~~~~~~~~~~~~~~~~ + +Starting in MongoDB 5.0, when Runtime Audit Filter Management is +enabled, auditing can be reconfigured at runtime without restarting the +:binary:`~bin.mongod` or :binary:`~bin.mongos` instance. A statically +configured instance has to be restarted to update its audit settings. + +Audit filter modifications made at runtime persist when an instance is +shutdown and restarted. + +.. _rafm-consistency: + +Consistency +~~~~~~~~~~~ + +Within a cluster, if all participating :binary:`~bin.mongod` and +:binary:`~bin.mongos` nodes are configured to use Runtime Audit Filter +Management, then every node will use the same audit filters. In +contrast, if each node has its own locally configured audit filters, +there is no guarantee of audit filter consistency across nodes. + +.. _rafm-enable: + +Enable Runtime Audit Filter Management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/fact-enable-runtime-audit-configuration.rst + .. seealso:: - :doc:`/tutorial/configure-audit-filters` - :doc:`/core/auditing` - :doc:`/reference/audit-message` + - :dbcommand:`setAuditConfig` + - :dbcommand:`getAuditConfig` + diff --git a/source/tutorial/upgrade-revision.txt b/source/tutorial/upgrade-revision.txt index 125e994199a..50124278581 100644 --- a/source/tutorial/upgrade-revision.txt +++ b/source/tutorial/upgrade-revision.txt @@ -96,7 +96,8 @@ Follow this upgrade procedure: #. Upgrade sharded clusters, as described in :ref:`upgrade-sharded-cluster`. -#. Upgrade any standalone instances. See :ref:`upgrade-mongodb-instance`. +#. Upgrade any standalone instances. See + :ref:`upgrade-mongodb-instance`. #. Upgrade any replica sets that are not part of a sharded cluster, as described in :ref:`upgrade-replica-set`. @@ -106,8 +107,8 @@ Follow this upgrade procedure: Upgrade a MongoDB Instance -------------------------- -To upgrade a :binary:`~bin.mongod` or :binary:`~bin.mongos` instance, use one -of the following approaches: +To upgrade a :binary:`~bin.mongod` or :binary:`~bin.mongos` instance, +use one of these approaches: - Upgrade the instance using the operating system's package management tool and the official MongoDB packages. This is the preferred @@ -116,6 +117,9 @@ of the following approaches: - Upgrade the instance by replacing the existing binaries with new binaries. See :ref:`upgrade-replace-binaries`. +- Make any required configuration file changes before restarting the + instance. + .. _upgrade-replace-binaries: Replace the Existing Binaries @@ -140,6 +144,8 @@ replacing the existing binaries: #. Replace the existing MongoDB binaries with the downloaded binaries. +#. Make any required configuration file changes. + #. Restart the instance. .. _`MongoDB Download Page`: https://www.mongodb.com/try/download/community?tck=docs_server From 216155409a578f5f1265e64149c124b4e74ac3c0 Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Tue, 28 Sep 2021 16:51:28 -0400 Subject: [PATCH 062/109] (DOCS-14817): Add release date for 4.2.17 --- source/release-notes/4.2.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/release-notes/4.2.txt b/source/release-notes/4.2.txt index f120544e6b4..c2041652a5a 100644 --- a/source/release-notes/4.2.txt +++ b/source/release-notes/4.2.txt @@ -15,8 +15,8 @@ Minor Releases .. _4.2.17-release-notes: -4.2.17 - Upcoming -~~~~~~~~~~~~~~~~~ +4.2.17 - Sep 28, 2021 +~~~~~~~~~~~~~~~~~~~~~ - :issue:`SERVER-59876`: Large delays in returning from libcrypto.so while establishing egress connections From 0858bf0ebd4e0c3defe2c8472aec51f88c4c3488 Mon Sep 17 00:00:00 2001 From: jmd-mongo <73852296+jmd-mongo@users.noreply.github.com> Date: Wed, 29 Sep 2021 17:29:37 -0400 Subject: [PATCH 063/109] Docs 14795 update order numeric when possible (#5898) * DOCS-14472 update operators act in lexicographic order * DOCS-14795 update order numeric when possible --- .../fact-update-operator-processing-order.rst | 4 ++++ source/reference/operator/update.txt | 24 +++++++++++++++++++ source/reference/operator/update/addToSet.txt | 2 ++ source/reference/operator/update/bit.txt | 2 ++ .../reference/operator/update/currentDate.txt | 2 ++ source/reference/operator/update/each.txt | 5 ++++ source/reference/operator/update/inc.txt | 4 +++- source/reference/operator/update/max.txt | 2 ++ source/reference/operator/update/min.txt | 2 ++ source/reference/operator/update/mul.txt | 2 ++ source/reference/operator/update/pop.txt | 2 ++ source/reference/operator/update/position.txt | 4 ++++ .../operator/update/positional-all.txt | 2 ++ .../operator/update/positional-filtered.txt | 2 ++ .../reference/operator/update/positional.txt | 2 ++ source/reference/operator/update/pull.txt | 2 ++ source/reference/operator/update/pullAll.txt | 2 ++ source/reference/operator/update/push.txt | 2 ++ source/reference/operator/update/rename.txt | 2 ++ source/reference/operator/update/set.txt | 4 ++-- .../reference/operator/update/setOnInsert.txt | 4 +++- source/reference/operator/update/slice.txt | 2 ++ source/reference/operator/update/sort.txt | 2 ++ source/reference/operator/update/unset.txt | 2 ++ source/release-notes/5.0-compatibility.txt | 5 ++++ 25 files changed, 84 insertions(+), 4 deletions(-) create mode 100644 source/includes/fact-update-operator-processing-order.rst diff --git a/source/includes/fact-update-operator-processing-order.rst b/source/includes/fact-update-operator-processing-order.rst new file mode 100644 index 00000000000..3eddf446867 --- /dev/null +++ b/source/includes/fact-update-operator-processing-order.rst @@ -0,0 +1,4 @@ +Starting in MongoDB 5.0, update operators process document fields with +string-based names in lexicographic order. Fields with numeric names are +processed in numeric order. See :ref:`Update Operators Behavior +` for details. diff --git a/source/reference/operator/update.txt b/source/reference/operator/update.txt index 171d7486ee0..4a00499e340 100644 --- a/source/reference/operator/update.txt +++ b/source/reference/operator/update.txt @@ -33,6 +33,30 @@ Specify the operator expression in a document of the form: Update Operators ---------------- +.. _update-operators-processing-order: + +Behavior +~~~~~~~~ + +Starting in MongoDB 5.0, update operators process document fields with +string-based names in lexicographic order. Fields with numeric names are +processed in numeric order. + +In MongoDB 4.4 and earlier, update operators process all document fields +in lexicographic order. + +Consider this example :update:`$set` command: + +.. code-block:: javascript + + { $set: { "a.2": , "a.10": , } } + +In MongoDB 5.0 and later, ``"a.2"`` is processed before ``"a.10"`` +because ``2`` comes before ``10`` in numeric order. + +In MongoDB 4.4 and earlier, ``"a.10"`` is processed before ``"a.2"`` +because ``10`` comes before ``2`` in lexicographic order. + Fields ~~~~~~ diff --git a/source/reference/operator/update/addToSet.txt b/source/reference/operator/update/addToSet.txt index 3a8baba5164..6e9ef5b4c09 100644 --- a/source/reference/operator/update/addToSet.txt +++ b/source/reference/operator/update/addToSet.txt @@ -30,6 +30,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + :update:`$addToSet` only ensures that there are no duplicate items *added* to the set and does not affect existing duplicate elements. :update:`$addToSet` does not guarantee a particular ordering of diff --git a/source/reference/operator/update/bit.txt b/source/reference/operator/update/bit.txt index 2190dd452bb..fc423f0f50d 100644 --- a/source/reference/operator/update/bit.txt +++ b/source/reference/operator/update/bit.txt @@ -42,6 +42,8 @@ Behavior .. include:: /includes/extracts/update-operation-empty-operand-expressions-bit.rst +.. include:: /includes/fact-update-operator-processing-order.rst + Examples -------- diff --git a/source/reference/operator/update/currentDate.txt b/source/reference/operator/update/currentDate.txt index 8666b386598..105e09a4898 100644 --- a/source/reference/operator/update/currentDate.txt +++ b/source/reference/operator/update/currentDate.txt @@ -41,6 +41,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + If the field does not exist, :update:`$currentDate` adds the field to a document. diff --git a/source/reference/operator/update/each.txt b/source/reference/operator/update/each.txt index f7e9c2a19dc..d66a5a21ca0 100644 --- a/source/reference/operator/update/each.txt +++ b/source/reference/operator/update/each.txt @@ -37,6 +37,11 @@ Definition other modifiers. For a list of modifiers available for :update:`$push`, see :ref:`push-modifiers`. +Behavior +-------- + +.. include:: /includes/fact-update-operator-processing-order.rst + Examples -------- diff --git a/source/reference/operator/update/inc.txt b/source/reference/operator/update/inc.txt index 0c50298008e..e5d2828ce0e 100644 --- a/source/reference/operator/update/inc.txt +++ b/source/reference/operator/update/inc.txt @@ -23,10 +23,12 @@ Definition { $inc: { : , : , ... } } .. include:: /includes/use-dot-notation.rst - + Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + The :update:`$inc` operator accepts positive and negative values. If the field does not exist, :update:`$inc` creates the field and sets diff --git a/source/reference/operator/update/max.txt b/source/reference/operator/update/max.txt index ce79fc44727..06e9ba5a80e 100644 --- a/source/reference/operator/update/max.txt +++ b/source/reference/operator/update/max.txt @@ -32,6 +32,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + If the field does not exists, the :update:`$max` operator sets the field to the specified value. diff --git a/source/reference/operator/update/min.txt b/source/reference/operator/update/min.txt index 03eb39233cd..7f2031ba407 100644 --- a/source/reference/operator/update/min.txt +++ b/source/reference/operator/update/min.txt @@ -30,6 +30,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + If the field does not exist, the :update:`$min` operator sets the field to the specified value. diff --git a/source/reference/operator/update/mul.txt b/source/reference/operator/update/mul.txt index 0ac2e62bc27..1ed6bc17aeb 100644 --- a/source/reference/operator/update/mul.txt +++ b/source/reference/operator/update/mul.txt @@ -31,6 +31,8 @@ Behavior .. include:: /includes/extracts/update-operation-empty-operand-expressions-mul.rst +.. include:: /includes/fact-update-operator-processing-order.rst + Missing Field ~~~~~~~~~~~~~ diff --git a/source/reference/operator/update/pop.txt b/source/reference/operator/update/pop.txt index 8b568b119c8..2fcd206c167 100644 --- a/source/reference/operator/update/pop.txt +++ b/source/reference/operator/update/pop.txt @@ -31,6 +31,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + The :update:`$pop` operation fails if the ```` is not an array. If the :update:`$pop` operator removes the last item in the diff --git a/source/reference/operator/update/position.txt b/source/reference/operator/update/position.txt index 244cf1a0a8a..2a0d60e9c3a 100644 --- a/source/reference/operator/update/position.txt +++ b/source/reference/operator/update/position.txt @@ -58,6 +58,10 @@ Definition greater than or equal to the length of the array, the :update:`$push` adds elements to the beginning of the array. +Behavior +-------- + +.. include:: /includes/fact-update-operator-processing-order.rst Examples -------- diff --git a/source/reference/operator/update/positional-all.txt b/source/reference/operator/update/positional-all.txt index d27813e3489..a960d837ca1 100644 --- a/source/reference/operator/update/positional-all.txt +++ b/source/reference/operator/update/positional-all.txt @@ -43,6 +43,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + ``upsert`` ~~~~~~~~~~~ diff --git a/source/reference/operator/update/positional-filtered.txt b/source/reference/operator/update/positional-filtered.txt index d76f4c3440f..3e1fe6bada2 100644 --- a/source/reference/operator/update/positional-filtered.txt +++ b/source/reference/operator/update/positional-filtered.txt @@ -52,6 +52,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + ``upsert`` ~~~~~~~~~~~ diff --git a/source/reference/operator/update/positional.txt b/source/reference/operator/update/positional.txt index 53bd2d557b3..aece7dd1a3e 100644 --- a/source/reference/operator/update/positional.txt +++ b/source/reference/operator/update/positional.txt @@ -59,6 +59,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + ``upsert`` ~~~~~~~~~~~ diff --git a/source/reference/operator/update/pull.txt b/source/reference/operator/update/pull.txt index e3cf66f62be..1afb922beae 100644 --- a/source/reference/operator/update/pull.txt +++ b/source/reference/operator/update/pull.txt @@ -26,6 +26,8 @@ $pull Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + If you specify a ```` and the array elements are embedded documents, :update:`$pull` operator applies the ```` as if each array element were a document in a collection. See diff --git a/source/reference/operator/update/pullAll.txt b/source/reference/operator/update/pullAll.txt index f0c1f2478e0..534ff0aad11 100644 --- a/source/reference/operator/update/pullAll.txt +++ b/source/reference/operator/update/pullAll.txt @@ -31,6 +31,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + If a ```` to remove is a document or an array, :update:`$pullAll` removes only the elements in the array that match the specified ```` exactly, including order. diff --git a/source/reference/operator/update/push.txt b/source/reference/operator/update/push.txt index a7440b74756..7e0aebf383c 100644 --- a/source/reference/operator/update/push.txt +++ b/source/reference/operator/update/push.txt @@ -28,6 +28,8 @@ Definition Behavior --------- +.. include:: /includes/fact-update-operator-processing-order.rst + If the field is absent in the document to update, :update:`$push` adds the array field with the value as its element. diff --git a/source/reference/operator/update/rename.txt b/source/reference/operator/update/rename.txt index 587aadaa037..faa50b551c7 100644 --- a/source/reference/operator/update/rename.txt +++ b/source/reference/operator/update/rename.txt @@ -37,6 +37,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + The :update:`$rename` operator logically performs an :update:`$unset` of both the old name and the new name, and then performs a :update:`$set` operation with the new name. As such, the operation may diff --git a/source/reference/operator/update/set.txt b/source/reference/operator/update/set.txt index 2c1e926b7c1..c2a6afea055 100644 --- a/source/reference/operator/update/set.txt +++ b/source/reference/operator/update/set.txt @@ -32,11 +32,11 @@ Definition .. include:: /includes/use-dot-notation.rst - - Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + If the field does not exist, :update:`$set` will add a new field with the specified value, provided that the new field does not violate a type constraint. diff --git a/source/reference/operator/update/setOnInsert.txt b/source/reference/operator/update/setOnInsert.txt index 221468c509b..d8bc0c104b1 100644 --- a/source/reference/operator/update/setOnInsert.txt +++ b/source/reference/operator/update/setOnInsert.txt @@ -38,8 +38,10 @@ Definition Behavior -------- -.. include:: /includes/extracts/update-operation-empty-operand-expressions-set-on-insert.rst +.. include:: /includes/fact-update-operator-processing-order.rst +.. include:: /includes/extracts/update-operation-empty-operand-expressions-set-on-insert.rst + Example ------- diff --git a/source/reference/operator/update/slice.txt b/source/reference/operator/update/slice.txt index 820bb606513..133cae4491d 100644 --- a/source/reference/operator/update/slice.txt +++ b/source/reference/operator/update/slice.txt @@ -58,6 +58,8 @@ $slice Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + The order in which the modifiers appear is immaterial. Previous versions required the :update:`$each` modifier to appear as the first modifier if used in conjunction with :update:`$slice`. For a list of diff --git a/source/reference/operator/update/sort.txt b/source/reference/operator/update/sort.txt index 2b61c1b4eea..e0d3a0b7279 100644 --- a/source/reference/operator/update/sort.txt +++ b/source/reference/operator/update/sort.txt @@ -47,6 +47,8 @@ $sort Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + The :update:`$sort` modifier can sort array elements that are not documents. In previous versions, the :update:`$sort` modifier required the array elements be documents. diff --git a/source/reference/operator/update/unset.txt b/source/reference/operator/update/unset.txt index c3a123760bf..f4ea7a060bc 100644 --- a/source/reference/operator/update/unset.txt +++ b/source/reference/operator/update/unset.txt @@ -36,6 +36,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + If the field does not exist, then :update:`$unset` does nothing (i.e. no operation). diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt index 974cc155ca1..a2144e5426c 100644 --- a/source/release-notes/5.0-compatibility.txt +++ b/source/release-notes/5.0-compatibility.txt @@ -232,6 +232,11 @@ operand expression ( ``{ }`` ): An empty update results in no changes and no :term:`oplog` entry is created (meaning that the operation is a no-op). +Update Operator Processing Order +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/fact-update-operator-processing-order.rst + Aggregation Pipeline Operator Parameter Limits ---------------------------------------------- From 43225b58845fda81166dbfde888e32591005230c Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Thu, 30 Sep 2021 15:05:34 +0200 Subject: [PATCH 064/109] DOCS-14828: fix for minSnapshotHistoryWindowInSeconds --- source/reference/parameters.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/reference/parameters.txt b/source/reference/parameters.txt index 954d91bdd5d..d008386ea8e 100644 --- a/source/reference/parameters.txt +++ b/source/reference/parameters.txt @@ -3693,7 +3693,7 @@ Storage Parameters ``minSnapshotHistoryWindowInSeconds``, :binary:`~bin.mongod` returns a ``SnapshotTooOld`` error. - Specify an integer greater than or equal to (``>=``) 1. + Specify an integer greater than or equal to (``>=``) 0. Consider the following example which sets the ``minSnapshotHistoryWindowInSeconds`` to ``600`` seconds: From 88afa9eb08de433079b5801ffba2a2b2cf497f7a Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Wed, 29 Sep 2021 14:14:44 +0200 Subject: [PATCH 065/109] Refactor Security Checklist --- source/administration/security-checklist.txt | 146 +++++++++---------- source/includes/fact-tls-libraries.rst | 2 +- 2 files changed, 70 insertions(+), 78 deletions(-) diff --git a/source/administration/security-checklist.txt b/source/administration/security-checklist.txt index 63665f4e737..b77c8518137 100644 --- a/source/administration/security-checklist.txt +++ b/source/administration/security-checklist.txt @@ -6,9 +6,9 @@ Security Checklist .. |arrow| unicode:: U+27A4 -*Last updated: 2020-03-25* +*Last updated: 2021-09-29* -This documents provides a list of security measures that you should +This document provides a list of security measures that you should implement to protect your MongoDB installation. The list is not meant to be exhaustive. @@ -20,46 +20,54 @@ Pre-production Checklist/Considerations |arrow| Enable Access Control and Enforce Authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Enable access control and specify the authentication mechanism. - You can use MongoDB's SCRAM or x.509 authentication mechanism or - integrate with your existing Kerberos/LDAP infrastructure. Authentication - requires that all clients and servers provide valid credentials - before they can connect to the system. +- Enable access control and specify an authentication mechanism. - | + MongoDB Community supports a number of :ref:`authentication mechanisms + ` that clients can use to verify + their identity: - See also: + - :ref:`authentication-scram` (*Default*) + - :ref:`x.509 Certificate Authentication `. - - :doc:`/core/authentication` - - :doc:`/tutorial/enable-authentication` + In addition to the preceding mechanisms, MongoDB Atlas and MongoDB + Enterprise support the following mechanisms: + + - :ref:`LDAP proxy authentication `, and + - :ref:`Kerberos authentication `. + + These mechanisms allow MongoDB to integrate into your + existing authentication system. + +.. seealso:: + + - :doc:`/core/authentication` + - :doc:`/tutorial/enable-authentication` .. _security-checklist-role-based-access-control: |arrow| Configure Role-Based Access Control ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Create a user administrator **first**, then create additional - users. Create a unique MongoDB user for each person/application - that accesses the system. - +- Create a :ref:`user administrator ` **first**, then + create additional users. Create a unique MongoDB user for each + person/application that accesses the system. + - Follow the principle of least privilege. Create roles that define the exact access rights required by a set of users. Then create users and assign them only the roles they need to perform their operations. A user can be a person or a client application. .. note:: - + A user can have privileges across different databases. If a user requires privileges on multiple databases, create a single user with roles that grant applicable database privileges instead of creating the user multiple times in different databases. - | - - See also: +.. seealso:: - - :doc:`/core/authorization` - - :doc:`/tutorial/manage-users-and-roles` + - :doc:`/core/authorization` + - :doc:`/tutorial/manage-users-and-roles` |arrow| Encrypt Communication (TLS/SSL) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -72,33 +80,29 @@ Pre-production Checklist/Considerations .. include:: /includes/fact-tls-libraries.rst - .. note:: - - .. include:: /includes/fact-tls-1.0.rst +.. seealso:: - | - - See also: :doc:`/tutorial/configure-ssl`. - -.. |binary| replace:: MongoDB + :doc:`/tutorial/configure-ssl`. |arrow| Encrypt and Protect Data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Starting with MongoDB Enterprise 3.2, you can encrypt data in - the storage layer with the WiredTiger storage engine's native - :doc:`/core/security-encryption-at-rest`. +- You can encrypt data in the storage layer with the WiredTiger storage + engine's native :doc:`/core/security-encryption-at-rest`. - If you are not using WiredTiger's encryption at rest, MongoDB data should be encrypted on each host using file-system, device, - or physical encryption (e.g. dm-crypt). Protect MongoDB data - using file-system permissions. MongoDB data includes data files, - configuration files, auditing logs, and key files. - -- Collect logs to a central log store. These logs contain DB - authentication attempts including source IP address. - - + or physical encryption (for example dm-crypt). You should also protect + MongoDB data using file-system permissions. MongoDB data includes data + files, configuration files, auditing logs, and key files. + +- You can use :doc:`/core/security-client-side-encryption` to encrypt + fields in documents application-side prior to transmitting data over + the wire to the server. + +- Collect logs to a central log store. These logs contain database + authentication attempts including source IP addresses. + |arrow| Limit Network Exposure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -111,25 +115,19 @@ Pre-production Checklist/Considerations - Allow only trusted clients to access the network interfaces and ports on which MongoDB instances are available. - .. note:: - - .. include:: /includes/fact-default-bind-ip-change.rst +.. seealso:: - | + - :doc:`/core/security-hardening` - See also: + - the :setting:`net.bindIp` configuration setting - - :doc:`/core/security-hardening` + - the :setting:`security.clusterIpSourceAllowlist` configuration + setting - - the :setting:`net.bindIp` configuration setting - - - the :setting:`security.clusterIpSourceAllowlist` configuration - setting - - - the :ref:`authenticationRestrictions - ` field to the - :method:`db.createUser()` command to specify a per-user IP - allow list. + - the :ref:`authenticationRestrictions + ` field to the + :method:`db.createUser()` command to specify a per-user IP + allow list. |arrow| Audit System Activity @@ -137,21 +135,19 @@ Pre-production Checklist/Considerations - Track access and changes to database configurations and data. `MongoDB Enterprise - `_ + `_ includes a system auditing facility that can record - system events (e.g. user operations, connection events) on a + system events (including user operations and connection events) on a MongoDB instance. These audit records permit forensic analysis - and allow administrators to verify proper controls. You can set - up filters to record specific events, such as authentication + and allow administrators to exercise proper controls. You can set + up filters to record only specific events, such as authentication events. - | - - See also: +.. seealso:: - - :doc:`/core/auditing` + - :doc:`/core/auditing` - - :doc:`/tutorial/configure-auditing` + - :doc:`/tutorial/configure-auditing` |arrow| Run MongoDB with a Dedicated User ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -160,9 +156,9 @@ Pre-production Checklist/Considerations account. Ensure that the account has permissions to access data but no unnecessary permissions. - | +.. seealso:: - See also: :doc:`/installation` + :doc:`/installation` .. _security-checklist-javascript: @@ -173,17 +169,16 @@ Pre-production Checklist/Considerations server-side operations: :dbcommand:`mapReduce`, :query:`$where`, :group:`$accumulator`, and :expression:`$function`. If you do not use these operations, disable server-side scripting by using - the :option:`--noscripting ` option on the - command line. + the :option:`--noscripting ` option. - Keep input validation enabled. MongoDB enables input validation by default through the :setting:`net.wireObjectCheck` setting. This ensures that all documents stored by the :binary:`~bin.mongod` instance are valid :term:`BSON`. - | +.. seealso:: - See also: :doc:`/core/security-hardening` + :doc:`/core/security-hardening` |arrow| Request a Security Technical Implementation Guide (where applicable) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -191,9 +186,7 @@ Pre-production Checklist/Considerations - The Security Technical Implementation Guide (STIG) contains security guidelines for deployments within the United States Department of Defense. MongoDB Inc. provides its STIG, upon - request, for situations where it is required. Please `request a - copy `_ for - more information. + `request `_. |arrow| Consider Security Standards Compliance ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -201,7 +194,7 @@ Pre-production Checklist/Considerations - For applications requiring HIPAA or PCI-DSS compliance, please refer to the `MongoDB Security Reference Architecture `_ - to learn more about how you can use the key security + to learn more about how you can use MongoDB's key security capabilities to build compliant application infrastructure. @@ -213,15 +206,14 @@ Periodic/Ongoing Production Checks - Consult the `MongoDB end of life dates `_ and upgrade your - MongoDB installation. In general, try to stay on the latest + MongoDB installation as needed. In general, try to stay on the latest version. - Ensure that your information security management system policies and procedures extend to your MongoDB installation, including performing the following: - - Periodically apply patches to your machine and review - guidelines. + - Periodically apply patches to your machine. - Review policy/procedure changes, especially changes to your network rules to prevent inadvertent MongoDB exposure to the diff --git a/source/includes/fact-tls-libraries.rst b/source/includes/fact-tls-libraries.rst index cdaa2f17fa1..085a41ff0c8 100644 --- a/source/includes/fact-tls-libraries.rst +++ b/source/includes/fact-tls-libraries.rst @@ -1,4 +1,4 @@ -Starting in version 4.0, MongoDB uses the native TLS/SSL OS libraries: +MongoDB uses the native TLS/SSL OS libraries: .. list-table:: :header-rows: 1 From 58942f123ce4d658b73ceb1819a5f7f756cd798a Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Thu, 30 Sep 2021 14:40:32 -0400 Subject: [PATCH 066/109] DOCS-14595 serverStatus output change --- source/reference/command/serverStatus.txt | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/source/reference/command/serverStatus.txt b/source/reference/command/serverStatus.txt index 9827cac2c2b..c1d6f9beb05 100644 --- a/source/reference/command/serverStatus.txt +++ b/source/reference/command/serverStatus.txt @@ -2837,7 +2837,8 @@ shardingStatistics "donorState" : , "recipientState" : , "coordinatorState" : , - "opStatus" : + "opStatus" : , + "lastOpEndingChunkImbalance": NumberLong() } }, @@ -3605,6 +3606,20 @@ shardingStatistics .. versionadded:: 5.0 +.. serverstatus:: shardingStatistics.resharding.lastOpEndingChunkImbalance + + This field contains the highest numeric difference for + (``maxNumChunksInShard - minNumChunksInShard``) among all + :ref:`zones ` for the + collection that was processed by the most recent + :ref:`resharding operation `. + + See :ref:`sharding-chunk-size`. + + *Only updated on config servers.* + + .. versionadded:: 5.0 + .. _server-status-sharded-index-consistency: shardedIndexConsistency From 1f9e54b9dc59c4d644e97e382509f82f8ddeff72 Mon Sep 17 00:00:00 2001 From: Joseph Dougherty Date: Fri, 1 Oct 2021 09:54:53 -0400 Subject: [PATCH 067/109] DOCS-14826 readWrite role has changeStream privilege --- source/reference/built-in-roles.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/source/reference/built-in-roles.txt b/source/reference/built-in-roles.txt index 3bd33ec5e2e..02350dcb875 100644 --- a/source/reference/built-in-roles.txt +++ b/source/reference/built-in-roles.txt @@ -72,6 +72,7 @@ Every database includes the following client roles: The role provides the following actions on those collections: + - :authaction:`changeStream` - :authaction:`collStats` - :authaction:`convertToCapped` - :authaction:`createCollection` From c245c727724945d58cee052985ed4579f7d3c635 Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Mon, 4 Oct 2021 07:32:55 -0400 Subject: [PATCH 068/109] DOCS-14681 update typo in range window codeblock --- source/reference/operator/aggregation/setWindowFields.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/reference/operator/aggregation/setWindowFields.txt b/source/reference/operator/aggregation/setWindowFields.txt index 66566e29ba2..bf3cd10ef0f 100644 --- a/source/reference/operator/aggregation/setWindowFields.txt +++ b/source/reference/operator/aggregation/setWindowFields.txt @@ -683,7 +683,7 @@ in the window is shown in the ``quantityFromSimilarOrders`` field: { "_id" : 1, "type" : "chocolate", "orderDate" : ISODate("2021-03-20T11:30:05Z"), "state" : "WA", "price" : 14, "quantity" : 140, "quantityFromSimilarOrders" : 244 } { "_id" : 5, "type" : "strawberry", "orderDate" : ISODate("2019-01-08T06:12:03Z"), - "state" : "WA", "price" : 43, "quantity" : 134, "quantityFromSimilarOrders" : 112 } + "state" : "WA", "price" : 43, "quantity" : 134, "quantityFromSimilarOrders" : 134 } .. _setWindowFields-time-range-window-examples: From 7b7228f66cda897cb14c258bbb7634bcd2b0ac76 Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Fri, 1 Oct 2021 11:13:18 -0400 Subject: [PATCH 069/109] DOCS-14375 add capped collection note to 5.0 changelog --- source/core/capped-collections.txt | 2 ++ source/release-notes/5.0.txt | 9 +++++++++ 2 files changed, 11 insertions(+) diff --git a/source/core/capped-collections.txt b/source/core/capped-collections.txt index 97af39f65a1..79e88ec5ae8 100644 --- a/source/core/capped-collections.txt +++ b/source/core/capped-collections.txt @@ -48,6 +48,8 @@ result, queries do not need an index to return documents in insertion order. Without this indexing overhead, capped collections can support higher insertion throughput. +.. _capped_collections_remove_documents: + Automatic Removal of Oldest Documents ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index bb327ed48c3..aa236014dfc 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -661,6 +661,15 @@ Transactions General Improvements -------------------- +Capped Collection Deletes Process On Secondaries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting in MongoDB 5.0, the +:ref:`implicit delete operations ` +of :doc:`replica set ` +:term:`capped collections ` are processed by +the :doc:`secondary members `. + Execution Plan Statistics for Query with ``$lookup`` Pipeline Stage ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 321d79e9d2ae3e5be1b51555c31cc64fe5465981 Mon Sep 17 00:00:00 2001 From: ian fogelman Date: Fri, 1 Oct 2021 16:09:18 -0400 Subject: [PATCH 070/109] DOCSP-14047 add note about mongoshell to page --- source/faq/fundamentals.txt | 44 +++++++++++++------ .../reference/method/db.createCollection.txt | 3 ++ 2 files changed, 33 insertions(+), 14 deletions(-) diff --git a/source/faq/fundamentals.txt b/source/faq/fundamentals.txt index bbede4711b1..9334e5f65f8 100644 --- a/source/faq/fundamentals.txt +++ b/source/faq/fundamentals.txt @@ -44,35 +44,51 @@ the columns in a relational database table. How do I create a database and a collection? -------------------------------------------- +.. note:: + + You can enter the commands referenced in this FAQ by using + the :binary:`MongoDB Shell <~bin.mongosh>`. The MongoDB Shell is an + interactive JavaScript interface to MongoDB. You can use the MongoDB + Shell to query and update data as well as perform administrative + operations. + If a database does not exist, MongoDB creates the database when you first store data for that database. If a collection does not exist, MongoDB creates the collection when you -first store data for that collection. [#explicit-creation]_ +first store data for that collection. As such, you can switch to a non-existent database (``use ``) and perform the following operation: .. code-block:: javascript - use myNewDB + use myNewDB; + + db.myNewCollection1.insertOne( { x: 1 } ); + db.myNewCollection2.createIndex( { a: 1 } ); - db.myNewCollection1.insertOne( { x: 1 } ) - db.myNewCollection2.createIndex( { a: 1 } ) +- The :method:`db.collection.insertOne()` method creates + the collection ``myNewCollection1`` if it does not already exist. -The ``insert`` operation creates both the database ``myNewDB`` and the -collection ``myNewCollection1`` if they do not already exist. +- The :method:`db.collection.createIndex()` method creates the index and + the collection ``myNewCollection2`` if it does not already exist. -The ``createIndex`` operation, which occurs after the ``myNewDB`` has -been created, creates the index and the collection ``myNewCollection2`` -if the collection does not exist. If ``myNewDb`` did not exist, the -``createIndex`` operation would have also created the ``myNewDB``. +- If the ``myNewDb`` database did not exist, either the + :method:`db.collection.createIndex()` method or + :method:`db.collection.insertOne()` method would have created + the ``myNewDb`` database automatically. + +You can also create a collection explicitly using +:method:`db.createCollection` method if you want to specify specific +:ref:`options`, such as maximum size +or document validation rules: + +.. code-block:: javascript -.. [#explicit-creation] + use myNewDB; - You can also create a collection explicitly using - :method:`db.createCollection` if you want to specify specific - options, such as maximum size or document validation rules. + db.createCollection("myNewCollection1"); .. _faq-schema-free: diff --git a/source/reference/method/db.createCollection.txt b/source/reference/method/db.createCollection.txt index 3bdca6f62aa..76677be73f2 100644 --- a/source/reference/method/db.createCollection.txt +++ b/source/reference/method/db.createCollection.txt @@ -63,6 +63,9 @@ Definition } ) + + .. _create_collection_parameters: + The :method:`db.createCollection()` method has the following parameters: From d3751b3b0a9c4ea364de22876fe06d09f7c36409 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Fri, 1 Oct 2021 14:46:11 +0200 Subject: [PATCH 071/109] DOCS-14824: Clarify random part of objectId --- source/includes/fact-ObjectId-construct.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/includes/fact-ObjectId-construct.rst b/source/includes/fact-ObjectId-construct.rst index 6aea30714a0..9f6abc15072 100644 --- a/source/includes/fact-ObjectId-construct.rst +++ b/source/includes/fact-ObjectId-construct.rst @@ -1,7 +1,8 @@ - a 4-byte *timestamp value*, representing the ObjectId's creation, measured in seconds since the Unix epoch -- a 5-byte *random value* +- a 5-byte *random value* generated once per process. This random value + is unique to the machine and process. - a 3-byte *incrementing counter*, initialized to a random value From facf868b58afd0e1d1d24092f4a30df0c7c4d09b Mon Sep 17 00:00:00 2001 From: jason-price-mongodb Date: Thu, 30 Sep 2021 12:47:48 -0700 Subject: [PATCH 072/109] DOCS-14452 view in log --- source/reference/log-messages.txt | 84 +++++++++++++++++++++++++++++++ source/release-notes/5.0.txt | 7 +++ 2 files changed, 91 insertions(+) diff --git a/source/reference/log-messages.txt b/source/reference/log-messages.txt index c11e50962b7..f6079ba167c 100644 --- a/source/reference/log-messages.txt +++ b/source/reference/log-messages.txt @@ -1330,3 +1330,87 @@ attribute object: "request": "RemoteCommand 229 -- target:localhost:27003 db:admin cmd:{ replSetRequestVotes: 1, setName: \"my-replica-name\", dryRun: true, term: 3, candidateIndex: 0, configVersion: 2, configTerm: 3, lastAppliedOpTime: { ts: Timestamp(1589915409, 1), t: 3 } }" } } + +.. _log-message-view-example: + +View +~~~~ + +Starting in MongoDB 5.0, :ref:`log messages for slow queries +` on :doc:`views ` include a +``resolvedViews`` field that contains the view details: + +.. code-block:: javascript + :copyable: false + + "resolvedViews": [ { + "viewNamespace": , // namespace and view name + "dependencyChain": , // view name and collection + "resolvedPipeline": // aggregation pipeline for view + } ] + +The following example uses the ``test`` database and creates a view +named ``myView`` that sorts the documents in ``myCollection`` by the +``firstName`` field: + +.. code-block:: javascript + + use test + db.createView( "myView", "myCollection", [ { $sort: { "firstName" : 1 } } ] ) + +Assume a :ref:`slow query ` is run on ``myView``. +The following example log message contains a ``resolvedViews`` field for +``myView``: + +.. code-block:: javascript + :copyable: false + + { + "t": { + "$date": "2021-09-30T17:53:54.646+00:00" + }, + "s": "I", + "c": "COMMAND", + "id": 51803, + "ctx": "conn249", + "msg": "Slow query", + "attr": { + "type": "command", + "ns": "test.myView", + "appName": "MongoDB Shell", + "command": { + "find": "myView", + "filter": {}, + "lsid": { + "id": { "$uuid": "ad176471-60e5-4e82-b977-156a9970d30f" } + }, + "$db": "test" + }, + "planSummary":"COLLSCAN", + "resolvedViews": [ { + "viewNamespace": "test.myView", + "dependencyChain": [ "myView", "myCollection" ], + "resolvedPipeline": [ { "$sort": { "firstName": 1 } } ] + } ], + "keysExamined": 0, + "docsExamined": 1, + "hasSortStage": true, + "cursorExhausted": true, + "numYields": 0, + "nreturned": 1, + "queryHash": "3344645B", + "planCacheKey": "1D3DE690", + "reslen": 134, + "locks": { "ParallelBatchWriterMode": { "acquireCount": { "r": 1 } }, + "ReplicationStateTransition": { "acquireCount": { "w": 1 } }, + "Global": { "acquireCount": { "r": 4 } }, + "Database": { "acquireCount": {"r": 1 } }, + "Collection": { "acquireCount": { "r": 1 } }, + "Mutex": { "acquireCount": { "r": 4 } } }, + "storage": {}, + "remote": "127.0.0.1:34868", + "protocol": "op_msg", + "durationMillis": 0 + } + } + } diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index aa236014dfc..d55c5bac11b 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -827,6 +827,13 @@ Starting in MongoDB 5.0, you can use the :ref:`remoteOpWaitMillis ` log field to obtain the wait time for results from :term:`shards `. +``resolvedViews`` Log Field for Slow Queries on Views +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting in MongoDB 5.0, :ref:`log messages for slow queries +` on :ref:`views ` +include a ``resolvedViews`` field that contains the view details. + Define Variables Using the ``let`` Option ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 2089bfe4ff7211d1afa5082711fea063a57719b0 Mon Sep 17 00:00:00 2001 From: jason-price-mongodb Date: Fri, 24 Sep 2021 09:40:51 -0700 Subject: [PATCH 073/109] DOCSP-17736 cluster chaining parameter --- source/reference/parameters.txt | 27 ++++++++++++++++++++++ source/reference/replica-configuration.txt | 26 +++++++++++++++++---- source/release-notes/5.0.txt | 10 +++++++- 3 files changed, 57 insertions(+), 6 deletions(-) diff --git a/source/reference/parameters.txt b/source/reference/parameters.txt index d008386ea8e..0a08c0a3eb9 100644 --- a/source/reference/parameters.txt +++ b/source/reference/parameters.txt @@ -1943,6 +1943,33 @@ The following parameters support diagnostic data capture (FTDC): Replication and Consistency ~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. parameter:: enableOverrideClusterChainingSetting + + .. versionadded:: 5.0.2 + + |both| + + *Type*: boolean + + *Default*: false + + If :parameter:`enableOverrideClusterChainingSetting` is ``true``, + replica set :term:`secondary` members can replicate data from + other secondary members even if :rsconf:`settings.chainingAllowed` is + ``false``. + + You can only set :parameter:`enableOverrideClusterChainingSetting` at + startup and cannot change this setting with the + :dbcommand:`setParameter` command. + + For example, to set the + :parameter:`enableOverrideClusterChainingSetting` for a + :binary:`~bin.mongod` instance to ``true``: + + .. code-block:: bash + + mongod --setParameter enableOverrideClusterChainingSetting=true + .. parameter:: logicalSessionRefreshMillis .. note:: Availability diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index ac3af0c64fd..a6e4bd705e5 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -467,11 +467,27 @@ Replica Set Configuration Fields *Default*: true - When :rsconf:`settings.chainingAllowed` is - ``true``, the replica set allows :term:`secondary` members to - replicate from other secondary members. When - :rsconf:`settings.chainingAllowed` is - ``false``, secondaries can replicate only from the :term:`primary`. + In MongoDB 5.0.1 and earlier, if + :rsconf:`settings.chainingAllowed` is: + + - ``true``, replica set :term:`secondary` members can + replicate data from other secondary members. + + - ``false``, secondary members can replicate data only from the + :term:`primary`. + + Starting in MongoDB 5.0.2: + + - Replica set :term:`secondary` members can + replicate data from other secondary members even if + :rsconf:`settings.chainingAllowed` is ``false``. + + - To override :rsconf:`settings.chainingAllowed`, set the + :parameter:`enableOverrideClusterChainingSetting` server + parameter to ``true``. + + - The default for + :parameter:`enableOverrideClusterChainingSetting` is ``false``. .. seealso:: diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index d55c5bac11b..35731a171c4 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -455,6 +455,15 @@ 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. +``enableOverrideClusterChainingSetting`` Server Parameter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting in MongoDB 5.0.2, you can set the new +:parameter:`enableOverrideClusterChainingSetting` server parameter to +``true`` to allow :term:`secondary` members to replicate data from other +secondary members even if :rsconf:`settings.chainingAllowed` is +``false``. + .. _5.0-rel-notes-security: Security @@ -588,7 +597,6 @@ This parameter can affect the behavior of: :dbcommand:`moveChunk` commands to evenly distribute chunks across shards. See :ref:`sharding-balancing`. - .. _5.0-rel-notes-shell: Shell Changes From f1a6c04f2139c4afe04311b8c8874bfcef7ace25 Mon Sep 17 00:00:00 2001 From: jason-price-mongodb Date: Fri, 24 Sep 2021 09:40:51 -0700 Subject: [PATCH 074/109] DOCSP-17736 cluster chaining parameter --- source/reference/replica-configuration.txt | 4 ++-- source/release-notes/5.0.txt | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index a6e4bd705e5..04f349fcc73 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -467,7 +467,7 @@ Replica Set Configuration Fields *Default*: true - In MongoDB 5.0.1 and earlier, if + In MongoDB 5.0.1, 4.2.15, 4.4.7, and earlier, if :rsconf:`settings.chainingAllowed` is: - ``true``, replica set :term:`secondary` members can @@ -476,7 +476,7 @@ Replica Set Configuration Fields - ``false``, secondary members can replicate data only from the :term:`primary`. - Starting in MongoDB 5.0.2: + Starting in MongoDB 5.0.2, 4.2.16, and 4.4.8: - Replica set :term:`secondary` members can replicate data from other secondary members even if diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 35731a171c4..76c6a86eb5a 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -458,7 +458,7 @@ source. ``enableOverrideClusterChainingSetting`` Server Parameter ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Starting in MongoDB 5.0.2, you can set the new +Starting in MongoDB 5.0.2 (and 4.2.16 and 4.4.8), you can set the new :parameter:`enableOverrideClusterChainingSetting` server parameter to ``true`` to allow :term:`secondary` members to replicate data from other secondary members even if :rsconf:`settings.chainingAllowed` is From 2a3136f5ffa6cedc77594bd94b1ae72a608b2506 Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Thu, 7 Oct 2021 12:36:17 -0400 Subject: [PATCH 075/109] (DOCSP-18989): Remove note about mongosh custom app name --- source/reference/connection-string.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/source/reference/connection-string.txt b/source/reference/connection-string.txt index 86be4d2d21f..2b5130d2921 100644 --- a/source/reference/connection-string.txt +++ b/source/reference/connection-string.txt @@ -1233,8 +1233,10 @@ Miscellaneous Configuration - the :data:`system.profile.appName` field in the :doc:`database profiler ` output. - If you do not specify a custom app name, :binary:`~bin.mongosh` - uses the default "``MongoDB Shell``". + The :urioption:`appName` connection option is only applicable + when provided to a :ecosystem:`MongoDB Driver `. This + parameter has no effect when supplied to a client application + such as :compass:`MongoDB Compass ` or :binary:`~bin.mongosh`. .. versionadded:: 4.0 From dea275da37dbd9d6ac76fbcdb3f2c07bc5fd28b8 Mon Sep 17 00:00:00 2001 From: jason-price-mongodb Date: Tue, 14 Sep 2021 14:51:52 -0700 Subject: [PATCH 076/109] DOCSP-15486 fix build errors --- .../steps-compass-manual-queries.yaml | 31 +- source/reference/audit-message.txt | 44 +- source/reference/built-in-roles.txt | 7 - source/reference/command/mapReduce.txt | 2 +- source/reference/command/setAuditConfig.txt | 17 +- source/reference/privilege-actions.txt | 12 + source/reference/program/mongo.txt | 4 +- source/reference/program/mongod.txt | 2 +- source/reference/program/mongokerberos.txt | 2 +- source/reference/program/mongoldap.txt | 2 +- source/reference/program/mongos.txt | 2 +- source/release-notes/2.4-upgrade.txt | 4 +- .../tutorial/add-shards-to-shard-cluster.txt | 2 +- source/tutorial/configure-audit-filters.txt | 16 +- .../configure-linux-iptables-firewall.txt | 2 +- .../convert-secondary-into-arbiter.txt | 4 +- source/tutorial/expand-replica-set.txt | 2 +- source/tutorial/insert-documents.txt | 1326 ++++++------ source/tutorial/update-documents.txt | 1908 +++++++++-------- 19 files changed, 1762 insertions(+), 1627 deletions(-) diff --git a/source/includes/steps-compass-manual-queries.yaml b/source/includes/steps-compass-manual-queries.yaml index cec87ce5ace..909f42f6f52 100644 --- a/source/includes/steps-compass-manual-queries.yaml +++ b/source/includes/steps-compass-manual-queries.yaml @@ -1,34 +1,17 @@ -title: Enter a query in the query bar +title: Enter a document filter level: 4 ref: enter-query action: pre: | - Queries entered in the query bar must be valid MongoDB syntax. Only - :dbcommand:`finds ` will be executed. - - This example manually selects documents whose ``departureAirportFsCode`` is - "JFK". - - .. figure:: /images/compass/manual-query.png - :alt: Compass query bar with query entered - - When a valid query is entered, the bar is colored green and can be - executed. Invalid queries are colored red. The UI will automatically update - to indicate which fields and values are selected in the query. + A document filter must use valid MongoDB syntax. Only + :dbcommand:`finds ` can be executed. Invalid filters are + colored red. --- -title: Apply the query +title: Apply a document filter level: 4 ref: apply action: pre: | - After entering a query, run it by clicking the Apply button. To clear the - query, use the Reset button. - - Continuing with the example, executing the query displays information on the - matching documents. - - .. figure:: /images/compass/manual-query-results.png - :alt: Compass Apply button executes query - - To clear a query, use the Reset button. + To run a filter, click the :guilabel:`FIND` button. To clear a + filter, click the :guilabel:`RESET` button. ... diff --git a/source/reference/audit-message.txt b/source/reference/audit-message.txt index 56784e2f75e..e00e54ef9d9 100644 --- a/source/reference/audit-message.txt +++ b/source/reference/audit-message.txt @@ -178,7 +178,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-authenticate: - :authaction:`authenticate` + ``authenticate`` - .. code-block:: none :copyable: false @@ -189,7 +189,7 @@ associated ``param`` details and the ``result`` values, if any. mechanism: } - Starting in MongoDB 5.0, :authaction:`authenticate`: + Starting in MongoDB 5.0, ``authenticate``: - Is logged for incomplete authentication attempts. @@ -207,7 +207,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-authCheck: - :authaction:`authCheck` + ``authCheck`` - .. code-block:: none :copyable: false @@ -227,8 +227,8 @@ associated ``param`` details and the ``result`` values, if any. .. include:: /includes/fact-auditAuthorizationSuccess-performance-impact.rst - Starting in MongoDB 5.0, :authaction:`authCheck` is not logged - for actions that are generated internally. + Starting in MongoDB 5.0, ``authCheck`` is not logged for actions + that are generated internally. .. versionchanged:: 5.0 @@ -238,7 +238,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-clientMetadata: - :authaction:`clientMetadata` + ``clientMetadata`` - .. code-block:: none :copyable: false @@ -308,7 +308,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`createDatabase` + * - ``createDatabase`` - .. code-block:: none :copyable: false @@ -367,7 +367,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-directAuthMutation: - :authaction:`directAuthMutation` + ``directAuthMutation`` - .. code-block:: none :copyable: false @@ -389,7 +389,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`renameCollection` + * - ``renameCollection`` - .. code-block:: none :copyable: false @@ -495,7 +495,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`dropAllUsersFromDatabase` + * - ``dropAllUsersFromDatabase`` - .. code-block:: none :copyable: false @@ -505,7 +505,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`updateUser` + * - ``updateUser`` - .. code-block:: none :copyable: false @@ -529,7 +529,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`grantRolesToUser` + * - ``grantRolesToUser`` - .. code-block:: none :copyable: false @@ -549,7 +549,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`revokeRolesFromUser` + * - ``revokeRolesFromUser`` - .. code-block:: none :copyable: false @@ -601,7 +601,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`updateRole` + * - ``updateRole`` - .. code-block:: none :copyable: false @@ -646,7 +646,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`dropAllRolesFromDatabase` + * - ``dropAllRolesFromDatabase`` - .. code-block:: none :copyable: false @@ -656,7 +656,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`grantRolesToRole` + * - ``grantRolesToRole`` - .. code-block:: none :copyable: false @@ -676,7 +676,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`revokeRolesFromRole` + * - ``revokeRolesFromRole`` - .. code-block:: none :copyable: false @@ -696,7 +696,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`grantPrivilegesToRole` + * - ``grantPrivilegesToRole`` - .. code-block:: none :copyable: false @@ -719,7 +719,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`revokePrivilegesFromRole` + * - ``revokePrivilegesFromRole`` - .. code-block:: none :copyable: false @@ -779,7 +779,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`shardCollection` + * - ``shardCollection`` - .. code-block:: none :copyable: false @@ -861,7 +861,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-logout: - :authaction:`logout` + ``logout`` - .. code-block:: none :copyable: false @@ -895,7 +895,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-startup: - :authaction:`startup` + ``startup`` - .. code-block:: none :copyable: false diff --git a/source/reference/built-in-roles.txt b/source/reference/built-in-roles.txt index 02350dcb875..7a50fd15cc9 100644 --- a/source/reference/built-in-roles.txt +++ b/source/reference/built-in-roles.txt @@ -247,9 +247,7 @@ Cluster Administration Roles - :authaction:`cleanupOrphaned` - :authaction:`flushRouterConfig` - :authaction:`getDefaultRWConcern` (New in version 4.4) - - :authaction:`listSessions` (New in version 3.6) - - :authaction:`listShards` - :authaction:`removeShard` - :authaction:`replSetConfigure` @@ -257,9 +255,7 @@ Cluster Administration Roles - :authaction:`replSetGetStatus` - :authaction:`replSetStateChange` - :authaction:`resync` - - :authaction:`setDefaultRWConcern` (New in version 4.4) - - :authaction:`setFeatureCompatibilityVersion` - :authaction:`setFreeMonitoring` @@ -399,16 +395,13 @@ Cluster Administration Roles - :authaction:`hostInfo` - :authaction:`inprog` - :authaction:`listDatabases` - - :authaction:`listSessions` (New in version 3.6) - - :authaction:`listShards` - :authaction:`netstat` - :authaction:`replSetGetConfig` - :authaction:`replSetGetStatus` - :authaction:`serverStatus` - :authaction:`setFreeMonitoring` (New in version 4.0) - - :authaction:`shardingState` - :authaction:`top` diff --git a/source/reference/command/mapReduce.txt b/source/reference/command/mapReduce.txt index 370384114b3..54d0f15cc08 100644 --- a/source/reference/command/mapReduce.txt +++ b/source/reference/command/mapReduce.txt @@ -370,7 +370,7 @@ collection `: - :authaction:`find`, - :authaction:`insert`, -- :authaction:`replace` +- :authaction:`remove` Map-reduce with the ``merge`` or ``reduce`` actions when :ref:`outputting to a collection `: diff --git a/source/reference/command/setAuditConfig.txt b/source/reference/command/setAuditConfig.txt index 94cae1f0de1..136b7100fdf 100644 --- a/source/reference/command/setAuditConfig.txt +++ b/source/reference/command/setAuditConfig.txt @@ -59,14 +59,13 @@ Behavior Enable :doc:`Auditing ` to use :dbcommand:`setAuditConfig` at runtime. -:parameter:`auditAuthorizationSuccess` enables -:doc:`auditing ` of authorization success for the -:ref:`authCheck ` action. The parameter -value must be ``true`` to audit :authaction:`read` and -:authaction:`write` operations. However, when +:parameter:`auditAuthorizationSuccess` enables :doc:`auditing +` of authorization success for the :ref:`authCheck +` action. The parameter value must be +``true`` to audit read and write operations. However, when :parameter:`auditAuthorizationSuccess` is ``false`` auditing has less -performance impact because the :doc:`audit system ` -only logs authorization failures. +performance impact because the :doc:`audit system ` only +logs authorization failures. Configuration updates are distributed via the :term:`oplog` mechanism which means updates on :binary:`~bin.mongod` nodes are distributed to @@ -146,8 +145,8 @@ Audit Document Interactions ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Set :parameter:`auditAuthorizationSuccess` to ``true`` and create a -filter which includes actions of interest to audit :authaction:`read` -and :authaction:`write` operations. +filter which includes actions of interest to audit read and write +operations. .. code-block:: javascript diff --git a/source/reference/privilege-actions.txt b/source/reference/privilege-actions.txt index 6f0f3c867ff..7fbed05869b 100644 --- a/source/reference/privilege-actions.txt +++ b/source/reference/privilege-actions.txt @@ -265,6 +265,13 @@ Database Management Actions User can kill **any** cursor, even cursors created by other users. Apply this action to collection resources. +.. authaction:: planCacheIndexFilter + + User can run the :dbcommand:`planCacheClearFilters`, + :dbcommand:`planCacheListFilters`, and + :dbcommand:`planCacheSetFilter` commands. Apply the + :authaction:`planCacheIndexFilter` action to collection resources. + .. authaction:: revokeRole User can remove any role from any user from any database in the system. @@ -302,6 +309,11 @@ Database Management Actions Apply this action to database resources. +.. authaction:: setFeatureCompatibilityVersion + + User can run the :dbcommand:`setFeatureCompatibilityVersion` command. + Apply this action to the ``cluster`` resource. + .. authaction:: unlock User can perform the :method:`db.fsyncUnlock()` method. Apply this diff --git a/source/reference/program/mongo.txt b/source/reference/program/mongo.txt index f97890f2fdf..329a36086c5 100644 --- a/source/reference/program/mongo.txt +++ b/source/reference/program/mongo.txt @@ -2,7 +2,7 @@ .. default-domain:: mongodb -.. only:: (not man) +.. cond:: (not man) .. binary:: mongo @@ -435,7 +435,7 @@ Core Options Specifies a JavaScript file to run and then exit. Generally this should be the last option specified. - .. optional:: + .. note:: Optional To specify a JavaScript file to execute *and* allow :program:`mongo` to prompt you for a password using diff --git a/source/reference/program/mongod.txt b/source/reference/program/mongod.txt index d6cfb153029..71c82a35e9e 100644 --- a/source/reference/program/mongod.txt +++ b/source/reference/program/mongod.txt @@ -2,7 +2,7 @@ .. default-domain:: mongodb -.. only:: (not man) +.. cond:: (not man) .. binary:: mongod diff --git a/source/reference/program/mongokerberos.txt b/source/reference/program/mongokerberos.txt index b85d4439afe..719fc495811 100644 --- a/source/reference/program/mongokerberos.txt +++ b/source/reference/program/mongokerberos.txt @@ -2,7 +2,7 @@ .. default-domain:: mongodb -.. only:: (not man) +.. cond:: (not man) .. binary:: mongokerberos diff --git a/source/reference/program/mongoldap.txt b/source/reference/program/mongoldap.txt index 0551a638b6f..ff187ff43c2 100644 --- a/source/reference/program/mongoldap.txt +++ b/source/reference/program/mongoldap.txt @@ -2,7 +2,7 @@ .. default-domain:: mongodb -.. only:: (not man) +.. cond:: (not man) .. binary:: mongoldap diff --git a/source/reference/program/mongos.txt b/source/reference/program/mongos.txt index c35404b688b..289e98408cd 100644 --- a/source/reference/program/mongos.txt +++ b/source/reference/program/mongos.txt @@ -2,7 +2,7 @@ .. default-domain:: mongodb -.. only:: (not man) +.. cond:: (not man) .. binary:: mongos diff --git a/source/release-notes/2.4-upgrade.txt b/source/release-notes/2.4-upgrade.txt index 5e4f50a00ee..1fa2f673c08 100644 --- a/source/release-notes/2.4-upgrade.txt +++ b/source/release-notes/2.4-upgrade.txt @@ -210,7 +210,7 @@ operations. :term:`sharded cluster`, as described in :ref:`sharding-balancing-disable-temporarily`. - .. optional:: + .. note:: Optional For additional security during the upgrade, you can make a backup of the config database using :binary:`~bin.mongodump` or @@ -265,7 +265,7 @@ operations. require manual intervention. To continue the upgrade process, you must follow the :ref:`upgrade-cluster-resync` procedure. - .. optional:: + .. note:: Optional If the :binary:`~bin.mongos` logs show the upgrade waiting for the upgrade lock, a previous upgrade process may still be active or diff --git a/source/tutorial/add-shards-to-shard-cluster.txt b/source/tutorial/add-shards-to-shard-cluster.txt index 83a6fb7754a..c56c73c305f 100644 --- a/source/tutorial/add-shards-to-shard-cluster.txt +++ b/source/tutorial/add-shards-to-shard-cluster.txt @@ -55,7 +55,7 @@ instance. name of the replica set and specify a member of the set. In production deployments, all shards should be replica sets. - .. optional:: + .. note:: Optional You can instead use the :dbcommand:`addShard` database command, which lets you specify a name and maximum size for the diff --git a/source/tutorial/configure-audit-filters.txt b/source/tutorial/configure-audit-filters.txt index 7e1dbf83bbd..71a42f6bba1 100644 --- a/source/tutorial/configure-audit-filters.txt +++ b/source/tutorial/configure-audit-filters.txt @@ -133,8 +133,8 @@ that occur against the ``test`` database by using the filter: path: data/db/auditLog.bson filter: '{ atype: "authenticate", "param.db": "test" }' -To filter on all :authaction:`authenticate` operations across -databases, use the filter ``{ atype: "authenticate" }``. +To filter on all ``authenticate`` operations across databases, omit +``"param.db": "test"`` and use the filter ``{ atype: "authenticate" }``. Filter on Collection Creation and Drop Operations for a Single Database ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -215,9 +215,9 @@ with roles that inherit from :authrole:`readWrite`, by using the filter: Filter on Read and Write Operations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To capture :authaction:`read` and :authaction:`write` operations in the -audit, you must also enable the audit system to log authorization -successes using the :parameter:`auditAuthorizationSuccess` parameter. +To capture read and write operations in the audit, you must also +enable the audit system to log authorization successes using the +:parameter:`auditAuthorizationSuccess` parameter. [#authorization-agnostic]_ .. note:: @@ -260,9 +260,9 @@ The following example audits the :method:`~db.collection.find()`, Filter on Read and Write Operations for a Collection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To capture :authaction:`read` and :authaction:`write` operations in the -audit, you must also enable the audit system to log authorization -successes using the :parameter:`auditAuthorizationSuccess` parameter. +To capture read and write operations in the audit, you must also +enable the audit system to log authorization successes using the +:parameter:`auditAuthorizationSuccess` parameter. [#authorization-agnostic]_ .. note:: diff --git a/source/tutorial/configure-linux-iptables-firewall.txt b/source/tutorial/configure-linux-iptables-firewall.txt index 44b1eb87259..adc79ca951d 100644 --- a/source/tutorial/configure-linux-iptables-firewall.txt +++ b/source/tutorial/configure-linux-iptables-firewall.txt @@ -82,7 +82,7 @@ port ``27017``, which allows the application server to connect to the :binary:`~bin.mongod` instance. The second rule, allows outgoing traffic from the :binary:`~bin.mongod` to reach the application server. -.. optional:: +.. note:: Optional If you have only one application server, you can replace ```` with either the IP address itself, such as: diff --git a/source/tutorial/convert-secondary-into-arbiter.txt b/source/tutorial/convert-secondary-into-arbiter.txt index 541fc195dca..07225ba3e71 100644 --- a/source/tutorial/convert-secondary-into-arbiter.txt +++ b/source/tutorial/convert-secondary-into-arbiter.txt @@ -65,7 +65,7 @@ Convert Secondary to Arbiter and Reuse the Port Number mv /data/db /data/db-old - .. optional:: + .. note:: Optional You may remove the data instead. @@ -178,6 +178,6 @@ Convert Secondary to Arbiter Running on a New Port Number mv /data/db /data/db-old - .. optional:: + .. note:: Optional You may remove the data instead. diff --git a/source/tutorial/expand-replica-set.txt b/source/tutorial/expand-replica-set.txt index 02f227547d9..5903889f79d 100644 --- a/source/tutorial/expand-replica-set.txt +++ b/source/tutorial/expand-replica-set.txt @@ -136,7 +136,7 @@ Add a Member to an Existing Replica Set For more information on configuration options, see the :binary:`~bin.mongod` manual page. - .. optional:: + .. note:: Optional You can specify the data directory, replica set name, and the ip binding in the ``mongod.conf`` :doc:`configuration file diff --git a/source/tutorial/insert-documents.txt b/source/tutorial/insert-documents.txt index 04012b5a814..6ef7460ce23 100644 --- a/source/tutorial/insert-documents.txt +++ b/source/tutorial/insert-documents.txt @@ -28,7 +28,6 @@ This page provides examples of insert operations in MongoDB. .. note:: Creating a Collection - If the collection does not currently exist, insert operations will create the collection. @@ -39,294 +38,311 @@ Insert a Single Document .. tabs-drivers:: - tabs: - - id: shell - content: | - :method:`db.collection.insertOne()` inserts a *single* - :ref:`document` into a collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, MongoDB adds the ``_id`` field with an - ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: compass - content: | - To insert a single document using :ref:`MongoDB Compass `: - - 1. Navigate to the collection you wish to insert the document - into: - - a. In the left-hand MongoDB Compass navigation pane, click - the database to which your target collection belongs. - - b. From the database view, click the target collection name. - - 2. Click the :guilabel:`Insert Document` button: - - .. figure:: /images/compass-insert-button.png - :alt: Compass insert button - - 3. For each field in the document, select the field type and - fill in the field name and value. Add fields by clicking - the last line number, then clicking - :guilabel:`Add Field After ...` - - - For ``Object`` types, add nested fields by clicking the - last field's number and selecting - :guilabel:`Add Field After ...` - - - For ``Array`` types, add additional elements to the array - by clicking the last element's line number and selecting - :guilabel:`Add Array Element After ...` - - 4. Once all fields have been filled out, click :guilabel:`Insert`. - - The following example inserts a new document into the - ``test.inventory`` collection: - - - id: python - content: | - :py:meth:`pymongo.collection.Collection.insert_one` inserts a - *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the PyMongo driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: motor - content: | - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_one` inserts a - *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the Motor driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: java-sync - content: | - com.mongodb.client.MongoCollection.insertOne_ - inserts a *single* :ref:`document` into - a collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the driver adds the ``_id`` field with an - ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: java-async - content: | - `com.mongodb.reactivestreams.client.MongoCollection.insertOne `_ - inserts a *single* :ref:`document` into - a collection with the `Java Reactive Streams - Driver `_: - - .. code-block:: json - - { item: "canvas", qty: 100, tags: ["cotton"], size: { h: 28, w: 35.5, uom: "cm" } } - - The following example inserts the document above into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the driver adds the ``_id`` field with an - ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: nodejs - content: | - :node-api:`Collection.insertOne() ` - inserts a *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the Node.js driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: php - content: | - :phpmethod:`MongoDB\\Collection::insertOne() ` - inserts a *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the PHP driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: perl - content: | - :perl-api:`MongoDB::Collection::insert_one()` - inserts a *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the Perl driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: ruby - content: | - :ruby-api:`Mongo::Collection#insert_one()` - inserts a *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the Ruby driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: scala - content: | - :scala-api:`collection.insertOne()` - inserts a *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the Scala driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: csharp - content: | - :csharp-api:`IMongoCollection.InsertOne() ` - inserts a *single* :ref:`document` into a - collection. - - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the C# driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. - - - id: go - content: | - - :go-api:`Collection.InsertOne ` - inserts a *single* :ref:`document` into a - collection. + .. tab:: + :tabid: shell + + :method:`db.collection.insertOne()` inserts a *single* + :ref:`document` into a collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, MongoDB adds the ``_id`` field with an + ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: compass + + To insert a single document using :ref:`MongoDB Compass `: + + 1. Navigate to the collection you wish to insert the document + into: + + a. In the left-hand MongoDB Compass navigation pane, click + the database to which your target collection belongs. + + b. From the database view, click the target collection name. + + 2. Click the :guilabel:`Insert Document` button: + + .. figure:: /images/compass-insert-button.png + :alt: Compass insert button + + 3. For each field in the document, select the field type and + fill in the field name and value. Add fields by clicking + the last line number, then clicking + :guilabel:`Add Field After ...` + + - For ``Object`` types, add nested fields by clicking the + last field's number and selecting + :guilabel:`Add Field After ...` + + - For ``Array`` types, add additional elements to the array + by clicking the last element's line number and selecting + :guilabel:`Add Array Element After ...` + + 4. Once all fields have been filled out, click :guilabel:`Insert`. + + The following example inserts a new document into the + ``test.inventory`` collection: + + .. tab:: + :tabid: python + + :py:meth:`pymongo.collection.Collection.insert_one` inserts a + *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the PyMongo driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: motor + + :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_one` inserts a + *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the Motor driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: java-sync + + com.mongodb.client.MongoCollection.insertOne_ + inserts a *single* :ref:`document` into + a collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the driver adds the ``_id`` field with an + ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: java-async + + `com.mongodb.reactivestreams.client.MongoCollection.insertOne `_ + inserts a *single* :ref:`document` into + a collection with the `Java Reactive Streams + Driver `_: + + .. code-block:: json + + { item: "canvas", qty: 100, tags: ["cotton"], size: { h: 28, w: 35.5, uom: "cm" } } + + The following example inserts the document above into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the driver adds the ``_id`` field with an + ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: nodejs + + :node-api:`Collection.insertOne() ` + inserts a *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the Node.js driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: php + + :phpmethod:`MongoDB\\Collection::insertOne() ` + inserts a *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the PHP driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: perl + + :perl-api:`MongoDB::Collection::insert_one()` + inserts a *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the Perl driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: ruby + + :ruby-api:`Mongo::Collection#insert_one()` + inserts a *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the Ruby driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: scala + + :scala-api:`collection.insertOne()` + inserts a *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the Scala driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: csharp + + :csharp-api:`IMongoCollection.InsertOne() ` + inserts a *single* :ref:`document` into a + collection. + + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the C# driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: go + + :go-api:`Collection.InsertOne ` + inserts a *single* :ref:`document` into a + collection. - The following example inserts a new document into the - ``inventory`` collection. If the document does not specify - an ``_id`` field, the driver adds the ``_id`` field - with an ObjectId value to the new document. See - :ref:`write-op-insert-behavior`. + The following example inserts a new document into the + ``inventory`` collection. If the document does not specify + an ``_id`` field, the driver adds the ``_id`` field + with an ObjectId value to the new document. See + :ref:`write-op-insert-behavior`. .. include:: /includes/driver-examples/driver-example-insert-1.rst .. tabs-drivers:: - tabs: - - id: shell - content: | - :method:`~db.collection.insertOne()` returns a document that - includes the newly inserted document's ``_id`` field value. For - an example of a return document, see - :ref:`db.collection.insertOne() reference`. - - - id: compass - content: | - .. note:: - - MongoDB Compass generates the ``_id`` field and its value - automatically. The generated - :term:`ObjectId` consists of a - unique randomly generated hexadecimal value. - - You can change this value prior to inserting your document - so long as it remains unique and is a valid ``ObjectId``. - For more information on the ``_id`` field, see - :ref:`_id Field `. - - - id: python - content: | - :py:meth:`~pymongo.collection.Collection.insert_one` returns an - instance of :py:class:`pymongo.results.InsertOneResult` whose - ``inserted_id`` field contains the ``_id`` of the newly - inserted document. - - - id: motor - content: | - :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.insert_one` returns an - instance of :py:class:`pymongo.results.InsertOneResult` whose - ``inserted_id`` field contains the ``_id`` of the newly - inserted document. - - - id: java-sync - content: | - - - id: java-async - content: | - `com.mongodb.reactivestreams.client.MongoCollection.insertOne `_ - returns a `Publisher `_ - object. The ``Publisher`` inserts the document into a collection when subscribers request data. - - - id: nodejs - content: | - :node-api:`insertOne() ` returns a - promise that provides a ``result``. The ``result.insertedId`` - promise contains the ``_id`` of the newly inserted document. - - - id: php - content: | - Upon successful insert, the - :phpmethod:`insertOne() ` - method returns an instance of - :phpclass:`MongoDB\\InsertOneResult ` - whose - :phpmethod:`getInsertedId() ` - method returns the ``_id`` of the newly inserted document. - - - id: perl - content: | - Upon successful insert, the - :perl-api:`insert_one()` method returns - an instance of - :perl-api:`MongoDB::InsertOneResult` whose - ``inserted_id`` attribute contains the ``_id`` of the newly - inserted document. - - - id: ruby - content: | - Upon successful insert, the - :ruby-api:`insert_one()` - method returns an instance of - :ruby-api:`Mongo::Operation::Result`, whose - ``inserted_id`` attribute contains the ``_id`` of the newly - inserted document. - - - id: scala - content: | - Upon successful insert, the - :scala-api:`collection.insertOne()` - method returns an instance of - :scala-api:`collection.insertOne().results();` whose - ``inserted_id`` attribute contains the ``_id`` of the newly - inserted document. - - - id: csharp - content: | - - - id: go - content: | - - :go-api:`Collection.InsertOne ` - function returns an instance of - :go-api:`InsertOneResult` whose - ``InsertedID`` attribute contains the ``_id`` of the newly - inserted document. + .. tab:: + :tabid: shell + + :method:`~db.collection.insertOne()` returns a document that + includes the newly inserted document's ``_id`` field value. For + an example of a return document, see + :ref:`db.collection.insertOne() reference`. + + .. tab:: + :tabid: compass + + .. note:: + + MongoDB Compass generates the ``_id`` field and its value + automatically. The generated + :term:`ObjectId` consists of a + unique randomly generated hexadecimal value. + + You can change this value prior to inserting your document + so long as it remains unique and is a valid ``ObjectId``. + For more information on the ``_id`` field, see + :ref:`_id Field `. + + .. tab:: + :tabid: python + + :py:meth:`~pymongo.collection.Collection.insert_one` returns an + instance of :py:class:`pymongo.results.InsertOneResult` whose + ``inserted_id`` field contains the ``_id`` of the newly + inserted document. + + .. tab:: + :tabid: motor + + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.insert_one` returns an + instance of :py:class:`pymongo.results.InsertOneResult` whose + ``inserted_id`` field contains the ``_id`` of the newly + inserted document. + + .. tab:: + :tabid: java-sync + + `com.mongodb.reactivestreams.client.MongoCollection.insertOne `_ + returns a `Publisher `_ + object. The ``Publisher`` inserts the document into a collection when subscribers request data. + + .. tab:: + :tabid: nodejs + + :node-api:`insertOne() ` returns a + promise that provides a ``result``. The ``result.insertedId`` + promise contains the ``_id`` of the newly inserted document. + + .. tab:: + :tabid: php + + Upon successful insert, the + :phpmethod:`insertOne() ` + method returns an instance of + :phpclass:`MongoDB\\InsertOneResult ` + whose + :phpmethod:`getInsertedId() ` + method returns the ``_id`` of the newly inserted document. + + .. tab:: + :tabid: perl + + Upon successful insert, the + :perl-api:`insert_one()` method returns + an instance of + :perl-api:`MongoDB::InsertOneResult` whose + ``inserted_id`` attribute contains the ``_id`` of the newly + inserted document. + + .. tab:: + :tabid: ruby + + Upon successful insert, the + :ruby-api:`insert_one()` + method returns an instance of + :ruby-api:`Mongo::Operation::Result`, whose + ``inserted_id`` attribute contains the ``_id`` of the newly + inserted document. + + .. tab:: + :tabid: scala + + Upon successful insert, the + :scala-api:`collection.insertOne()` + method returns an instance of + :scala-api:`collection.insertOne().results();` whose + ``inserted_id`` attribute contains the ``_id`` of the newly + inserted document. + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: go + + :go-api:`Collection.InsertOne ` + function returns an instance of + :go-api:`InsertOneResult` whose + ``InsertedID`` attribute contains the ``_id`` of the newly + inserted document. To retrieve the document that you just inserted, :ref:`query the collection `: @@ -347,298 +363,316 @@ upper-right to set the language of the examples on this page. .. tabs-drivers:: - tabs: - - id: shell - content: | - .. versionadded:: 3.2 - - :method:`db.collection.insertMany()` can insert *multiple* - :ref:`documents ` into a collection. Pass an - array of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, MongoDB adds the ``_id`` field with an ObjectId - value to each document. See :ref:`write-op-insert-behavior`. - - - id: compass - content: | - Currently, MongoDB Compass does not support inserting multiple - documents in a single operation. - - - id: python - content: | - .. versionadded:: 3.2 - - :py:meth:`pymongo.collection.Collection.insert_many` can insert - *multiple* :ref:`documents ` into a - collection. Pass an iterable of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the PyMongo driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: motor - content: | - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_many` - can insert *multiple* :ref:`documents ` - into a collection. Pass an iterable of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the PyMongo driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: java-sync - content: | - .. versionadded:: 3.2 - - com.mongodb.client.MongoCollection.insertMany_ - can insert *multiple* :ref:`documents ` - into a collection. Pass a list of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: java-async - content: | - .. versionadded:: 3.2 - - `com.mongodb.reactivestreams.client.MongoCollection.html.insertMany - `_ - inserts the following documents with the `Java Reactive Streams - Driver `_: - - .. code-block:: json - - { item: "journal", qty: 25, tags: ["blank", "red"], size: { h: 14, w: 21, uom: "cm" } } - { item: "mat", qty: 85, tags: ["gray"], size: { h: 27.9, w: 35.5, uom: "cm" } } - { item: "mousepad", qty: 25, tags: ["gel", "blue"], size: { h: 19, w: 22.85, uom: "cm" } } - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: nodejs - content: | - .. versionadded:: 3.2 - - :node-api:`Collection.insertMany() ` - can insert *multiple* :ref:`documents ` - into a collection. Pass an array of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the Node.js driver adds the ``_id`` field with - an ObjectId value to each document. See - :ref:`write-op-insert-behavior`. - - - id: php - content: | - .. versionadded:: 3.2 - - :phpmethod:`MongoDB\\Collection::insertMany() ` - can insert *multiple* :ref:`documents ` into a - collection. Pass an array of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the PHP driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: perl - content: | - .. versionadded:: 3.2 - - :perl-api:`MongoDB::Collection::insert_many()` - can insert *multiple* :ref:`documents ` into a - collection. Pass an array reference of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the Perl driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: ruby - content: | - .. versionadded:: 3.2 - - :ruby-api:`Mongo::Collection#insert_many()` - can insert *multiple* :ref:`documents ` into a - collection. Pass an array of documents to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the Ruby driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: scala - content: | - .. versionadded:: 3.2 - - :scala-api:`collection.insertMany()` - can insert *multiple* :ref:`documents ` into a - collection. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the Scala driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: csharp - content: | - .. versionadded:: 3.2 - - :csharp-api:`IMongoCollection.InsertMany()` - can insert *multiple* :ref:`documents ` - into a collection. Pass an enumerable collection of documents - to the method. - - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. - - - id: go - content: | - - :go-api:`Collection.InsertMany ` - can insert *multiple* :ref:`documents ` into a - collection. + .. tab:: + :tabid: shell + + .. versionadded:: 3.2 + + :method:`db.collection.insertMany()` can insert *multiple* + :ref:`documents ` into a collection. Pass an + array of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, MongoDB adds the ``_id`` field with an ObjectId + value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: compass + + Currently, MongoDB Compass does not support inserting multiple + documents in a single operation. + + .. tab:: + :tabid: python + + .. versionadded:: 3.2 + + :py:meth:`pymongo.collection.Collection.insert_many` can insert + *multiple* :ref:`documents ` into a + collection. Pass an iterable of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the PyMongo driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: motor + + :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_many` + can insert *multiple* :ref:`documents ` + into a collection. Pass an iterable of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the PyMongo driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: java-sync + + .. versionadded:: 3.2 + + com.mongodb.client.MongoCollection.insertMany_ + can insert *multiple* :ref:`documents ` + into a collection. Pass a list of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: java-async + + .. versionadded:: 3.2 + + `com.mongodb.reactivestreams.client.MongoCollection.html.insertMany + `_ + inserts the following documents with the `Java Reactive Streams + Driver `_: + + .. code-block:: json + + { item: "journal", qty: 25, tags: ["blank", "red"], size: { h: 14, w: 21, uom: "cm" } } + { item: "mat", qty: 85, tags: ["gray"], size: { h: 27.9, w: 35.5, uom: "cm" } } + { item: "mousepad", qty: 25, tags: ["gel", "blue"], size: { h: 19, w: 22.85, uom: "cm" } } + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: nodejs + + .. versionadded:: 3.2 + + :node-api:`Collection.insertMany() ` + can insert *multiple* :ref:`documents ` + into a collection. Pass an array of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the Node.js driver adds the ``_id`` field with + an ObjectId value to each document. See + :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: php + + .. versionadded:: 3.2 + + :phpmethod:`MongoDB\\Collection::insertMany() ` + can insert *multiple* :ref:`documents ` into a + collection. Pass an array of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the PHP driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: perl + + .. versionadded:: 3.2 + + :perl-api:`MongoDB::Collection::insert_many()` + can insert *multiple* :ref:`documents ` into a + collection. Pass an array reference of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the Perl driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: ruby + + .. versionadded:: 3.2 + + :ruby-api:`Mongo::Collection#insert_many()` + can insert *multiple* :ref:`documents ` into a + collection. Pass an array of documents to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the Ruby driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: scala + + .. versionadded:: 3.2 + + :scala-api:`collection.insertMany()` + can insert *multiple* :ref:`documents ` into a + collection. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the Scala driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: csharp + + .. versionadded:: 3.2 + + :csharp-api:`IMongoCollection.InsertMany()` + can insert *multiple* :ref:`documents ` + into a collection. Pass an enumerable collection of documents + to the method. + + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + + .. tab:: + :tabid: go + + :go-api:`Collection.InsertMany ` + can insert *multiple* :ref:`documents ` into a + collection. - The following example inserts three new documents into the - ``inventory`` collection. If the documents do not specify an - ``_id`` field, the driver adds the ``_id`` field with - an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + The following example inserts three new documents into the + ``inventory`` collection. If the documents do not specify an + ``_id`` field, the driver adds the ``_id`` field with + an ObjectId value to each document. See :ref:`write-op-insert-behavior`. .. include:: /includes/driver-examples/driver-example-insert-3.rst .. tabs-drivers:: - tabs: - - id: shell - content: | - :method:`~db.collection.insertMany()` returns a document that includes - the newly inserted documents ``_id`` field values. See the - :ref:`reference ` for an example. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: python - content: | - :py:meth:`~pymongo.collection.Collection.insert_many` returns - an instance of :py:class:`pymongo.results.InsertManyResult` - whose ``inserted_ids`` field is a list containing the ``_id`` - of each newly inserted document. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: motor - content: | - :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.insert_many` - returns an instance of :py:class:`pymongo.results.InsertManyResult` - whose ``inserted_ids`` field is a list containing the ``_id`` - of each newly inserted document. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: java-sync - content: | - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: java-async - content: | - `com.mongodb.reactivestreams.client.MongoCollection.html.insertMany - `_ - returns a `Publisher `_ - object. The ``Publisher`` inserts the document into a collection - when subscribers request data. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: nodejs - content: | - :node-api:`insertMany() ` returns a - promise that provides a ``result``. The ``result.insertedIds`` - field contains an array with the ``_id`` of each newly inserted - document. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: php - content: | - Upon successful insert, the - :phpmethod:`insertMany() ` - method - returns an instance of - :phpclass:`MongoDB\\InsertManyResult ` - whose - :phpmethod:`getInsertedIds() ` - method returns the ``_id`` of each newly inserted document. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: perl - content: | - Upon successful insert, the - :perl-api:`insert_many()` method - returns an instance of - :perl-api:`MongoDB::InsertManyResult` - whose ``inserted_ids`` attribute is a list containing the - ``_id`` of each newly inserted document. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: ruby - content: | - Upon successful insert, the - :ruby-api:`insert_many()` method - returns an instance of - :ruby-api:`Mongo::BulkWrite::Result` - whose ``inserted_ids`` attribute is a list containing the - ``_id`` of each newly inserted document. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: scala - content: | - Upon successful insert, the - :scala-api:`insertMany()` - method returns an `Observable `_ with a type parameter indicating when - the operation has completed or with either a - ``com.mongodb.DuplicateKeyException`` or - ``com.mongodb.MongoException``. - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: csharp - content: | - - To retrieve the inserted documents, :ref:`query the collection - `: - - - id: go - content: | - - To retrieve the inserted documents, :ref:`query the collection - `: + .. tab:: + :tabid: shell + + :method:`~db.collection.insertMany()` returns a document that includes + the newly inserted documents ``_id`` field values. See the + :ref:`reference ` for an example. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: python + + :py:meth:`~pymongo.collection.Collection.insert_many` returns + an instance of :py:class:`pymongo.results.InsertManyResult` + whose ``inserted_ids`` field is a list containing the ``_id`` + of each newly inserted document. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: motor + + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.insert_many` + returns an instance of :py:class:`pymongo.results.InsertManyResult` + whose ``inserted_ids`` field is a list containing the ``_id`` + of each newly inserted document. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: java-sync + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: java-async + + `com.mongodb.reactivestreams.client.MongoCollection.html.insertMany + `_ + returns a `Publisher `_ + object. The ``Publisher`` inserts the document into a collection + when subscribers request data. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: nodejs + + :node-api:`insertMany() ` returns a + promise that provides a ``result``. The ``result.insertedIds`` + field contains an array with the ``_id`` of each newly inserted + document. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: php + + Upon successful insert, the + :phpmethod:`insertMany() ` + method + returns an instance of + :phpclass:`MongoDB\\InsertManyResult ` + whose + :phpmethod:`getInsertedIds() ` + method returns the ``_id`` of each newly inserted document. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: perl + + Upon successful insert, the + :perl-api:`insert_many()` method + returns an instance of + :perl-api:`MongoDB::InsertManyResult` + whose ``inserted_ids`` attribute is a list containing the + ``_id`` of each newly inserted document. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: ruby + + Upon successful insert, the + :ruby-api:`insert_many()` method + returns an instance of + :ruby-api:`Mongo::BulkWrite::Result` + whose ``inserted_ids`` attribute is a list containing the + ``_id`` of each newly inserted document. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: scala + + Upon successful insert, the + :scala-api:`insertMany()` + method returns an `Observable `_ with a type parameter indicating when + the operation has completed or with either a + ``com.mongodb.DuplicateKeyException`` or + ``com.mongodb.MongoException``. + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: csharp + + To retrieve the inserted documents, :ref:`query the collection + `: + + .. tab:: + :tabid: go + + To retrieve the inserted documents, :ref:`query the collection + `: .. include:: /includes/driver-examples/driver-example-query-7.rst @@ -677,124 +711,136 @@ requested from MongoDB for write operations. For details, see .. tabs-drivers:: - tabs: - - id: shell - content: | - .. seealso:: + .. tab:: + :tabid: shell + + .. seealso:: + + - :method:`db.collection.insertOne()` + + - :method:`db.collection.insertMany()` + + - :ref:`additional-inserts` + + .. tab:: + :tabid: python + + .. seealso:: + + - :py:meth:`pymongo.collection.Collection.insert_one` + + - :py:meth:`pymongo.collection.Collection.insert_many` + + - :ref:`additional-inserts` + + .. tab:: + :tabid: motor + + .. seealso:: + + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_one` + + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_many` - - :method:`db.collection.insertOne()` + - :ref:`additional-inserts` - - :method:`db.collection.insertMany()` + .. tab:: + :tabid: java-sync - - :ref:`additional-inserts` + .. seealso:: - - id: python - content: | - .. seealso:: + - com.mongodb.client.MongoCollection.insertOne_ - - :py:meth:`pymongo.collection.Collection.insert_one` + - com.mongodb.client.MongoCollection.insertMany_ - - :py:meth:`pymongo.collection.Collection.insert_many` + - `Additional Java Synchronous Driver Write Examples`_ - - :ref:`additional-inserts` + .. tab:: + :tabid: java-async - - id: motor - content: | - .. seealso:: + .. seealso:: - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_one` + - `com.mongodb.reactivestreams.client.MongoCollection.insertOne `_ - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.insert_many` + - `com.mongodb.reactivestreams.client.MongoCollection.html.insertMany `_ - - :ref:`additional-inserts` + - `Java Reactive Streams Driver Quick Tour `_ - - id: java-sync - content: | - .. seealso:: + .. tab:: + :tabid: nodejs - - com.mongodb.client.MongoCollection.insertOne_ + .. seealso:: - - com.mongodb.client.MongoCollection.insertMany_ + - :node-api:`Collection.insertOne() ` - - `Additional Java Synchronous Driver Write Examples`_ + - :node-api:`Collection.insertMany() ` - - id: java-async - content: | - .. seealso:: + - :ref:`additional-inserts` - - `com.mongodb.reactivestreams.client.MongoCollection.insertOne `_ + .. tab:: + :tabid: php - - `com.mongodb.reactivestreams.client.MongoCollection.html.insertMany `_ + .. seealso:: - - `Java Reactive Streams Driver Quick Tour `_ + - :phpmethod:`MongoDB\\Collection::insertOne() ` - - id: nodejs - content: | - .. seealso:: + - :phpmethod:`MongoDB\\Collection::insertMany() ` - - :node-api:`Collection.insertOne() ` + - :ref:`additional-inserts` - - :node-api:`Collection.insertMany() ` + .. tab:: + :tabid: perl - - :ref:`additional-inserts` + .. seealso:: - - id: php - content: | - .. seealso:: + - :perl-api:`MongoDB::Collection::insert_one()` - - :phpmethod:`MongoDB\\Collection::insertOne() ` + - :perl-api:`MongoDB::Collection::insert_many()` - - :phpmethod:`MongoDB\\Collection::insertMany() ` + - :ref:`additional-inserts` - - :ref:`additional-inserts` + .. tab:: + :tabid: ruby - - id: perl - content: | - .. seealso:: + .. seealso:: - - :perl-api:`MongoDB::Collection::insert_one()` + - :ruby-api:`Mongo::Collection#insert_one()` - - :perl-api:`MongoDB::Collection::insert_many()` + - :ruby-api:`Mongo::Collection#insert_many()` - - :ref:`additional-inserts` + .. tab:: + :tabid: scala - - id: ruby - content: | - .. seealso:: + .. seealso:: - - :ruby-api:`Mongo::Collection#insert_one()` + - :scala-api:`collection.insertOne()` - - :ruby-api:`Mongo::Collection#insert_many()` + - :scala-api:`collection.insertMany()` - - id: scala - content: | - .. seealso:: + - :ref:`additional-inserts` - - :scala-api:`collection.insertOne()` + .. tab:: + :tabid: csharp - - :scala-api:`collection.insertMany()` + .. seealso:: - - :ref:`additional-inserts` + - :csharp-api:`IMongoCollection.InsertOne() ` - - id: csharp - content: | - .. seealso:: + - :csharp-api:`IMongoCollection.InsertMany() ` - - :csharp-api:`IMongoCollection.InsertOne() ` + - :ref:`additional-inserts` - - :csharp-api:`IMongoCollection.InsertMany() ` + .. tab:: + :tabid: go - - :ref:`additional-inserts` + .. seealso:: - - id: go - content: | - .. seealso:: + - :go-api:`Collection.InsertOne ` - - :go-api:`Collection.InsertOne ` + - :go-api:`Collection.InsertMany ` - - :go-api:`Collection.InsertMany ` + - :ref:`additional-inserts` - - :ref:`additional-inserts` .. toctree:: :titlesonly: :hidden: diff --git a/source/tutorial/update-documents.txt b/source/tutorial/update-documents.txt index 73f542db208..a8b62eab4c3 100644 --- a/source/tutorial/update-documents.txt +++ b/source/tutorial/update-documents.txt @@ -30,177 +30,188 @@ upper-right to set the language of the following examples. .. tabs-drivers:: - tabs: - - id: shell - content: | - This page uses the following :binary:`~bin.mongosh` methods: + .. tab:: + :tabid: shell - - :method:`db.collection.updateOne(\, \, \) ` + This page uses the following :binary:`~bin.mongosh` methods: - - :method:`db.collection.updateMany(\, \, \) ` + - :method:`db.collection.updateOne(\, \, \) ` - - :method:`db.collection.replaceOne(\, \, \) ` + - :method:`db.collection.updateMany(\, \, \) ` - |populate-inventory| + - :method:`db.collection.replaceOne(\, \, \) ` - - id: compass - content: | + |populate-inventory| - This page uses :ref:`MongoDB Compass ` to - update the documents. + .. tab:: + :tabid: compass - The examples on this page use the ``inventory`` collection. - Populate the ``inventory`` collection with the following - documents: + This page uses :ref:`MongoDB Compass ` to + update the documents. - - id: python - content: | - This page uses the - following :api:`PyMongo ` - Python driver methods: + The examples on this page use the ``inventory`` collection. + Populate the ``inventory`` collection with the following + documents: - - :py:meth:`pymongo.collection.Collection.update_one` + .. tab:: + :tabid: python - - :py:meth:`pymongo.collection.Collection.update_many` + This page uses the + following :api:`PyMongo ` + Python driver methods: - - :py:meth:`pymongo.collection.Collection.replace_one` + - :py:meth:`pymongo.collection.Collection.update_one` - |populate-inventory| + - :py:meth:`pymongo.collection.Collection.update_many` - - id: motor - content: | - This page uses the - following `Motor `_ - driver methods: + - :py:meth:`pymongo.collection.Collection.replace_one` + + |populate-inventory| - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_one` + .. tab:: + :tabid: motor - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_many` + This page uses the + following `Motor `_ + driver methods: - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.replace_one` + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_one` - |populate-inventory| + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_many` - - id: java-sync - content: | - This page uses the - following `Java Synchronous Driver`_ methods: + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.replace_one` - - com.mongodb.client.MongoCollection.updateOne_ + |populate-inventory| - - com.mongodb.client.MongoCollection.updateMany_ + .. tab:: + :tabid: java-sync - - com.mongodb.client.MongoCollection.replaceOne_ + This page uses the + following `Java Synchronous Driver`_ methods: - |populate-inventory| + - com.mongodb.client.MongoCollection.updateOne_ - - id: java-async - content: | - This page uses the - following `Java Reactive Streams Driver - `_ methods: + - com.mongodb.client.MongoCollection.updateMany_ - - `com.mongodb.reactivestreams.client.MongoCollection.updateOne - `_ + - com.mongodb.client.MongoCollection.replaceOne_ - - `com.mongodb.reactivestreams.client.MongoCollection.updateMany - `_ + |populate-inventory| - - `com.mongodb.reactivestreams.client.MongoCollection.replaceOne - `_ + .. tab:: + :tabid: java-async - |populate-inventory| + This page uses the + following `Java Reactive Streams Driver + `_ methods: - - id: nodejs - content: | - This page uses the - following :node-docs:`MongoDB Node.js Driver <>` methods: + - `com.mongodb.reactivestreams.client.MongoCollection.updateOne + `_ - - :node-api:`Collection.updateOne() ` + - `com.mongodb.reactivestreams.client.MongoCollection.updateMany + `_ - - :node-api:`Collection.updateMany() ` + - `com.mongodb.reactivestreams.client.MongoCollection.replaceOne + `_ - - :node-api:`Collection.replaceOne() ` + |populate-inventory| - |populate-inventory| + .. tab:: + :tabid: nodejs - - id: php - content: | - This page uses the - following `MongoDB PHP Library `_ methods: + This page uses the + following :node-docs:`MongoDB Node.js Driver <>` methods: - - :phpmethod:`MongoDB\\Collection::updateOne() ` + - :node-api:`Collection.updateOne() ` - - :phpmethod:`MongoDB\\Collection::updateMany() ` + - :node-api:`Collection.updateMany() ` - - :phpmethod:`MongoDB\\Collection::replaceOne() ` + - :node-api:`Collection.replaceOne() ` - |populate-inventory| + |populate-inventory| - - id: perl - content: | - This page uses the - following `MongoDB Perl Driver `_ methods: + .. tab:: + :tabid: php - - :perl-api:`MongoDB::Collection::update_one()` + This page uses the following `MongoDB PHP Library + `_ methods: - - :perl-api:`MongoDB::Collection::update_many()` + - :phpmethod:`MongoDB\\Collection::updateOne() ` - - :perl-api:`MongoDB::Collection::replace_one()` + - :phpmethod:`MongoDB\\Collection::updateMany() ` - |populate-inventory| + - :phpmethod:`MongoDB\\Collection::replaceOne() ` - - id: ruby - content: | - This page uses the - following `MongoDB Ruby Driver `_ methods: + |populate-inventory| - - :ruby-api:`Mongo::Collection#update_one()` + .. tab:: + :tabid: perl - - :ruby-api:`Mongo::Collection#update_many()` + This page uses the following `MongoDB Perl Driver + `_ methods: - - :ruby-api:`Mongo::Collection#replace_one()` + - :perl-api:`MongoDB::Collection::update_one()` - |populate-inventory| + - :perl-api:`MongoDB::Collection::update_many()` - - id: scala - content: | - This page uses the - following `MongoDB Scala Driver `_ methods: + - :perl-api:`MongoDB::Collection::replace_one()` - - :scala-api:`collection.updateOne()` + |populate-inventory| - - :scala-api:`collection.updateMany()` + .. tab:: + :tabid: ruby - - :scala-api:`collection.replaceOne()` + This page uses the following `MongoDB Ruby Driver + `_ methods: - |populate-inventory| + - :ruby-api:`Mongo::Collection#update_one()` - - id: csharp - content: | - This page uses the - following `MongoDB C# Driver `_ methods: + - :ruby-api:`Mongo::Collection#update_many()` - - :csharp-api:`IMongoCollection.UpdateOne()` + - :ruby-api:`Mongo::Collection#replace_one()` - - :csharp-api:`IMongoCollection.UpdateMany()` + |populate-inventory| - - :csharp-api:`IMongoCollection.ReplaceOne() ` + .. tab:: + :tabid: scala - |populate-inventory| + This page uses the following `MongoDB Scala Driver + `_ methods: - - id: go - content: | - This page uses the - following `MongoDB Go Driver `_ functions: + - :scala-api:`collection.updateOne()` - - :go-api:`Collection.UpdateOne` + - :scala-api:`collection.updateMany()` - - :go-api:`Collection.UpdateMany` + - :scala-api:`collection.replaceOne()` - - :go-api:`Collection.ReplaceOne ` + |populate-inventory| + + .. tab:: + :tabid: csharp + + This page uses the following `MongoDB C# Driver + `_ methods: + + - :csharp-api:`IMongoCollection.UpdateOne()` + + - :csharp-api:`IMongoCollection.UpdateMany()` + + - :csharp-api:`IMongoCollection.ReplaceOne() ` + + |populate-inventory| + + .. tab:: + :tabid: go + + This page uses the following `MongoDB Go Driver + `_ functions: + + - :go-api:`Collection.UpdateOne` - |populate-inventory| + - :go-api:`Collection.UpdateMany` + + - :go-api:`Collection.ReplaceOne ` + + |populate-inventory| .. include:: /includes/driver-examples/driver-example-update-51.rst @@ -211,255 +222,264 @@ Update Documents in a Collection .. tabs-drivers:: - tabs: - - id: shell - content: | - To update a document, MongoDB provides - :manual:`update operators `, such - as :update:`$set`, to modify field values. + .. tab:: + :tabid: shell + + To update a document, MongoDB provides + :manual:`update operators `, such + as :update:`$set`, to modify field values. + + To use the update operators, pass to the update methods an + update document of the form: + + .. code-block:: javascript + + { + : { : , ... }, + : { : , ... }, + ... + } + + .. include:: /includes/fact-update-set-create-fields.rst + + .. tab:: + :tabid: compass + + To update a document in Compass, hover over the target + document and click the pencil icon: + + .. figure:: /images/compass-update-doc-button.png + :alt: Click edit document + + After clicking the pencil icon, the document enters edit mode: - To use the update operators, pass to the update methods an - update document of the form: + .. figure:: /images/compass-update-edit-mode.png + :alt: Document edit mode - .. code-block:: javascript + You can now change the this document by clicking the item you wish + to change and modifying the value. - { - : { : , ... }, - : { : , ... }, - ... - } + For detailed instructions on updating documents in Compass, + refer to the + :ref:`Compass documentation ` + or follow the :ref:`example ` below. - .. include:: /includes/fact-update-set-create-fields.rst + Once you are satisfied with your changes, click + :guilabel:`Update` to save the updated document. - - id: compass - content: | - To update a document in Compass, hover over the target - document and click the pencil icon: + Click :guilabel:`Cancel` to revert any modifications made to + the document and exit edit mode. - .. figure:: /images/compass-update-doc-button.png - :alt: Click edit document + .. tab:: + :tabid: python - After clicking the pencil icon, the document enters edit mode: + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - .. figure:: /images/compass-update-edit-mode.png - :alt: Document edit mode + To use the update operators, pass to the update methods an + update document of the form: - You can now change the this document by clicking the item you wish to - change and modifying the value. + .. code-block:: python - For detailed instructions on updating documents in Compass, - refer to the - :ref:`Compass documentation ` - or follow the :ref:`example ` below. + { + : { : , ... }, + : { : , ... }, + ... + } - Once you are satisfied with your changes, click - :guilabel:`Update` to save the updated document. + .. include:: /includes/fact-update-set-create-fields.rst - Click :guilabel:`Cancel` to revert any modifications made to - the document and exit edit mode. + .. tab:: + :tabid: motor - - id: python - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - To use the update operators, pass to the update methods an - update document of the form: + To use the update operators, pass to the update methods an + update document of the form: - .. code-block:: python + .. code-block:: python - { - : { : , ... }, - : { : , ... }, - ... - } + { + : { : , ... }, + : { : , ... }, + ... + } - .. include:: /includes/fact-update-set-create-fields.rst + .. include:: /includes/fact-update-set-create-fields.rst - - id: motor - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + .. tab:: + :tabid: java-sync - To use the update operators, pass to the update methods an - update document of the form: + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - .. code-block:: python + The driver provides the `com.mongodb.client.model.Updates + `__ + class to facilitate the creation of update documents. For example: - { - : { : , ... }, - : { : , ... }, - ... - } + .. code-block:: java - .. include:: /includes/fact-update-set-create-fields.rst + combine(set( , ), set(, ) ) - - id: java-sync - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + For a list of the update helpers, see + `com.mongodb.client.model.Updates + `__. - The driver provides the `com.mongodb.client.model.Updates `__ - class to facilitate the creation of update documents. For example: + .. include:: /includes/fact-update-set-create-fields.rst - .. code-block:: java + .. tab:: + :tabid: java-async - combine(set( , ), set(, ) ) + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - For a list of the update helpers, see `com.mongodb.client.model.Updates `__. + The driver provides the `com.mongodb.client.model.Updates + `__ + class to facilitate the creation of update documents. For example: - .. include:: /includes/fact-update-set-create-fields.rst + .. code-block:: java - - id: java-async - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + combine(set( , ), set(, ) ) - The driver provides the `com.mongodb.client.model.Updates `__ - class to facilitate the creation of update documents. For example: + For a list of the update helpers, see + `com.mongodb.client.model.Updates + `__. - .. code-block:: java + .. include:: /includes/fact-update-set-create-fields.rst - combine(set( , ), set(, ) ) + .. tab:: + :tabid: nodejs - For a list of the update helpers, see `com.mongodb.client.model.Updates `__. + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - .. include:: /includes/fact-update-set-create-fields.rst + To use the update operators, pass to the update methods an + update document of the form: - - id: nodejs - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + .. code-block:: javascript - To use the update operators, pass to the update methods an - update document of the form: + { + : { : , ... }, + : { : , ... }, + ... + } - .. code-block:: javascript + .. include:: /includes/fact-update-set-create-fields.rst - { - : { : , ... }, - : { : , ... }, - ... - } + .. tab:: + :tabid: php - .. include:: /includes/fact-update-set-create-fields.rst + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - - id: php - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + To use the update operators, pass to the update methods an + update document of the form: - To use the update operators, pass to the update methods an - update document of the form: + .. code-block:: php - .. code-block:: php + [ + => [ => , ... ], + => [ => , ... ], + ... + ] - [ - => [ => , ... ], - => [ => , ... ], - ... - ] + .. include:: /includes/fact-update-set-create-fields.rst - .. include:: /includes/fact-update-set-create-fields.rst + .. tab:: + :tabid: perl - - id: perl - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - To use the update operators, pass to the update methods an - update document of the form: + To use the update operators, pass to the update methods an + update document of the form: - .. code-block:: perl + .. code-block:: perl - { - => { => , ... }, - => { => , ... }, - ... - } + { + => { => , ... }, + => { => , ... }, + ... + } - .. include:: /includes/fact-update-set-create-fields.rst + .. include:: /includes/fact-update-set-create-fields.rst - - id: ruby - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + .. tab:: + :tabid: ruby - To use the update operators, pass to the update methods an - update document of the form: + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - .. code-block:: ruby + To use the update operators, pass to the update methods an + update document of the form: - { - => { => , ... }, - => { => , ... }, - ... - } + .. code-block:: ruby - .. include:: /includes/fact-update-set-create-fields.rst + { + => { => , ... }, + => { => , ... }, + ... + } - - id: csharp - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + .. include:: /includes/fact-update-set-create-fields.rst - To use the update operators, pass to the update methods an - update document of the form: + .. tab:: + :tabid: csharp - .. code-block:: c# + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - { - => { => , ... }, - => { => , ... }, - ... - } + To use the update operators, pass to the update methods an + update document of the form: - .. include:: /includes/fact-update-set-create-fields.rst + .. code-block:: c# - - id: scala - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + { + => { => , ... }, + => { => , ... }, + ... + } - To use the update operators, pass to the update methods an - update document of the form: + .. include:: /includes/fact-update-set-create-fields.rst - .. code-block:: scala + .. tab:: + :tabid: scala - ( - set (, ), - set (, ), - ... - ) + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. - .. include:: /includes/fact-update-set-create-fields.rst + To use the update operators, pass to the update methods an + update document of the form: - - id: go - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + .. code-block:: scala - .. include:: /includes/fact-update-set-create-fields.rst + ( + set (, ), + set (, ), + ... + ) + .. include:: /includes/fact-update-set-create-fields.rst - - id: go - content: | - To update a document, MongoDB provides - :manual:`update operators ` such - as :update:`$set` to modify field values. + .. tab:: + :tabid: go - .. include:: /includes/fact-update-set-create-fields.rst + To update a document, MongoDB provides + :manual:`update operators ` such + as :update:`$set` to modify field values. + + .. include:: /includes/fact-update-set-create-fields.rst .. note:: @@ -474,109 +494,122 @@ Update a Single Document .. tabs-drivers:: - tabs: - - id: shell - content: | - The following example uses the - :method:`db.collection.updateOne()` method on the - ``inventory`` collection to update the *first* document where - ``item`` equals ``"paper"``: - - - id: compass - content: | - The following example demonstrates using |compass| to modify - a single document where ``item: paper`` in the ``inventory`` - collection: - - .. note:: - - This example uses the Compass - :ref:`Table View ` to modify the - document. The editing process using the Compass - :ref:`List View ` follows a very - similar approach. - - For more information on the differences between Table View - and List View in Compass, refer to the - :ref:`Compass documentation `. - - - id: python - content: | - The following example uses the - :py:meth:`~pymongo.collection.Collection.update_one` method on - the ``inventory`` collection to update the *first* document - where ``item`` equals ``"paper"``: - - - id: motor - content: | - The following example uses the - :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_one` method on - the ``inventory`` collection to update the *first* document - where ``item`` equals ``"paper"``: - - - id: java-sync - content: | - The following example uses the - com.mongodb.client.MongoCollection.updateOne_ method on the - ``inventory`` collection to update the *first* document where - ``item`` equals ``"paper"``: - - - id: java-async - content: | - The following example uses the - `com.mongodb.reactivestreams.client.MongoCollection.updateOne - `_ - on the ``inventory`` collection to update the *first* document where - ``item`` equals ``"paper"``: - - - id: nodejs - content: | - The following example uses the - :node-api:`Collection.updateOne() ` - method on the ``inventory`` collection to update the *first* - document where ``item`` equals ``"paper"``: - - - id: php - content: | - The following example uses the - :phpmethod:`updateOne() ` - method on the ``inventory`` collection to update the *first* - document where ``item`` equals ``"paper"``: - - - id: perl - content: | - The following example uses the - :perl-api:`update_one()` method on the - ``inventory`` collection to update the *first* document where - ``item`` equals ``"paper"``: - - - id: ruby - content: | - The following example uses the - :ruby-api:`update_one()` method on the - ``inventory`` collection to update the *first* document where - ``item`` equals ``"paper"``: - - - id: scala - content: | - The following example uses the - :scala-api:`updateOne()` - method on the ``inventory`` collection to update the *first* - document where ``item`` equals ``"paper"``: - - - id: csharp - content: | - The following example uses the - :csharp-api:`IMongoCollection.UpdateOne() ` method on the - ``inventory`` collection to update the *first* document where - ``item`` equals ``"paper"``: - - - id: go - content: | - The following example uses the - :go-api:`Collection.UpdateOne` method on the - ``inventory`` collection to update the *first* document where - ``item`` equals ``"paper"``: + .. tab:: + :tabid: shell + + The following example uses the + :method:`db.collection.updateOne()` method on the + ``inventory`` collection to update the *first* document where + ``item`` equals ``"paper"``: + + .. tab:: + :tabid: compass + + The following example demonstrates using |compass| to modify + a single document where ``item: paper`` in the ``inventory`` + collection: + + .. note:: + + This example uses the Compass + :ref:`Table View ` to modify the + document. The editing process using the Compass + :ref:`List View ` follows a very + similar approach. + + For more information on the differences between Table View + and List View in Compass, refer to the + :ref:`Compass documentation `. + + .. tab:: + :tabid: python + + The following example uses the + :py:meth:`~pymongo.collection.Collection.update_one` method on + the ``inventory`` collection to update the *first* document + where ``item`` equals ``"paper"``: + + .. tab:: + :tabid: motor + + The following example uses the + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_one` + method on the ``inventory`` collection to update the *first* + document where ``item`` equals ``"paper"``: + + .. tab:: + :tabid: java-sync + + The following example uses the + com.mongodb.client.MongoCollection.updateOne_ method on the + ``inventory`` collection to update the *first* document where + ``item`` equals ``"paper"``: + + .. tab:: + :tabid: java-async + + The following example uses the + `com.mongodb.reactivestreams.client.MongoCollection.updateOne + `_ + on the ``inventory`` collection to update the *first* document + where ``item`` equals ``"paper"``: + + .. tab:: + :tabid: nodejs + + The following example uses the + :node-api:`Collection.updateOne() ` + method on the ``inventory`` collection to update the *first* + document where ``item`` equals ``"paper"``: + + .. tab:: + :tabid: php + + The following example uses the :phpmethod:`updateOne() + ` method on the + ``inventory`` collection to update the *first* document where + ``item`` equals ``"paper"``: + + .. tab:: + :tabid: perl + + The following example uses the + :perl-api:`update_one()` method on the + ``inventory`` collection to update the *first* document where + ``item`` equals ``"paper"``: + + .. tab:: + :tabid: ruby + + The following example uses the + :ruby-api:`update_one()` + method on the ``inventory`` collection to update the *first* + document where ``item`` equals ``"paper"``: + + .. tab:: + :tabid: scala + + The following example uses the + :scala-api:`updateOne()` + method on the ``inventory`` collection to update the *first* + document where ``item`` equals ``"paper"``: + + .. tab:: + :tabid: csharp + + The following example uses the + :csharp-api:`IMongoCollection.UpdateOne() + ` method on the + ``inventory`` collection to update the *first* document where + ``item`` equals ``"paper"``: + + .. tab:: + :tabid: go + + The following example uses the + :go-api:`Collection.UpdateOne` method + on the ``inventory`` collection to update the *first* document + where ``item`` equals ``"paper"``: .. include:: /includes/driver-examples/driver-example-update-52.rst @@ -585,272 +618,303 @@ Update a Single Document .. tabs-drivers:: - tabs: - - id: shell - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - .. versionadded:: 3.2 - - The following example uses the :method:`db.collection.updateMany()` - method on the ``inventory`` collection to update all documents where - ``qty`` is less than ``50``: - - - id: python - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - .. versionadded:: 3.2 - - The following example uses the - :py:meth:`~pymongo.collection.Collection.update_many` method on - the ``inventory`` collection to update all documents where - ``qty`` is less than ``50``: - - - id: motor - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - .. versionadded:: 3.2 - - The following example uses the - :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_many` - method on the ``inventory`` collection to update all documents - where ``qty`` is less than ``50``: - - - id: java-sync - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - com.mongodb.client.MongoCollection.updateMany_ method on - the ``inventory`` collection to update all documents where - ``qty`` is less than ``50``: - - - id: java-async - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - `com.mongodb.reactivestreams.client.MongoCollection.updateMany - `_ - method on the ``inventory`` collection to update all documents where - ``qty`` is less than ``50``: - - - id: nodejs - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - :node-api:`Collection.updateMany() ` - method on the ``inventory`` collection to update all documents - where ``qty`` is less than ``50``: - - - id: php - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - :phpmethod:`updateMany() ` - method on the ``inventory`` collection to update all documents - where ``qty`` is less than ``50``: - - - id: perl - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - :perl-api:`update_many()` method on - the ``inventory`` collection to update all documents where - ``qty`` is less than ``50``: - - - id: ruby - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - :ruby-api:`update_many()` method on - the ``inventory`` collection to update all documents where - ``qty`` is less than ``50``: - - - id: scala - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - :scala-api:`updateMany()` method on - the ``inventory`` collection to update all documents where - ``qty`` is less than ``50``: - - - id: csharp - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - :csharp-api:`IMongoCollection.UpdateMany() ` - method on the ``inventory`` collection to update all documents - where ``qty`` is less than ``50``: - - - id: go - content: | - Update Multiple Documents - ~~~~~~~~~~~~~~~~~~~~~~~~~ - - The following example uses the - :go-api:`Collection.UpdateMany` - method on the ``inventory`` collection to update all documents - where ``qty`` is less than ``50``: + .. tab:: + :tabid: compass + + .. tab:: + :tabid: shell + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + .. versionadded:: 3.2 + + The following example uses the + :method:`db.collection.updateMany()` method on the ``inventory`` + collection to update all documents where ``qty`` is less than + ``50``: + + .. tab:: + :tabid: python + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + .. versionadded:: 3.2 + + The following example uses the + :py:meth:`~pymongo.collection.Collection.update_many` method on + the ``inventory`` collection to update all documents where ``qty`` + is less than ``50``: + + .. tab:: + :tabid: motor + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + .. versionadded:: 3.2 + + The following example uses the + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_many` + method on the ``inventory`` collection to update all documents + where ``qty`` is less than ``50``: + + .. tab:: + :tabid: java-sync + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the + com.mongodb.client.MongoCollection.updateMany_ method on + the ``inventory`` collection to update all documents where + ``qty`` is less than ``50``: + + .. tab:: + :tabid: java-async + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the + `com.mongodb.reactivestreams.client.MongoCollection.updateMany + `_ + method on the ``inventory`` collection to update all documents + where ``qty`` is less than ``50``: + + .. tab:: + :tabid: nodejs + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the :node-api:`Collection.updateMany() + ` method on the ``inventory`` + collection to update all documents where ``qty`` is less than + ``50``: + + .. tab:: + :tabid: php + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the :phpmethod:`updateMany() + ` method on the + ``inventory`` collection to update all documents where ``qty`` is + less than ``50``: + + .. tab:: + :tabid: perl + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the + :perl-api:`update_many()` method on the + ``inventory`` collection to update all documents where ``qty`` is + less than ``50``: + + .. tab:: + :tabid: ruby + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the + :ruby-api:`update_many()` + method on the ``inventory`` collection to update all documents + where ``qty`` is less than ``50``: + + .. tab:: + :tabid: scala + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the + :scala-api:`updateMany()` + method on the ``inventory`` collection to update all documents + where ``qty`` is less than ``50``: + + .. tab:: + :tabid: csharp + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the + :csharp-api:`IMongoCollection.UpdateMany() + ` method on the + ``inventory`` collection to update all documents where ``qty`` is + less than ``50``: + + .. tab:: + :tabid: go + + Update Multiple Documents + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The following example uses the + :go-api:`Collection.UpdateMany` + method on the ``inventory`` collection to update all documents + where ``qty`` is less than ``50``: .. include:: /includes/driver-examples/driver-example-update-53.rst .. tabs-drivers:: - tabs: - - id: shell - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: compass - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :method:`db.collection.replaceOne()`. + .. tab:: + :tabid: shell - .. include:: /includes/fact-update-replace-example.rst + Replace a Document + ------------------ - - id: python - content: | - Replace a Document - ------------------ + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :method:`db.collection.replaceOne()`. - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :py:meth:`~pymongo.collection.Collection.replace_one`. + .. include:: /includes/fact-update-replace-example.rst - .. include:: /includes/fact-update-replace-example.rst + .. tab:: + :tabid: python - - id: motor - content: | - Replace a Document - ------------------ + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.replace_one`. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :py:meth:`~pymongo.collection.Collection.replace_one`. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: java-sync - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: motor + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - com.mongodb.client.MongoCollection.replaceOne_. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.replace_one`. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: java-async - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: java-sync + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - `com.mongodb.reactivestreams.client.MongoCollection.replaceOne - `_. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + com.mongodb.client.MongoCollection.replaceOne_. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: nodejs - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: java-async + + Replace a Document + ------------------ - To replace the entire content of a document except for the - ``_id`` field, pass an entirely new document as the second - argument to - :node-api:`Collection.replaceOne() `. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + `com.mongodb.reactivestreams.client.MongoCollection.replaceOne + `_. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: php - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: nodejs + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :phpmethod:`replaceOne() `. + To replace the entire content of a document except for the + ``_id`` field, pass an entirely new document as the second + argument to + :node-api:`Collection.replaceOne() `. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: perl - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: php + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :perl-api:`replace_one()`. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :phpmethod:`replaceOne() + `. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: ruby - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: perl + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :ruby-api:`replace_one()`. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :perl-api:`replace_one()`. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: scala - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: ruby + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :scala-api:`replaceOne()` + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :ruby-api:`replace_one()`. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: csharp - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: scala + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :csharp-api:`IMongoCollection.ReplaceOne() - `. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :scala-api:`replaceOne()` - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst - - id: go - content: | - Replace a Document - ------------------ + .. tab:: + :tabid: csharp + + Replace a Document + ------------------ - To replace the entire content of a document except for the ``_id`` - field, pass an entirely new document as the second argument to - :go-api:`Collection.ReplaceOne `. + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :csharp-api:`IMongoCollection.ReplaceOne() + `. - .. include:: /includes/fact-update-replace-example.rst + .. include:: /includes/fact-update-replace-example.rst + + .. tab:: + :tabid: go + + Replace a Document + ------------------ + + To replace the entire content of a document except for the ``_id`` + field, pass an entirely new document as the second argument to + :go-api:`Collection.ReplaceOne `. + + .. include:: /includes/fact-update-replace-example.rst .. include:: /includes/driver-examples/driver-example-update-54.rst @@ -880,198 +944,227 @@ Field Order .. tabs-drivers:: - tabs: - - id: shell - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :method:`~db.collection.updateOne()`, - :method:`~db.collection.updateMany()`, or - :method:`~db.collection.replaceOne()` includes ``upsert : true`` **and** - no documents match the specified filter, then the operation creates a - new document and inserts it. If there are matching documents, then the - operation modifies or replaces the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: python - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :py:meth:`~pymongo.collection.Collection.update_one`, - :py:meth:`~pymongo.collection.Collection.update_many`, or - :py:meth:`~pymongo.collection.Collection.replace_one` includes - ``upsert : true`` **and** no documents match the specified - filter, then the operation creates a new document and inserts - it. If there are matching documents, then the operation - modifies or replaces the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: motor - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_one`, - :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_many`, or - :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.replace_one` includes - ``upsert : true`` **and** no documents match the specified - filter, then the operation creates a new document and inserts - it. If there are matching documents, then the operation - modifies or replaces the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: java-sync - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If the update and replace methods include the - com.mongodb.client.model.UpdateOptions_ parameter that - specifies `com.mongodb.client.model.UpdateOptions.upsert(true)`_ - **and** no documents match the specified filter, then the - operation creates a new document and inserts it. If there are - matching documents, then the operation modifies or replaces - the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: java-async - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If the update and replace methods include the - `UpdateOptions `_ - parameter that specifies `UpdateOptions.upsert(true) `_ - **and** no documents match the specified filter, then the - operation creates a new document and inserts it. If there are - matching documents, then the operation modifies or replaces - the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: nodejs - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :node-api:`updateOne() `, - :node-api:`updateMany() `, or - :node-api:`replaceOne() ` include - ``upsert : true`` in the ``options`` parameter document **and** - no documents match the specified filter, then the operation - creates a new document and inserts it. If there are matching - documents, then the operation modifies or replaces the matching - document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: php - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :phpmethod:`updateOne() `, - :phpmethod:`updateMany() `, - or :phpmethod:`replaceOne() ` - includes ``upsert => true`` **and** no documents match the - specified filter, then the operation creates a new document and - inserts it. If there are matching documents, then the operation - modifies or replaces the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: perl - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :perl-api:`update_one()`, - :perl-api:`update_many()`, or - :perl-api:`replace_one()` includes - ``upsert => true`` **and** no documents match the specified - filter, then the operation creates a new document and inserts - it. If there are matching documents, then the operation - modifies or replaces the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: ruby - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :ruby-api:`update_one()`, - :ruby-api:`update_many()`, or - :ruby-api:`replace_one()` includes - ``upsert => true`` **and** no documents match the specified - filter, then the operation creates a new document and inserts - it. If there are matching documents, then the operation - modifies or replaces the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: scala - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :scala-api:`updateOne()`, :scala-api:`updateMany()`, or :scala-api:`replaceOne()` - includes ``upsert => true`` **and** no documents match the specified - filter, then the operation creates a new document and inserts it. If - there are matching documents, then the operation modifies or replaces - the matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: csharp - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :csharp-api:`UpdateOne() `, - :csharp-api:`UpdateMany() `, or - :csharp-api:`ReplaceOne() ` - includes an :csharp-api:`UpdateOptions ` - argument instance with the ``IsUpsert`` option set to ``true`` - **and** no documents match the specified filter, then the - operation creates a new document and inserts it. If there are - matching documents, then the operation modifies or replaces the - matching document or documents. - - For details on the new document created, see the individual reference - pages for the methods. - - - id: go - content: | - Upsert Option - ~~~~~~~~~~~~~ - - If :go-api:`Collection.UpdateOne` - includes the :go-api:`Upsert option set to true - ` **and** no documents match the - specified filter, then the operation creates a new document - and inserts it. If there are matching documents, then the - operation modifies or replaces the matching document or - documents. - - For details on the new document created, see the individual reference - pages for the methods. + .. tab:: + :tabid: compass + + .. tab:: + :tabid: shell + + Upsert Option + ~~~~~~~~~~~~~ + + If :method:`~db.collection.updateOne()`, + :method:`~db.collection.updateMany()`, or + :method:`~db.collection.replaceOne()` includes ``upsert : true`` + **and** no documents match the specified filter, then the + operation creates a new document and inserts it. If there are + matching documents, then the operation modifies or replaces the + matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: python + + Upsert Option + ~~~~~~~~~~~~~ + + If :py:meth:`~pymongo.collection.Collection.update_one`, + :py:meth:`~pymongo.collection.Collection.update_many`, or + :py:meth:`~pymongo.collection.Collection.replace_one` includes + ``upsert : true`` **and** no documents match the specified + filter, then the operation creates a new document and inserts + it. If there are matching documents, then the operation + modifies or replaces the matching document or documents. + + For details on the new document created, see the individual reference + pages for the methods. + + .. tab:: + :tabid: motor + + Upsert Option + ~~~~~~~~~~~~~ + + If + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_one`, + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_many`, + or + :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.replace_one` + includes ``upsert : true`` **and** no documents match the + specified filter, then the operation creates a new document and + inserts it. If there are matching documents, then the operation + modifies or replaces the matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: java-sync + + Upsert Option + ~~~~~~~~~~~~~ + + If the update and replace methods include the + com.mongodb.client.model.UpdateOptions_ parameter that + specifies `com.mongodb.client.model.UpdateOptions.upsert(true)`_ + **and** no documents match the specified filter, then the + operation creates a new document and inserts it. If there are + matching documents, then the operation modifies or replaces + the matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: java-async + + Upsert Option + ~~~~~~~~~~~~~ + + If the update and replace methods include the `UpdateOptions + `_ + parameter that specifies `UpdateOptions.upsert(true) + `_ + **and** no documents match the specified filter, then the + operation creates a new document and inserts it. If there are + matching documents, then the operation modifies or replaces the + matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: nodejs + + Upsert Option + ~~~~~~~~~~~~~ + + If :node-api:`updateOne() `, + :node-api:`updateMany() `, or + :node-api:`replaceOne() ` include + ``upsert : true`` in the ``options`` parameter document **and** + no documents match the specified filter, then the operation + creates a new document and inserts it. If there are matching + documents, then the operation modifies or replaces the matching + document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: php + + Upsert Option + ~~~~~~~~~~~~~ + + If :phpmethod:`updateOne() + `, + :phpmethod:`updateMany() + `, or + :phpmethod:`replaceOne() + ` includes ``upsert => + true`` **and** no documents match the specified filter, then the + operation creates a new document and inserts it. If there are + matching documents, then the operation modifies or replaces the + matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: perl + + Upsert Option + ~~~~~~~~~~~~~ + + If :perl-api:`update_one()`, + :perl-api:`update_many()`, or + :perl-api:`replace_one()` includes + ``upsert => true`` **and** no documents match the specified + filter, then the operation creates a new document and inserts + it. If there are matching documents, then the operation + modifies or replaces the matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: ruby + + Upsert Option + ~~~~~~~~~~~~~ + + If + :ruby-api:`update_one()`, + :ruby-api:`update_many()`, + or + :ruby-api:`replace_one()` + includes ``upsert => true`` **and** no documents match the + specified filter, then the operation creates a new document and + inserts it. If there are matching documents, then the operation + modifies or replaces the matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: scala + + Upsert Option + ~~~~~~~~~~~~~ + + If + :scala-api:`updateOne()`, + :scala-api:`updateMany()`, + or + :scala-api:`replaceOne()` + includes ``upsert => true`` **and** no documents match the + specified filter, then the operation creates a new document and + inserts it. If there are matching documents, then the operation + modifies or replaces the matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: csharp + + Upsert Option + ~~~~~~~~~~~~~ + + If :csharp-api:`UpdateOne() + `, + :csharp-api:`UpdateMany() + `, or + :csharp-api:`ReplaceOne() + ` includes an + :csharp-api:`UpdateOptions ` + argument instance with the ``IsUpsert`` option set to ``true`` + **and** no documents match the specified filter, then the + operation creates a new document and inserts it. If there are + matching documents, then the operation modifies or replaces the + matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. + + .. tab:: + :tabid: go + + Upsert Option + ~~~~~~~~~~~~~ + + If :go-api:`Collection.UpdateOne` + includes the :go-api:`Upsert option set to true + ` **and** no documents match the + specified filter, then the operation creates a new document and + inserts it. If there are matching documents, then the operation + modifies or replaces the matching document or documents. + + For details on the new document created, see the individual + reference pages for the methods. Write Acknowledgement ~~~~~~~~~~~~~~~~~~~~~ @@ -1082,164 +1175,173 @@ requested from MongoDB for write operations. For details, see .. tabs-drivers:: - tabs: - - id: shell - content: | + .. tab:: + :tabid: shell - .. seealso:: + .. seealso:: - - :doc:`/tutorial/update-documents-with-aggregation-pipeline` + - :doc:`/tutorial/update-documents-with-aggregation-pipeline` - - :method:`db.collection.updateOne()` + - :method:`db.collection.updateOne()` + + - :method:`db.collection.updateMany()` + + - :method:`db.collection.replaceOne()` - - :method:`db.collection.updateMany()` + - :ref:`additional-updates` - - :method:`db.collection.replaceOne()` + .. tab:: + :tabid: compass - - :ref:`additional-updates` + .. seealso:: - - id: compass - content: | - .. seealso:: + - `Compass Documents `_ - - `Compass Documents `_ + - :ref:`Compass Query Bar ` - - :ref:`Compass Query Bar ` + .. tab:: + :tabid: python - - id: python - content: | - .. seealso:: + .. seealso:: - - :py:meth:`pymongo.collection.Collection.update_one` + - :py:meth:`pymongo.collection.Collection.update_one` - - :py:meth:`pymongo.collection.Collection.update_many` + - :py:meth:`pymongo.collection.Collection.update_many` - - :py:meth:`pymongo.collection.Collection.replace_one` + - :py:meth:`pymongo.collection.Collection.replace_one` - - :ref:`additional-updates` + - :ref:`additional-updates` - - id: motor - content: | - .. seealso:: + .. tab:: + :tabid: motor - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_one` + .. seealso:: - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_many` + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_one` - - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.replace_one` + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_many` - - :ref:`additional-updates` + - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.replace_one` - - id: java-sync - content: | + - :ref:`additional-updates` - .. seealso:: + .. tab:: + :tabid: java-sync + + .. seealso:: + + - com.mongodb.client.MongoCollection.updateOne_ + + - com.mongodb.client.MongoCollection.updateMany_ - - com.mongodb.client.MongoCollection.updateOne_ + - com.mongodb.client.MongoCollection.replaceOne_ + + - `Additional Java Synchronous Driver Write Examples`_ + + .. tab:: + :tabid: java-async + + .. seealso:: + + - `com.mongodb.reactivestreams.client.MongoCollection.updateOne + `_ + + - `com.mongodb.reactivestreams.client.MongoCollection.updateMany + `_ - - com.mongodb.client.MongoCollection.updateMany_ + - `com.mongodb.reactivestreams.client.MongoCollection.replaceOne + `_ - - com.mongodb.client.MongoCollection.replaceOne_ + - `Java Reactive Streams Driver Quick Tour `_ - - `Additional Java Synchronous Driver Write Examples`_ + .. tab:: + :tabid: nodejs - - id: java-async - content: | + .. seealso:: - .. seealso:: + - :node-api:`Collection.updateOne() ` - - `com.mongodb.reactivestreams.client.MongoCollection.updateOne - `_ + - :node-api:`Collection.updateMany() ` - - `com.mongodb.reactivestreams.client.MongoCollection.updateMany - `_ + - :node-api:`Collection.replaceOne() ` - - `com.mongodb.reactivestreams.client.MongoCollection.replaceOne - `_ + - :ref:`additional-updates` - - `Java Reactive Streams Driver Quick Tour `_ + .. tab:: + :tabid: php - - id: nodejs - content: | - .. seealso:: + .. seealso:: - - :node-api:`Collection.updateOne() ` + - :phpmethod:`MongoDB\\Collection::updateOne() ` - - :node-api:`Collection.updateMany() ` + - :phpmethod:`MongoDB\\Collection::updateMany() ` - - :node-api:`Collection.replaceOne() ` + - :phpmethod:`MongoDB\\Collection::replaceOne() ` - - :ref:`additional-updates` + - :ref:`additional-updates` - - id: php - content: | - .. seealso:: + .. tab:: + :tabid: perl - - :phpmethod:`MongoDB\\Collection::updateOne() ` + .. seealso:: - - :phpmethod:`MongoDB\\Collection::updateMany() ` + - :perl-api:`MongoDB::Collection::update_one()` - - :phpmethod:`MongoDB\\Collection::replaceOne() ` + - :perl-api:`MongoDB::Collection::update_many()` - - :ref:`additional-updates` + - :perl-api:`MongoDB::Collection::replace_one()` - - id: perl - content: | - .. seealso:: + - :ref:`additional-updates` - - :perl-api:`MongoDB::Collection::update_one()` + .. tab:: + :tabid: ruby - - :perl-api:`MongoDB::Collection::update_many()` + .. seealso:: - - :perl-api:`MongoDB::Collection::replace_one()` + - :ruby-api:`Mongo::Collection#update_one()` - - :ref:`additional-updates` + - :ruby-api:`Mongo::Collection#update_many()` - - id: ruby - content: | - .. seealso:: + - :ruby-api:`Mongo::Collection#replace_one()` - - :ruby-api:`Mongo::Collection#update_one()` + .. tab:: + :tabid: scala - - :ruby-api:`Mongo::Collection#update_many()` + .. seealso:: - - :ruby-api:`Mongo::Collection#replace_one()` + - :scala-api:`collection.updateOne()` - - id: scala - content: | - .. seealso:: + - :scala-api:`collection.updateMany()` - - :scala-api:`collection.updateOne()` + - :scala-api:`collection.replaceOne()` - - :scala-api:`collection.updateMany()` + - :ref:`additional-updates` - - :scala-api:`collection.replaceOne()` + .. tab:: + :tabid: csharp - - :ref:`additional-updates` + .. seealso:: - - id: csharp - content: | - .. seealso:: + - :csharp-api:`IMongoCollection.UpdateOne() ` - - :csharp-api:`IMongoCollection.UpdateOne() ` + - :csharp-api:`IMongoCollection.UpdateMany() ` - - :csharp-api:`IMongoCollection.UpdateMany() ` + - :csharp-api:`IMongoCollection.ReplaceOne() ` - - :csharp-api:`IMongoCollection.ReplaceOne() ` + - :ref:`additional-updates` - - :ref:`additional-updates` + .. tab:: + :tabid: go - - id: go - content: | - .. seealso:: + .. seealso:: - - :go-api:`Collection.UpdateOne` + - :go-api:`Collection.UpdateOne` - - :go-api:`Collection.UpdateMany` + - :go-api:`Collection.UpdateMany` - - :go-api:`Collection.ReplaceOne ` + - :go-api:`Collection.ReplaceOne ` - - :ref:`additional-updates` + - :ref:`additional-updates` .. toctree:: :titlesonly: From 0b8476fab888b476b2db79b663efb3aaaba5cecb Mon Sep 17 00:00:00 2001 From: Dave Cuthbert Date: Fri, 1 Oct 2021 16:07:54 -0400 Subject: [PATCH 077/109] DOCSP-18892 improved examples for getField --- .../operator/aggregation/getField.txt | 80 ++++++++++++++++++- 1 file changed, 76 insertions(+), 4 deletions(-) diff --git a/source/reference/operator/aggregation/getField.txt b/source/reference/operator/aggregation/getField.txt index 1268f5b7871..b389bc8b51c 100644 --- a/source/reference/operator/aggregation/getField.txt +++ b/source/reference/operator/aggregation/getField.txt @@ -133,14 +133,14 @@ greater than ``200``: .. code-block:: javascript - db.inventory.aggregate([ + db.inventory.aggregate( [ { $match: { $expr: { $gt: [ { $getField: "price.usd" }, 200 ] } } } - ]) + ] ) The operation returns the following results: @@ -171,14 +171,14 @@ products have a ``$price`` greater than ``200``: .. code-block:: javascript - db.inventory.aggregate([ + db.inventory.aggregate( [ { $match: { $expr: { $gt: [ { $getField: {$literal: "$price" } }, 200 ] } } } - ]) + ] ) The operation returns the following results: @@ -190,3 +190,75 @@ The operation returns the following results: { _id: 4, item: 'leather boots', qty: 300, '$price': 249.99 } ] +Query a Field in a Sub-document +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create an ``inventory`` collection with the following documents: + +.. code-block:: javascript + + db.inventory.insertMany( [ + { "_id" : 1, "item" : "sweatshirt", "price.usd": 45.99, + "quantity": { "$large": 50, "$medium": 50, "$small": 25 } + }, + { "_id" : 2, "item" : "winter coat", "price.usd": 499.99, + "quantity": { "$large": 35, "$medium": 35, "$small": 35 } + }, + { "_id" : 3, "item" : "sun dress", "price.usd": 199.99, + "quantity": { "$large": 45, "$medium": 40, "$small": 5 } + }, + { "_id" : 4, "item" : "leather boots", "price.usd": 249.99, + "quantity": { "$large": 20, "$medium": 30, "$small": 40 } + }, + { "_id" : 5, "item" : "bow tie", "price.usd": 9.99, + "quantity": { "$large": 0, "$medium": 10, "$small": 75 } + } + ] ) + +The following operation returns documents where the number of +``$small`` items is less than or equal to ``20``. + +.. code-block:: javascript + :emphasize-lines: 6-8 + + db.inventory.aggregate( [ + { $match: + { $expr: + { $lte: + [ + { $getField: + { field: { $literal: "$small" }, + input: "$quantity" + } + }, + 20 + ] + } + } + } + ] ) + +Use these operators to query the collection: + +- The :expression:`$lte` operator finds values less than or equal to + 20. +- :expression:`$getField` requires explicit ``field`` and ``input`` + parameters because the ``$small`` field is part of a + sub-document. +- :expression:`$getField` uses :expression:`$literal` to evaluate + "``$small``", because the field name has a dollar sign (``$``) in it. + +Example output: + +.. code-block:: javascript + :copyable: false + + [ + { + _id: 3, + item: 'sun dress', + 'price.usd': 199.99, + quantity: { '$large': 45, '$medium': 40, '$small': 5 } + } + ] + From 2e8e9d59f09eb356a6f41f28b2315cd82e3d0673 Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Wed, 6 Oct 2021 18:00:02 -0400 Subject: [PATCH 078/109] (DOCS-12321): Document new TLS version logging configuration option --- source/reference/configuration-options.txt | 31 +++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/source/reference/configuration-options.txt b/source/reference/configuration-options.txt index 2b30159c712..e5a6d544487 100644 --- a/source/reference/configuration-options.txt +++ b/source/reference/configuration-options.txt @@ -868,6 +868,7 @@ Core Options allowInvalidHostnames: disabledProtocols: FIPSMode: + logVersions: compression: compressors: @@ -909,12 +910,16 @@ Core Options may attach :binary:`~bin.mongos` or :binary:`~bin.mongod` to any interface. To bind to multiple addresses, enter a list of comma-separated values. - .. example:: ``localhost,/tmp/mongod.sock`` + .. example:: + + ``localhost,/tmp/mongod.sock`` You can specify both IPv4 and IPv6 addresses, or hostnames that resolve to an IPv4 or IPv6 address. - .. example:: ``localhost, 2001:0DB8:e132:ba26:0d5c:2774:e7f9:d513`` + .. example:: + + ``localhost, 2001:0DB8:e132:ba26:0d5c:2774:e7f9:d513`` .. note:: @@ -929,7 +934,9 @@ Core Options `zone index `_ to that address (i.e. ``fe80::
%``). - .. example:: ``localhost,fe80::a00:27ff:fee0:1fcf%enp0s3`` + .. example:: + + ``localhost,fe80::a00:27ff:fee0:1fcf%enp0s3`` .. include:: /includes/tip-hostnames.rst @@ -1150,6 +1157,7 @@ Core Options allowInvalidHostnames: disabledProtocols: FIPSMode: + logVersions: .. setting:: net.tls.mode @@ -1611,6 +1619,23 @@ Core Options .. include:: /includes/note-fips-is-enterprise-only.rst +.. setting:: net.tls.logVersions + + *Type*: string + + Instructs :binary:`~bin.mongos` or :binary:`~bin.mongod` to log a + message when a client connects using a specified TLS version. + + Specify either a single TLS version or a comma-separated list of + multiple TLS versions. + + .. example:: + + To instruct :binary:`~bin.mongos` or :binary:`~bin.mongod` to + log a message when a client connects using either TLS 1.2 or + TLS 1.3, set :setting:`net.tls.logVersions` to + ``"TLS1_2,TLS1_3"``. + .. _net-ssl-conf-options: From fc9f7442533e713d64dafa167e746a94b51c0f0c Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Fri, 8 Oct 2021 15:31:55 -0400 Subject: [PATCH 079/109] (DOCS-14856): v4.4.10 initial changelog --- config/changelog_conf.yaml | 1 + .../includes/changelogs/releases/4.4.10.rst | 172 ++++++++++++++++++ source/release-notes/4.4-changelog.txt | 2 + source/release-notes/4.4.txt | 22 +++ 4 files changed, 197 insertions(+) create mode 100644 source/includes/changelogs/releases/4.4.10.rst diff --git a/config/changelog_conf.yaml b/config/changelog_conf.yaml index af87f7e7c15..3af2baba4f8 100644 --- a/config/changelog_conf.yaml +++ b/config/changelog_conf.yaml @@ -66,6 +66,7 @@ groups: - Cache and eviction - Backup - Checkpoints + - Documentation "Tools": - Tools - All Tools diff --git a/source/includes/changelogs/releases/4.4.10.rst b/source/includes/changelogs/releases/4.4.10.rst new file mode 100644 index 00000000000..7529649d489 --- /dev/null +++ b/source/includes/changelogs/releases/4.4.10.rst @@ -0,0 +1,172 @@ +.. _4.4.10-changelog: + +4.4.10 Changelog +---------------- + +Security +~~~~~~~~ + +:issue:`SERVER-50050` Build with --ssl=off fails + +Sharding +~~~~~~~~ + +- :issue:`SERVER-53332` Change ShardRegistry::_connStringLookup to store connection strings as std::strings +- :issue:`SERVER-54064` Sessions on arbiters accumulate and cannot be cleared out +- :issue:`SERVER-55975` The core/find_and_modify.js test is not suitable to run in the stepdown suites +- :issue:`SERVER-59160` Disable balancer in test_stacked_migration_cleanup.js +- :issue:`SERVER-59769` Balancer conflicts with chunk migration tests +- :issue:`SERVER-59916` T{1, 2}Starts{First, Second}AndWins In WriteConflictHelpers Does Not Synchronize Committing Of Failed Transaction +- :issue:`SERVER-60142` Shard can migrate on top of orphans after filtering metadata was cleared +- :issue:`SERVER-60419` Make CleanUpForMigrateIn deterministic + +Replication +~~~~~~~~~~~ + +- :issue:`SERVER-50241` PeriodicShardedIndexConsistencyChecker should skip dropped collections +- :issue:`SERVER-55376` Reconfig can roll back committed writes in PSA sets +- :issue:`SERVER-58988` Avoid sync source selection cycle during primary catchup. +- :issue:`SERVER-60153` More INFO level logs during election + +Query +~~~~~ + +- :issue:`SERVER-51806` bulk key insertion phase of index build holds IX lock without yielding +- :issue:`SERVER-54791` Excessive file descriptor usage during index build with external sort +- :issue:`SERVER-57321` $mod match expression incorrectly handles NaN, Infinity and large values + +Aggregation +~~~~~~~~~~~ + +:issue:`SERVER-49214` Add $toHashedIndexKey expression + +Operations +~~~~~~~~~~ + +:issue:`SERVER-53242` Always log collmod command + +Internals +~~~~~~~~~ + +- :issue:`SERVER-34597` shardedcluster.py does not wait correctly on shards initialization +- :issue:`SERVER-46147` Update repair to fix multikey errors without performing an index rebuild +- :issue:`SERVER-49340` Add repair mode to validate for startup --repair +- :issue:`SERVER-52850` Remove assertion from initial_sync_nodes_maintain_and_gossip_commit_point.js +- :issue:`SERVER-53448` Make ftdc_mirrored_reads.js resilient to slow machines +- :issue:`SERVER-54825` Use 'toArray()' in addition to array access after 'find()' in rslib.js +- :issue:`SERVER-55904` Consolidate getFirstOplogEntry and getLeastRecentOp helpers +- :issue:`SERVER-56326` Add a round() method to the Decimal128 class +- :issue:`SERVER-56416` mongod --version returns with extraneous log line on M1 laptops +- :issue:`SERVER-56919` Add validation for memberIndex to reconfigToPSASet() shell helper +- :issue:`SERVER-57284` Wait for config commitment in reconfig_for_psa_set_shell.js +- :issue:`SERVER-57605` Expose Decimal128 equality comparison helper to shell +- :issue:`SERVER-57938` Skip polygon validation for stored GeoJSON when query has $geoIntersect and a 2dsphere index +- :issue:`SERVER-58047` $toHashedIndexKey expression doesn't add any dependencies +- :issue:`SERVER-58104` config.system.sessions collection can end up with invalid chunks if it is dropped and re-sharded with a shard key other than _id +- :issue:`SERVER-58122` Replace searching logs for invariant failure with failpoint usage in resync_majority_member.js +- :issue:`SERVER-58139` Avoid leaking state from NetworkInterfaceTest::CancelLocally +- :issue:`SERVER-58148` mirrored_reads.js assertion does not consider mirrored read failure +- :issue:`SERVER-58183` _applyPrepareTransaction does not ensure prepareConflictBehavior is kIgnoreConflictAcceptWrites on retry attempts +- :issue:`SERVER-58203` improve $unionWith stage +- :issue:`SERVER-58583` Query analysis for mongocryptd does not handle expressive projections in find +- :issue:`SERVER-58777` Inserts and updates disagree on whether an empty subdocument is a level of nesting +- :issue:`SERVER-58780` [v4.4] Ensure that _shouldSetStableTimestamp gets restored to true if replSetInitiate fails +- :issue:`SERVER-59010` Fix SSL off build, OCSPManager shouldn't be used when ssl = off +- :issue:`SERVER-59074` Do not acquire storage tickets just to set/wait on oplog visibility +- :issue:`SERVER-59120` Create unit tests for commitChunksMerge +- :issue:`SERVER-59143` hard fail if "--ninja" tool option is used with ninja module in place +- :issue:`SERVER-59190` IndexAccessMethod can be destructed during index build bulk load yield +- :issue:`SERVER-59294` Check action type for oidReset +- :issue:`SERVER-59299` Improve $match stage +- :issue:`SERVER-59425` Ninja fails to install archive targets locally +- :issue:`SERVER-59456` Start the LDAPReaper threadpool +- :issue:`SERVER-59476` validate_commit_message does not allow wiredtiger imports to be reverted +- :issue:`SERVER-59651` replsettest runCommandWithRetry should handle slow configs +- :issue:`SERVER-59725` Remove push task from extra RHEL 6.2 variants +- :issue:`SERVER-59804` Using a separate branch for YCSB in system_perf.yml +- :issue:`SERVER-59866` Stop FCV from waiting for majority when currentCommittedSnapshot is dropped +- :issue:`SERVER-59867` Split horizon mappings in ReplSetConfig/MemberConfig should be serialized deterministically +- :issue:`SERVER-59876` Large delays in returning from libcrypto.so while establishing egress connections +- :issue:`SERVER-60025` queue document crashes the server due to producing invalid runtime object +- :issue:`SERVER-60062` Fix duplicate uuid and server description deep copy found in topology description clone +- :issue:`SERVER-60085` Cap number of fallback test suites at number of tests in suite +- :issue:`SERVER-60290` Update Windows external auth test distro +- :issue:`SERVER-60299` Backport PCRE bugfix for Bugzilla #2613 +- :issue:`SERVER-60406` $searchMeta fails on unsharded collection in sharded cluster when there are no search results +- :issue:`WT-5270` Create wtperf script for evergreen +- :issue:`WT-6193` Re-enable VLCS testing in format-test +- :issue:`WT-6669` Enable VLCS coverage and checkpoint tests in evergreen +- :issue:`WT-6900` Write "schema" subpage for Architecture Guide +- :issue:`WT-6903` Write "dhandle/btree" subpage for Architecture Guide +- :issue:`WT-6907` Write "snapshots" subpage for Architecture Guide +- :issue:`WT-6909` Eviction architecture guide +- :issue:`WT-6913` file system and os interface architecture guide +- :issue:`WT-7169` Commit ts should not be lesser than the last durable ts in test_timestamp22.py +- :issue:`WT-7294` Re-enable VLCS evergreen endianness tests +- :issue:`WT-7392` Added evicted flag to dhandle for use by session sweep +- :issue:`WT-7601` Fix typo in operation tracking documentation +- :issue:`WT-7695` Dump entire tree when key out-of-order found in __cursor_key_order_check_row +- :issue:`WT-7745` Add macro to identify uris for btree objects +- :issue:`WT-7757` Skip obsolete leaf pages without having to read them +- :issue:`WT-7844` Add tiered_abort stress test for tiered storage. +- :issue:`WT-7902` Retry the alter command after a system wide checkpoint +- :issue:`WT-7914` Update the documentation only when required +- :issue:`WT-7942` Release timestamp lock in test/format when all_durable timestamp is not found +- :issue:`WT-7949` Change local store cache and bucket directories to be relative to WT_HOME +- :issue:`WT-7957` Tiered storage should look in local system for objects +- :issue:`WT-7959` Skipped_pages is less than expected_pages_skipped in test_cursor17 +- :issue:`WT-7980` Create interface to "log:" cursor which switches log files before returning them +- :issue:`WT-7987` Create Unit Test to check compact does not rewrite overflow items +- :issue:`WT-7989` Compact quits when running at the same time as a system checkpoint +- :issue:`WT-7992` Provide API to return the last key in a table regardless of visibility +- :issue:`WT-7993` If gathering handles and not in aggressive eviction mode, have eviction sleep to let checkpoint grab a contentious spinlock. +- :issue:`WT-8001` Fix Inconsistent API behaviour when setting global oldest and stable timestamps +- :issue:`WT-8007` Update script to correctly generate new test for the CPP test suite framework +- :issue:`WT-8011` Add format support for randomly choosing RS or VLCS +- :issue:`WT-8017` Re-enable VLCS format stress testing in evergreen. +- :issue:`WT-8019` VLCS snapshot-isolation search mismatch +- :issue:`WT-8022` Verify WT_CURSOR.modify return values in format test program +- :issue:`WT-8023` Use global transaction information to assess if a session has active transaction +- :issue:`WT-8024` Add link text to cross-references in Arch Guide +- :issue:`WT-8034` Use the PR branch when docs are compiled in PR testing +- :issue:`WT-8035` Handle prefix enabled lexicographical comparisons for string key formats +- :issue:`WT-8036` Added connection panic flag in two assert statements in wt_evict_thread_run and _wt_evict_thread_stop. +- :issue:`WT-8039` Add a new flag for API check instead of clearing prepared flag which may incorrectly force a roll back +- :issue:`WT-8041` Rollback to stable unpacks values repeatedly +- :issue:`WT-8042` Create an evergreen job to run test/checkpoint variation +- :issue:`WT-8043` Tidy the "ripcip" argument into the visibility code +- :issue:`WT-8044` Prefix enabled search near only returns matching keys +- :issue:`WT-8048` Remove split_8 timing stress configuration +- :issue:`WT-8055` Fix issue when compact quits when running at the same time as a checkpoint +- :issue:`WT-8057` Add a test to verify that changing compact is not resulting in data loss +- :issue:`WT-8059` Add a check in salvage when no overflow items are found +- :issue:`WT-8068` Improve __rollback_row_modify control flow +- :issue:`WT-8069` Coverity analysis defect 120706: Redundant test +- :issue:`WT-8070` Remove discrepancy between prefix_key and prefix_search +- :issue:`WT-8075` Coverity analysis defect 120712: 'Constant' variable guards dead code +- :issue:`WT-8077` Mark the page dirty once the prepared updates are resolved +- :issue:`WT-8078` Implement tiered storage local retention caching +- :issue:`WT-8079` Add breakpoint to verify error macros, clean up API processing +- :issue:`WT-8081` Fix tiered hook functions to provide default for config string +- :issue:`WT-8086` Create cpp test for prefix search near entries +- :issue:`WT-8092` Prefix early exit when keys are present in the insert list +- :issue:`WT-8094` Fix use after free in csv extractor +- :issue:`WT-8101` Enable diagnostic mode for the CPP tests in evergreen +- :issue:`WT-8103` Skip a dhandle if it isn't a btree +- :issue:`WT-8104` Fix memory leaks noted by ASAN +- :issue:`WT-8108` Use temporary files and rename in local store +- :issue:`WT-8112` Skip null check, per coverity +- :issue:`WT-8113` Remove dead code, per coverity +- :issue:`WT-8115` Define macros only when necessary in cpp files +- :issue:`WT-8119` Add targeted compact testing to the existing testing framework +- :issue:`WT-8121` Create a long running stress test which inserts a large amount of data over a long period +- :issue:`WT-8125` Update hs_cleanup cppsuite test to use the new thread_context logic +- :issue:`WT-8126` Mark btree as dirty only if not newly created when instantiating a deleted row-store leaf page +- :issue:`WT-8146` Stop the tracking component when a CPP test ends +- :issue:`WT-8148` Fix comment typo in util_verify.c +- :issue:`WT-8161` Reduce verbosity of CMake Evergreen smoke +- :issue:`WT-8162` Refactor uses of SMOKE arg in 'define_c_test' helper +- :issue:`WT-8164` Disable rollback_to_stable10 python test on Windows +- :issue:`WT-8171` Implement a C style test in the CPP testing framework +- :issue:`WT-8193` Wrong corner case in VLCS rollback-to-stable + diff --git a/source/release-notes/4.4-changelog.txt b/source/release-notes/4.4-changelog.txt index 4e09bd2aeb8..45a06fa1c86 100644 --- a/source/release-notes/4.4-changelog.txt +++ b/source/release-notes/4.4-changelog.txt @@ -10,6 +10,8 @@ :depth: 1 :class: singlecol +.. include:: /includes/changelogs/releases/4.4.10.rst + .. include:: /includes/changelogs/releases/4.4.9.rst .. include:: /includes/changelogs/releases/4.4.8.rst diff --git a/source/release-notes/4.4.txt b/source/release-notes/4.4.txt index f5687cf4685..bdd2c613680 100644 --- a/source/release-notes/4.4.txt +++ b/source/release-notes/4.4.txt @@ -13,6 +13,28 @@ Release Notes for MongoDB 4.4 Minor Releases -------------- +.. _4.4.10-release-notes: + +4.4.10 - Oct 8, 2021 +~~~~~~~~~~~~~~~~~~~~ + +Issues fixed: + +- :issue:`SERVER-59876`: Large delays in returning from libcrypto.so + while establishing egress connections +- :issue:`SERVER-59867`: Split horizon mappings in + ReplSetConfig/MemberConfig should be serialized deterministically +- :issue:`SERVER-59456`: Start the LDAPReaper threadpool +- :issue:`SERVER-59074`: Do not acquire storage tickets just to + set/wait on oplog visibility +- :issue:`SERVER-54064`: Sessions on arbiters accumulate and cannot be + cleared out + +- `All JIRA issues closed in 4.4.10 + `_ + +- :ref:`4.4.10-changelog` + .. _4.4.9-release-notes: 4.4.9 - Sep 21, 2021 From 42346125cc423396fa4408d721b3e677bc3e12bc Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Fri, 8 Oct 2021 16:30:16 -0400 Subject: [PATCH 080/109] (DOCS-14856): Replace date with 'upcoming' for 4.4.10 notes --- source/release-notes/4.4.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/release-notes/4.4.txt b/source/release-notes/4.4.txt index bdd2c613680..31b3d1be40d 100644 --- a/source/release-notes/4.4.txt +++ b/source/release-notes/4.4.txt @@ -15,8 +15,8 @@ Minor Releases .. _4.4.10-release-notes: -4.4.10 - Oct 8, 2021 -~~~~~~~~~~~~~~~~~~~~ +4.4.10 - Upcoming +~~~~~~~~~~~~~~~~~ Issues fixed: From 981c750e38055d5db0b85fa37973397c8e65011a Mon Sep 17 00:00:00 2001 From: jason-price-mongodb Date: Mon, 4 Oct 2021 10:16:50 -0700 Subject: [PATCH 081/109] DOCS-13868 chunk errors in sharded transactions --- .../transactionLifetimeLimitSeconds-parameter.rst | 10 ++++++++++ source/reference/parameters.txt | 8 +++++--- source/release-notes/5.0-compatibility.txt | 5 +++++ 3 files changed, 20 insertions(+), 3 deletions(-) create mode 100644 source/includes/transactionLifetimeLimitSeconds-parameter.rst diff --git a/source/includes/transactionLifetimeLimitSeconds-parameter.rst b/source/includes/transactionLifetimeLimitSeconds-parameter.rst new file mode 100644 index 00000000000..f4ab8602719 --- /dev/null +++ b/source/includes/transactionLifetimeLimitSeconds-parameter.rst @@ -0,0 +1,10 @@ +Starting in MongoDB 5.0, if you change the +:parameter:`transactionLifetimeLimitSeconds` parameter, you must also +change :parameter:`transactionLifetimeLimitSeconds` to the same value on +all config server replica set members. Keeping this value consistent: + +- Ensures the routing table history is retained for at least as long as + the transaction lifetime limit on the shard replica set members. + +- Reduces the transaction retry frequency and therefore improves + performance. \ No newline at end of file diff --git a/source/reference/parameters.txt b/source/reference/parameters.txt index 0a08c0a3eb9..12eb3d7c777 100644 --- a/source/reference/parameters.txt +++ b/source/reference/parameters.txt @@ -4014,11 +4014,11 @@ Transaction Parameters *Default*: 60 Specifies the lifetime of :doc:`multi-document transactions - `. Transactions that exceeds this limit are + `. Transactions that exceed this limit are considered expired and will be aborted by a periodic cleanup process. The cleanup process runs every :parameter:`transactionLifetimeLimitSeconds`/2 seconds or at least - once per every 60 seconds. + once every 60 seconds. The cleanup process helps relieve storage cache pressure. @@ -4042,7 +4042,9 @@ Transaction Parameters To set the parameter for a sharded cluster, the parameter must be modified for all shard replica set members. - + + .. include:: /includes/transactionLifetimeLimitSeconds-parameter.rst + .. parameter:: maxTransactionLockRequestTimeoutMillis .. versionadded:: 4.0 diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt index a2144e5426c..58f650a47d0 100644 --- a/source/release-notes/5.0-compatibility.txt +++ b/source/release-notes/5.0-compatibility.txt @@ -337,6 +337,11 @@ If ``auditLog.runtimeConfiguration`` is set to ``false`` and an audit filter config document is present, then a startup warning will be issued but the server will not abort. +Reduce Risk of Stale Chunks in Sharded Transactions +--------------------------------------------------- + +.. include:: /includes/transactionLifetimeLimitSeconds-parameter.rst + General Changes --------------- From 64e21f4ea6e5c649c67e7c1dc123f3519b19b44f Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Mon, 11 Oct 2021 15:00:53 +0200 Subject: [PATCH 082/109] DOCS-14469: Address rename behaviour --- source/reference/method/db.collection.renameCollection.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/source/reference/method/db.collection.renameCollection.txt b/source/reference/method/db.collection.renameCollection.txt index fa85443e91b..4b740850396 100644 --- a/source/reference/method/db.collection.renameCollection.txt +++ b/source/reference/method/db.collection.renameCollection.txt @@ -68,7 +68,7 @@ warnings and messages. :dbcommand:`renameCollection` command create an :ref:`change-event-invalidate` for any existing :doc:`/changeStreams` opened on the source or target collection. - + - The method has the following limitations: - :method:`db.collection.renameCollection()` cannot move a collection @@ -83,6 +83,9 @@ warnings and messages. - :method:`db.collection.renameCollection()` is not supported on :term:`time series collections