From b00f0f6f4998adf75a889c36b2e7ab78c439303e Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 12 Sep 2024 16:45:53 -0500 Subject: [PATCH 1/7] wip --- config/redirects | 2 +- snooty.toml | 2 +- .../mongodb-compatibility-table-node.rst | 17 ++++- source/whats-new.txt | 69 +++++++++++++++++++ 4 files changed, 87 insertions(+), 3 deletions(-) diff --git a/config/redirects b/config/redirects index ac1f802de..03fe2e595 100644 --- a/config/redirects +++ b/config/redirects @@ -1,6 +1,6 @@ define: prefix docs/drivers/node define: base https://www.mongodb.com/${prefix} -define: versions v3.6 v3.7 v4.0 v4.1 v4.2 v4.3 v4.4 v4.5 v4.6 v4.7 v4.8 v4.9 v4.10 v4.11 v4.12 v4.13 v4.14 v4.15 v4.16 v4.17 v5.0 v5.1 v5.2 v5.3 v5.4 v5.5 v5.6 v5.7 v5.8 v5.9 v6.0 v6.1 v6.2 v6.3 v6.4 v6.5 v6.6 v6.7 v6.8 master +define: versions v3.6 v3.7 v4.0 v4.1 v4.2 v4.3 v4.4 v4.5 v4.6 v4.7 v4.8 v4.9 v4.10 v4.11 v4.12 v4.13 v4.14 v4.15 v4.16 v4.17 v5.0 v5.1 v5.2 v5.3 v5.4 v5.5 v5.6 v5.7 v5.8 v5.9 v6.0 v6.1 v6.2 v6.3 v6.4 v6.5 v6.6 v6.7 v6.8 v6.9 master symlink: current -> master diff --git a/snooty.toml b/snooty.toml index 27e759fd3..d5af02dd7 100644 --- a/snooty.toml +++ b/snooty.toml @@ -19,7 +19,7 @@ toc_landing_pages = [ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" [constants] -version = "6.8" +version = "6.9" api = "https://mongodb.github.io/node-mongodb-native/{+version+}" driver-long = "MongoDB Node.js driver" driver-short = "Node.js driver" diff --git a/source/includes/mongodb-compatibility-table-node.rst b/source/includes/mongodb-compatibility-table-node.rst index 732215b24..285f498c6 100644 --- a/source/includes/mongodb-compatibility-table-node.rst +++ b/source/includes/mongodb-compatibility-table-node.rst @@ -17,7 +17,21 @@ - MongoDB 3.0 - MongoDB 2.6 - * - 6.0 to 6.9 + * - 6.9 + - ✓ + - ✓ + - ✓ + - ✓ + - ✓ + - ✓ + - ✓ + - ✓ [#deprecated]_ + - + - + - + - + + * - 6.0 to 6.8 - ⊛ - ✓ - ✓ @@ -214,3 +228,4 @@ - ✓ .. [#unified-topology] When using Node.js Driver version 3.7, you must set the ``useUnifiedTopology`` flag to ``true`` for certain features. +.. [#deprecated] Support for MongoDB 3.6 is deprecated in {+driver+short+} v6.9. \ No newline at end of file diff --git a/source/whats-new.txt b/source/whats-new.txt index ed7bab4ed..60bf77f51 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -19,6 +19,7 @@ What's New Learn what's new in: +* :ref:`Version 6.9 ` * :ref:`Version 6.8 ` * :ref:`Version 6.7 ` * :ref:`Version 6.6 ` @@ -59,6 +60,74 @@ Learn what's new in: * :ref:`Version 3.7 ` * :ref:`Version 3.6 ` +.. _version-6.9: + +What's New in 6.9.0 +------------------- + +- Support for {+mdb-server+} 3.6 is deprecated and will be removed in a future driver release. +- The driver natively supports explicit resource management for cursors and the + ``MongoClient``, ``ClientSession``, ``ChangeStream`` objects. On compatible Node.js + versions, you can use explicit resource management used with the ``cursor.stream()`` + method and ``GridFSDownloadStream`` class. + + To learn how to use explicit resource management, see the + :github:`v6.9.0 Release Notes ` on + GitHub. For more information about explicit resource management, see the + :github:`ECMAScript Explicit Resource Management Proposal ` + on GitHub. +- If you're using Node.js 18.13 or later, you can pass the ``autoSelectFamily`` and + ``autoSelectFamilyTimeout`` options to the ``MongoClient`` constructor. When the + ``autoSelectFamily`` option is ``true``, the driver automatically selects between + an IPv4 or IPv6 connection. + + The following code example shows how to use these options: + + .. code-block:: javascript + :copyable: true + + const client = new MongoClient(process.env.MONGODB_URI, { autoSelectFamily: true, autoSelectFamilyTimeout: 100 }); +- The ``MongoClient`` constructor accepts the ``allowPartialTrustChain`` option. This option + controls the X509_V_FLAG_PARTIAL_CHAIN OpenSSL flag. +- Fixes the ``enableUtf8Validation`` when deserializing BSON. +- Adds the ``durationMS`` property to the ``ConnectionReadyEvent`` class. This property + represents the time between the connection creation event and when the ``ConnectionReadyEvent`` + fires. +- The ``ConnectionCheckedOutEvent`` and ``ConnectionCheckFailedEvent`` now include a ``durationMS`` + property. This property indicates the time elapsed between the start and end of a + connection checkout operation. +- If you're using Node.js 18 or later, the driver ignores the ``cryptoCallbacks`` option + and uses callbacks defined in C++ instead, significantly improving encryption + performance. This change is available in ``mongodb-client-encryption`` v6.1.0. +- To enhance security, the options specifying the spawn path and arguments for + ``mongocryptd`` must be own properties of ``autoEncryption.extraOptions``. + This change helps prevent global prototype pollution bugs related to these options. + For more information about own properties, see + `Object.hasOwn() `__ + on MDN. +- The driver officially supports Queryable Encryption (QE) range queries. To use this + feature, your app must use ``mongodb-client-encryption`` v6.1.0 or later and must connect + to {+mdb-server+} 8.0 or later. For more information about QE range queries, see + :manual:`Queryable Encryption ` in the {+mdb-server+} manual. +- The ``insertMany()`` and ``bulkWrite()`` methods accept ``ReadonlyArray`` inputs. +- The driver retries writes based on the top-level code, found in ``error.code``, rather + than the nested code in ``error.result.writeConcernError.code``. +- The ``LocalKMSProviderConfiguration.key`` property accepts a ``BSON`` ``Binary`` instance + for ``AutoEncryptionOptions``. +- In TypeScript, the ``BulkOperationBase`` class reports the ``length`` getter property. +- The ``MongoWriteConcernError`` type now preserves the original top-level code in + ``MongoWriteConcernError.code``. +- The ``cursor.toArray()`` method empties the current batch of documents into the array + before calling the async iterator again. This change avoids the delays associated + with ``async``/``await`` execution and improves performance by up to 5% on average. + This optimization doesn't apply if you provide a transform to the ``cursor.map()`` method + before calling the ``toArray()`` method. +- Fixes mixed use of the ``cursor.next()`` method along with ``for await`` syntax. + +To learn more about this release, see the +:github:`v6.9.0 Release Notes ` on +GitHub. + .. _version-6.8: What's New in 6.8 From 691247f0286add85d41db2022e61b0a6989b005a Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 13 Sep 2024 09:48:40 -0500 Subject: [PATCH 2/7] cleanup --- source/whats-new.txt | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/source/whats-new.txt b/source/whats-new.txt index 60bf77f51..dd10fa756 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -62,13 +62,13 @@ Learn what's new in: .. _version-6.9: -What's New in 6.9.0 -------------------- +What's New in 6.9 +----------------- - Support for {+mdb-server+} 3.6 is deprecated and will be removed in a future driver release. - The driver natively supports explicit resource management for cursors and the - ``MongoClient``, ``ClientSession``, ``ChangeStream`` objects. On compatible Node.js - versions, you can use explicit resource management used with the ``cursor.stream()`` + ``MongoClient``, ``ClientSession``, and ``ChangeStream`` objects. On compatible Node.js + versions, you can use explicit resource management with the ``cursor.stream()`` method and ``GridFSDownloadStream`` class. To learn how to use explicit resource management, see the @@ -79,7 +79,8 @@ What's New in 6.9.0 - If you're using Node.js 18.13 or later, you can pass the ``autoSelectFamily`` and ``autoSelectFamilyTimeout`` options to the ``MongoClient`` constructor. When the ``autoSelectFamily`` option is ``true``, the driver automatically selects between - an IPv4 or IPv6 connection. + an IPv4 or IPv6 connection. The ``autoSelectFamilyTimeout`` option specifies the + timeout, in milliseconds, for the driver to select the connection family. The following code example shows how to use these options: @@ -89,10 +90,6 @@ What's New in 6.9.0 const client = new MongoClient(process.env.MONGODB_URI, { autoSelectFamily: true, autoSelectFamilyTimeout: 100 }); - The ``MongoClient`` constructor accepts the ``allowPartialTrustChain`` option. This option controls the X509_V_FLAG_PARTIAL_CHAIN OpenSSL flag. -- Fixes the ``enableUtf8Validation`` when deserializing BSON. -- Adds the ``durationMS`` property to the ``ConnectionReadyEvent`` class. This property - represents the time between the connection creation event and when the ``ConnectionReadyEvent`` - fires. - The ``ConnectionCheckedOutEvent`` and ``ConnectionCheckFailedEvent`` now include a ``durationMS`` property. This property indicates the time elapsed between the start and end of a connection checkout operation. @@ -111,7 +108,8 @@ What's New in 6.9.0 :manual:`Queryable Encryption ` in the {+mdb-server+} manual. - The ``insertMany()`` and ``bulkWrite()`` methods accept ``ReadonlyArray`` inputs. - The driver retries writes based on the top-level code, found in ``error.code``, rather - than the nested code in ``error.result.writeConcernError.code``. + than the nested code in ``error.result.writeConcernError.code``. This fixes an issue + in sharded clusters running versions {+mdb-server+} earlier than 4.4. - The ``LocalKMSProviderConfiguration.key`` property accepts a ``BSON`` ``Binary`` instance for ``AutoEncryptionOptions``. - In TypeScript, the ``BulkOperationBase`` class reports the ``length`` getter property. @@ -123,9 +121,13 @@ What's New in 6.9.0 This optimization doesn't apply if you provide a transform to the ``cursor.map()`` method before calling the ``toArray()`` method. - Fixes mixed use of the ``cursor.next()`` method along with ``for await`` syntax. +- Fixes the ``enableUtf8Validation`` when deserializing BSON. +- Adds the ``durationMS`` property to the ``ConnectionReadyEvent`` class. This property + represents the time between the connection creation event and when the ``ConnectionReadyEvent`` + fires. To learn more about this release, see the -:github:`v6.9.0 Release Notes ` on +:github:`v6.9 Release Notes ` on GitHub. .. _version-6.8: From 04df1b29e80635c901f1bf23cb6a268352028d47 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 13 Sep 2024 09:58:13 -0500 Subject: [PATCH 3/7] fixes --- source/includes/mongodb-compatibility-table-node.rst | 2 +- source/whats-new.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/mongodb-compatibility-table-node.rst b/source/includes/mongodb-compatibility-table-node.rst index 285f498c6..53a547118 100644 --- a/source/includes/mongodb-compatibility-table-node.rst +++ b/source/includes/mongodb-compatibility-table-node.rst @@ -228,4 +228,4 @@ - ✓ .. [#unified-topology] When using Node.js Driver version 3.7, you must set the ``useUnifiedTopology`` flag to ``true`` for certain features. -.. [#deprecated] Support for MongoDB 3.6 is deprecated in {+driver+short+} v6.9. \ No newline at end of file +.. [#deprecated] Support for MongoDB 3.6 is deprecated in {+driver-short+} v6.9. \ No newline at end of file diff --git a/source/whats-new.txt b/source/whats-new.txt index dd10fa756..f38d5d6c7 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -127,7 +127,7 @@ What's New in 6.9 fires. To learn more about this release, see the -:github:`v6.9 Release Notes ` on +:github:`v6.9.0 Release Notes ` on GitHub. .. _version-6.8: From 5115bdbf3bd91a1ae85269ed28776adbfb445642 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 13 Sep 2024 13:33:30 -0500 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Rea Rustagi <85902999+rustagir@users.noreply.github.com> --- source/includes/mongodb-compatibility-table-node.rst | 2 +- source/whats-new.txt | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/source/includes/mongodb-compatibility-table-node.rst b/source/includes/mongodb-compatibility-table-node.rst index 53a547118..58b9364b6 100644 --- a/source/includes/mongodb-compatibility-table-node.rst +++ b/source/includes/mongodb-compatibility-table-node.rst @@ -228,4 +228,4 @@ - ✓ .. [#unified-topology] When using Node.js Driver version 3.7, you must set the ``useUnifiedTopology`` flag to ``true`` for certain features. -.. [#deprecated] Support for MongoDB 3.6 is deprecated in {+driver-short+} v6.9. \ No newline at end of file +.. [#server-3.6-deprecated] Support for MongoDB 3.6 is deprecated in {+driver-short+} v6.9. \ No newline at end of file diff --git a/source/whats-new.txt b/source/whats-new.txt index f38d5d6c7..6880324a4 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -67,8 +67,8 @@ What's New in 6.9 - Support for {+mdb-server+} 3.6 is deprecated and will be removed in a future driver release. - The driver natively supports explicit resource management for cursors and the - ``MongoClient``, ``ClientSession``, and ``ChangeStream`` objects. On compatible Node.js - versions, you can use explicit resource management with the ``cursor.stream()`` + ``MongoClient``, ``ClientSession``, and ``ChangeStream`` objects. When using a compatible Node.js + version, you can implement explicit resource management by using the ``cursor.stream()`` method and ``GridFSDownloadStream`` class. To learn how to use explicit resource management, see the @@ -89,20 +89,20 @@ What's New in 6.9 const client = new MongoClient(process.env.MONGODB_URI, { autoSelectFamily: true, autoSelectFamilyTimeout: 100 }); - The ``MongoClient`` constructor accepts the ``allowPartialTrustChain`` option. This option - controls the X509_V_FLAG_PARTIAL_CHAIN OpenSSL flag. + controls the ``X509_V_FLAG_PARTIAL_CHAIN`` OpenSSL flag. - The ``ConnectionCheckedOutEvent`` and ``ConnectionCheckFailedEvent`` now include a ``durationMS`` property. This property indicates the time elapsed between the start and end of a connection checkout operation. - If you're using Node.js 18 or later, the driver ignores the ``cryptoCallbacks`` option and uses callbacks defined in C++ instead, significantly improving encryption - performance. This change is available in ``mongodb-client-encryption`` v6.1.0. + performance. This change is available in the v6.1.0 version of the ``mongodb-client-encryption`` package. - To enhance security, the options specifying the spawn path and arguments for ``mongocryptd`` must be own properties of ``autoEncryption.extraOptions``. This change helps prevent global prototype pollution bugs related to these options. For more information about own properties, see `Object.hasOwn() `__ on MDN. -- The driver officially supports Queryable Encryption (QE) range queries. To use this +- Official support for Queryable Encryption (QE) range queries. To use this feature, your app must use ``mongodb-client-encryption`` v6.1.0 or later and must connect to {+mdb-server+} 8.0 or later. For more information about QE range queries, see :manual:`Queryable Encryption ` in the {+mdb-server+} manual. @@ -120,7 +120,7 @@ What's New in 6.9 with ``async``/``await`` execution and improves performance by up to 5% on average. This optimization doesn't apply if you provide a transform to the ``cursor.map()`` method before calling the ``toArray()`` method. -- Fixes mixed use of the ``cursor.next()`` method along with ``for await`` syntax. +- Fixes mixed use of the ``cursor.next()`` method with ``for await`` syntax. - Fixes the ``enableUtf8Validation`` when deserializing BSON. - Adds the ``durationMS`` property to the ``ConnectionReadyEvent`` class. This property represents the time between the connection creation event and when the ``ConnectionReadyEvent`` From 5bdcfed86b88377a956ba87b8ba9c1a2f3018718 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 13 Sep 2024 13:41:02 -0500 Subject: [PATCH 5/7] feedback --- source/whats-new.txt | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/source/whats-new.txt b/source/whats-new.txt index 6880324a4..176391cfb 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -66,6 +66,7 @@ What's New in 6.9 ----------------- - Support for {+mdb-server+} 3.6 is deprecated and will be removed in a future driver release. + - The driver natively supports explicit resource management for cursors and the ``MongoClient``, ``ClientSession``, and ``ChangeStream`` objects. When using a compatible Node.js version, you can implement explicit resource management by using the ``cursor.stream()`` @@ -76,6 +77,7 @@ What's New in 6.9 GitHub. For more information about explicit resource management, see the :github:`ECMAScript Explicit Resource Management Proposal ` on GitHub. + - If you're using Node.js 18.13 or later, you can pass the ``autoSelectFamily`` and ``autoSelectFamilyTimeout`` options to the ``MongoClient`` constructor. When the ``autoSelectFamily`` option is ``true``, the driver automatically selects between @@ -87,41 +89,57 @@ What's New in 6.9 .. code-block:: javascript :copyable: true - const client = new MongoClient(process.env.MONGODB_URI, { autoSelectFamily: true, autoSelectFamilyTimeout: 100 }); + const client = new MongoClient(url, + { autoSelectFamily: true, autoSelectFamilyTimeout: 100 }); + - The ``MongoClient`` constructor accepts the ``allowPartialTrustChain`` option. This option controls the ``X509_V_FLAG_PARTIAL_CHAIN`` OpenSSL flag. + - The ``ConnectionCheckedOutEvent`` and ``ConnectionCheckFailedEvent`` now include a ``durationMS`` property. This property indicates the time elapsed between the start and end of a connection checkout operation. + - If you're using Node.js 18 or later, the driver ignores the ``cryptoCallbacks`` option and uses callbacks defined in C++ instead, significantly improving encryption performance. This change is available in the v6.1.0 version of the ``mongodb-client-encryption`` package. + - To enhance security, the options specifying the spawn path and arguments for ``mongocryptd`` must be own properties of ``autoEncryption.extraOptions``. This change helps prevent global prototype pollution bugs related to these options. For more information about own properties, see `Object.hasOwn() `__ on MDN. -- Official support for Queryable Encryption (QE) range queries. To use this + +- Adds official support for Queryable Encryption (QE) range queries. To use this feature, your app must use ``mongodb-client-encryption`` v6.1.0 or later and must connect to {+mdb-server+} 8.0 or later. For more information about QE range queries, see :manual:`Queryable Encryption ` in the {+mdb-server+} manual. + - The ``insertMany()`` and ``bulkWrite()`` methods accept ``ReadonlyArray`` inputs. + - The driver retries writes based on the top-level code, found in ``error.code``, rather than the nested code in ``error.result.writeConcernError.code``. This fixes an issue in sharded clusters running versions {+mdb-server+} earlier than 4.4. + - The ``LocalKMSProviderConfiguration.key`` property accepts a ``BSON`` ``Binary`` instance for ``AutoEncryptionOptions``. -- In TypeScript, the ``BulkOperationBase`` class reports the ``length`` getter property. + +- In TypeScript, the ``BulkOperationBase`` class reports the ``length`` getter property. + - The ``MongoWriteConcernError`` type now preserves the original top-level code in ``MongoWriteConcernError.code``. + - The ``cursor.toArray()`` method empties the current batch of documents into the array before calling the async iterator again. This change avoids the delays associated with ``async``/``await`` execution and improves performance by up to 5% on average. This optimization doesn't apply if you provide a transform to the ``cursor.map()`` method before calling the ``toArray()`` method. + - Fixes mixed use of the ``cursor.next()`` method with ``for await`` syntax. -- Fixes the ``enableUtf8Validation`` when deserializing BSON. + +- Adds the ``enableUtf8Validation`` option when deserializing BSON, which was + inadvertently removed in {+driver-short+} v6.8. + - Adds the ``durationMS`` property to the ``ConnectionReadyEvent`` class. This property represents the time between the connection creation event and when the ``ConnectionReadyEvent`` fires. From 55f6c4e0af60248b86d010fa0ee3bee678b74a2b Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 13 Sep 2024 14:43:35 -0500 Subject: [PATCH 6/7] feedback --- source/fundamentals/monitoring/connection-monitoring.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/monitoring/connection-monitoring.txt b/source/fundamentals/monitoring/connection-monitoring.txt index 9ee671252..3aa3789fa 100644 --- a/source/fundamentals/monitoring/connection-monitoring.txt +++ b/source/fundamentals/monitoring/connection-monitoring.txt @@ -160,7 +160,8 @@ connectionReady ConnectionReadyEvent { time: 2023-02-13T15:56:38.291Z, address: '...', - connectionId: 1 + connectionId: 1, + durationMS: 60 } connectionClosed @@ -197,7 +198,8 @@ connectionCheckOutFailed ConnectionCheckOutFailedEvent { time: 2023-02-13T15:56:38.291Z, address: '...', - reason: ... + reason: ..., + durationMS: 60 } connectionCheckedOut @@ -209,7 +211,8 @@ connectionCheckedOut ConnectionCheckedOutEvent { time: 2023-02-13T15:54:07.188Z, address: '...', - connectionId: 1 + connectionId: 1, + durationMS: 60 } connectionCheckedIn From 57e6a5d1a31ca9cd26c137702ff800d690319216 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 13 Sep 2024 14:51:28 -0500 Subject: [PATCH 7/7] feedback --- source/includes/mongodb-compatibility-table-node.rst | 2 +- source/whats-new.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/mongodb-compatibility-table-node.rst b/source/includes/mongodb-compatibility-table-node.rst index 58b9364b6..4cee78cc9 100644 --- a/source/includes/mongodb-compatibility-table-node.rst +++ b/source/includes/mongodb-compatibility-table-node.rst @@ -25,7 +25,7 @@ - ✓ - ✓ - ✓ - - ✓ [#deprecated]_ + - ✓ [#server-3.6-deprecated]_ - - - diff --git a/source/whats-new.txt b/source/whats-new.txt index 176391cfb..c09592217 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -89,7 +89,7 @@ What's New in 6.9 .. code-block:: javascript :copyable: true - const client = new MongoClient(url, + const client = new MongoClient(uri, { autoSelectFamily: true, autoSelectFamilyTimeout: 100 }); - The ``MongoClient`` constructor accepts the ``allowPartialTrustChain`` option. This option