Skip to content

Commit 4b64812

Browse files
rustagirrustagir
authored
DOCSP-26052: upgrade guide (#634)
* DOCSP-26052: upgrade guide * new file * add to toc + links * typo fix * JS PR fixes 1
1 parent 28588ac commit 4b64812

File tree

5 files changed

+194
-7
lines changed

5 files changed

+194
-7
lines changed

‎snooty.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ mongosh = "``mongosh``"
2525
driver = "node"
2626
driver-long = "MongoDB Node.js driver"
2727
driver-short = "Node.js driver"
28+
mdb-server = "MongoDB Server"
2829
node-legacy = "`MongoDB Node.js driver with optional callback support <https://www.npmjs.com/package/mongodb-legacy>`__"
2930
stable-api = "Stable API"
3031
qe = "Queryable Encryption"

‎source/compatibility.txt‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
1+
.. _node-compatibility:
2+
3+
=============
4+
Compatibility
5+
=============
6+
17
.. contents:: On this page
28
:local:
39
:backlinks: none
410
:depth: 2
511
:class: singlecol
612

7-
=============
8-
Compatibility
9-
=============
10-
1113
MongoDB Compatibility
1214
---------------------
1315
The following compatibility table specifies the recommended versions of

‎source/index.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ MongoDB Node Driver
1717
/issues-and-help
1818
/compatibility
1919
/whats-new
20+
/upgrade
2021
Release Notes <https://github.com/mongodb/node-mongodb-native/releases/>
2122
View the Source <https://github.com/mongodb/node-mongodb-native/>
2223

@@ -84,6 +85,12 @@ What's New
8485
For a list of new features and changes in each version, see the
8586
:doc:`What's New </whats-new>` section.
8687

88+
Upgrade Driver Versions
89+
-----------------------
90+
91+
Learn what changes you may need to make to your application to upgrade
92+
driver versions in the :ref:`<node-upgrade-driver>` section.
93+
8794
Learn
8895
-----
8996

‎source/upgrade.txt‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
.. _node-upgrade-driver:
2+
3+
=======================
4+
Upgrade Driver Versions
5+
=======================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
On this page, you can learn about any changes you might need to make to
17+
your application to upgrade your driver to a new version without loss of
18+
functionality.
19+
20+
Before you upgrade, perform the following actions:
21+
22+
- Ensure the new driver version is compatible with the {+mdb-server+} version
23+
your application connects to and the version of Node.js that your
24+
application runs on. See the :ref:`<node-compatibility>`
25+
page for this information.
26+
- Address any breaking changes between the version of the driver
27+
your application currently uses and your planned upgrade version in the
28+
:ref:`<node-breaking-changes>` section of this guide. To learn
29+
more about the {+mdb-server+} release compatibility changes, see the
30+
:ref:`<node-server-support-changes>` section.
31+
32+
.. tip::
33+
34+
You can minimize the amount of changes that you need to make to your
35+
application when upgrading driver versions by using the
36+
:ref:`{+stable-api+} <nodejs-stable-api>`.
37+
38+
.. _node-breaking-changes:
39+
40+
Breaking Changes
41+
----------------
42+
43+
A breaking change is a modification in a convention or behavior in
44+
a specific version of the driver that may prevent your application from
45+
working as expected.
46+
47+
The breaking changes in this section are categorized by the major
48+
version releases that introduced them. When upgrading driver versions,
49+
address all the breaking changes between your current version and the
50+
planned upgrade version. For example, if you are upgrading the driver
51+
from v3.x to v5.x, address all breaking changes listed under v4.x and
52+
v5.x.
53+
54+
.. _node-breaking-changes-v5.x:
55+
56+
Version 5.x Breaking Changes
57+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58+
59+
- Driver versions 5.x are not compatible with Node.js
60+
v12 or earlier. If you want to use this version of the driver, You must
61+
use Node.js v14.20.1 or greater.
62+
63+
- The driver removes support for callbacks in favor of a promise-based API.
64+
The following list provides some strategies for callback users to adopt this
65+
version:
66+
67+
- Migrate to the promise-based API (recommended)
68+
- Use the promise-based API and ``util.callbackify``
69+
- Add ``mongodb-legacy`` to continue using callbacks
70+
71+
For more information about these strategies, see
72+
`the v5.0 changelog <https://github.com/mongodb/node-mongodb-native/blob/main/etc/notes/CHANGES_5.0.0.md#optional-callback-support-migrated-to-mongodb-legacy>`__.
73+
74+
- The driver removes support for the ``Collection.insert()``,
75+
``Collection.update()``, and ``Collection.remove()`` helper methods.
76+
The following list provides instructions on how to replace the
77+
functionality of the removed methods:
78+
79+
- Migrate from ``Collection.insert()`` to ``insertOne()`` or ``insertMany()``
80+
- Migrate from ``Collection.update()`` to ``updateOne()`` or ``updateMany()``
81+
- Migrate from ``Collection.remove()`` to ``deleteOne()`` or ``deleteMany()``
82+
83+
- The driver no longer includes AWS SDK modules by default.
84+
85+
- The driver no longer automatically imports the ``bson-ext`` package.
86+
87+
- The driver removes support for custom ``Promise`` libraries. The driver no
88+
longer supports the ``promiseLibrary`` option of ``MongoClient`` and the ``Promise.set``
89+
export that allows specifying a custom ``Promise`` library.
90+
91+
- The driver removes support for the ``Collection.mapReduce()`` helper.
92+
93+
- The ``BulkWriteResult`` type no longer has the publicly enumerable
94+
``result`` property.
95+
96+
- The following types, options, and methods have been removed:
97+
98+
- ``BulkResult.lastOp()`` method
99+
- ``opTime`` property of ``BulkResult``
100+
- ``BulkWriteOptions.keepGoing`` option
101+
- ``WriteConcernError.err()`` method
102+
- ``AddUserOptions.digestPassword`` option
103+
- Kerberos ``gssapiCanonicalizeHostName`` option
104+
- ``slaveOk`` options and method removed in favor of ``secondaryOk``
105+
- ``ObjectID`` type removed in favor of ``ObjectId``
106+
- ``AsyncIterator`` interface removed in favor of ``AsyncGenerator``
107+
108+
.. _node-breaking-changes-v4.x:
109+
110+
Version 4.x Breaking Changes
111+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112+
113+
- Driver versions 4.x are not compatible with Node.js
114+
v12.8 or earlier. If you want to use this version of the driver, You must
115+
use Node.js v12.9 or greater.
116+
117+
- ``Cursor`` types no longer extend ``Readable`` directly.
118+
119+
- You cannot use a ``ChangeStream`` instance as an iterator after using
120+
it as an ``EventEmitter``. You also cannot do the reverse—using an
121+
``EventEmitter`` instance as an iterator after using it as a ``ChangeStream``.
122+
123+
- The following methods no longer accept a callback parameter:
124+
125+
- ``Collection.find()``
126+
- ``Collection.aggregate()``
127+
- ``Db.aggregate()``
128+
129+
- The default value of the ``maxPoolSize`` connection option is now
130+
``100``.
131+
132+
- The driver no longer supports the ``gssapiServiceName`` Kerberos
133+
option. Users should use ``authMechanismProperties.SERVICE_NAME`` instead.
134+
135+
- The driver no longer accepts non-boolean types, such as ``0`` or
136+
``1``, for boolean options.
137+
138+
- The ``db.collection`` type no longer accepts a callback.
139+
140+
- The ``Db`` type is no longer an ``EventEmitter``. You can listen to
141+
any events directly from the ``MongoClient`` instance.
142+
143+
- The driver removes support for the ``Collection.group()`` helper.
144+
145+
- The driver no longer includes the deprecated ``GridStore`` API.
146+
147+
For more information about these changes, see
148+
`the v4.0 changelog <https://github.com/mongodb/node-mongodb-native/blob/main/etc/notes/CHANGES_4.0.0.md>`__.
149+
150+
.. _node-server-support-changes:
151+
152+
Server Release Compatibility Changes
153+
------------------------------------
154+
155+
A server release compatibility change is a modification
156+
to the driver that discontinues support for a set of
157+
{+mdb-server+} versions.
158+
159+
The driver discontinues support for a {+mdb-server+} version after it reaches
160+
end-of-life (EOL).
161+
162+
To learn more about the MongoDB support for EOL products,
163+
see the `Legacy Support Policy <https://www.mongodb.com/support-policy/legacy>`__.
164+
165+
Version 4.2 Server Release Support Changes
166+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167+
168+
- The v4.2 driver drops support for {+mdb-server+} v3.4 and earlier.
169+
To use the v4.2 driver, your {+mdb-server+} must be v3.6 or later. To learn
170+
how to upgrade your {+mdb-server+} to v3.6, follow the link that corresponds
171+
to your MongoDB deployment configuration:
172+
173+
- :ref:`<3.6-upgrade-replica-set>`
174+
- :ref:`<3.6-upgrade-standalone>`
175+
- :ref:`<3.6-upgrade-sharded-cluster>`

‎source/whats-new.txt‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,9 @@ What's New in 5.0
7575
- Migrate from ``Collection.insert()`` to ``insertOne()`` or ``insertMany()``
7676
- Migrate from ``Collection.update()`` to ``updateOne()`` or ``updateMany()``
7777
- Migrate from ``Collection.remove()`` to ``deleteOne()`` or ``deleteMany()``
78+
79+
To view a full list of breaking changes introduced in this version, see the :ref:`Breaking
80+
Changes section <node-breaking-changes-v5.x>` in the Upgrade guide.
7881

7982
New features of the 5.0 {+driver-short+} release include:
8083

@@ -684,9 +687,8 @@ for more information.
684687
Detailed List
685688
~~~~~~~~~~~~~
686689

687-
For a detailed list of breaking changes, removals, and associated JIRA tickets,
688-
see the detailed `list here <https://github.com/mongodb/node-mongodb-native/blob/4.0/docs/CHANGES_4.0.0.md>`__.
689-
690+
To view a full list of breaking changes introduced in this version, see the :ref:`Breaking
691+
Changes section <node-breaking-changes-v4.x>` in the Upgrade guide.
690692

691693
.. _version-3.7:
692694

0 commit comments

Comments
 (0)