Skip to content

Commit f337e8f

Browse files
norareidynorareidy
authored
DOCSP-51349: Upgrade guide (#127)
* DOCSP-51349: Upgrade guide * edits * edits
1 parent 9084089 commit f337e8f

File tree

1 file changed

+387
-1
lines changed

1 file changed

+387
-1
lines changed

‎source/reference/upgrade.txt

Lines changed: 387 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,390 @@ Upgrade Driver Versions
88
:local:
99
:backlinks: none
1010
:depth: 1
11-
:class: singlecol
11+
:class: singlecol
12+
13+
.. meta::
14+
:keywords: backwards compatibility, update
15+
16+
Overview
17+
--------
18+
19+
In this section, you can identify the changes you must
20+
make to your application to upgrade your driver to a new version.
21+
22+
Before you upgrade, perform the following actions:
23+
24+
- Ensure the new driver version is compatible with the {+mdb-server+} versions
25+
your application connects to and the Java Runtime Environment (JRE) your
26+
application runs on. To view compatibility information, see the
27+
:ref:`Compatibility <kotlin-sync-compatibility>` page.
28+
- Address any breaking changes between the current version of the driver
29+
your application is using and your planned upgrade version in the
30+
:ref:`Breaking Changes <kotlin-sync-breaking-changes>` section. To learn
31+
more about {+mdb-server+} release compatibility changes, see the
32+
:ref:`<kotlin-sync-server-release-changes>` section.
33+
34+
.. tip::
35+
36+
To minimize the number of changes your application might require when
37+
you upgrade driver versions in the future, use the
38+
:ref:`{+stable-api+}. <kotlin-sync-stable-api>`
39+
40+
.. _kotlin-sync-breaking-changes:
41+
42+
Breaking Changes
43+
----------------
44+
45+
A breaking change is a modification in a convention or behavior in
46+
a specific version of the driver that might prevent your application from
47+
working properly if not addressed before upgrading.
48+
49+
The breaking changes in this section are categorized by the driver version that
50+
introduced them. When upgrading driver versions, address all the breaking
51+
changes between the current and upgrade versions. For example, if you
52+
are upgrading the driver from v5.0 to v5.5, address all breaking changes from
53+
the versions after v5.0 including any listed for v5.5.
54+
55+
.. _kotlin-sync-breaking-changes-v5.5:
56+
57+
Version 5.5 Breaking Changes
58+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
59+
60+
- The driver is no longer compatible with {+mdb-server+} version
61+
4.0. To learn more about this change, see the
62+
:ref:`kotlin-sync-server-release-change-v5.5` section.
63+
64+
.. _kotlin-sync-breaking-changes-v5.2:
65+
66+
Version 5.2 Breaking Changes
67+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
68+
69+
This driver version introduces the following breaking changes:
70+
71+
- Drops support for {+mdb-server+} v3.6. To learn more about this change,
72+
see the :ref:`<kotlin-sync-server-release-change-v5.2>` section.
73+
74+
- Revises the `mongodb-crypt <https://mvnrepository.com/artifact/org.mongodb/mongodb-crypt>`__
75+
dependency versioning to match the versioning for the JVM drivers. Future versions of
76+
``mongodb-crypt`` are released alongside the driver and share the same version number.
77+
You must upgrade your ``mongodb-crypt`` dependency to v5.2.0 when upgrading your driver for
78+
this release.
79+
80+
.. _kotlin-sync-breaking-changes-v5.1:
81+
82+
Version 5.1 Breaking Changes
83+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
84+
85+
This driver version introduces the following breaking changes:
86+
87+
- When using the ``MONGODB-OIDC`` authentication mechanism, you cannot
88+
include comma characters in the ``authMechanismProperties`` connection
89+
string value. If your ``authMechanismProperties`` value includes a comma,
90+
pass the value as a connection option in a ``MongoClientSettings`` instance.
91+
92+
.. _kotlin-sync-breaking-changes-v5.0:
93+
94+
Version 5.0 Breaking Changes
95+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
96+
97+
This driver version introduces the following breaking changes:
98+
99+
- Introduces the following changes to the ``ConnectionId`` class:
100+
101+
- The ``ConnectionId`` constructor now accepts a value of type ``long`` as its second
102+
parameter instead of type ``int``. Similarly, the constructor now accepts a value of
103+
type ``Long`` as its third parameter instead of type ``Integer``. Because this change breaks
104+
binary compatibility, recompile any existing code that calls the
105+
``ConnectionId`` constructor.
106+
107+
- The ``withServerValue()`` method now accepts a parameter of type ``long`` rather than
108+
type ``int``. Because this change breaks binary compatibility, you must recompile any code
109+
that calls the ``withServerValue()`` method.
110+
111+
- The ``getServerValue()`` method now returns a value of type ``Long`` instead of type
112+
``Integer``. Similarly, the ``getLocalValue()`` method returns a value of type
113+
``long`` instead of type ``int``. Because this change breaks both binary and source
114+
compatibility, update any source code that uses these methods and rebuild your binary.
115+
116+
- Replaces the following record annotations from the
117+
``org.bson.codecs.record.annotations`` package with
118+
annotations of the same name from the ``org.bson.codecs.pojo.annotations`` package:
119+
120+
- ``BsonId``
121+
- ``BsonProperty``
122+
- ``BsonRepresentation``
123+
124+
- Changes the data type of the ``connectTimeout`` timeout duration parameter for the
125+
``SocketSettings.Builder.connectTimeout()`` and
126+
``SocketSettings.Builder.readTimeout()`` methods. The data type of this
127+
parameter is now ``long`` instead of ``int``.
128+
129+
In earlier versions, this parameter is of type ``int`` for both methods. This
130+
change breaks binary compatibility and requires recompiling, but does not
131+
require code changes.
132+
133+
- Removes the ``Filters.eqFull()`` method, released
134+
exclusively in ``Beta``, which allowed you
135+
to construct an equality filter when performing a vector search.
136+
Instead, you can use the ``Filters.eq()`` method when instantiating a
137+
``VectorSearchOptions`` type, as shown in the following code:
138+
139+
.. code-block:: kotlin
140+
141+
val opts = vectorSearchOptions().filter(eq("x", 8))
142+
143+
- Changes how ``ClusterSettings`` computes the ``ClusterConnectionMode``
144+
setting, making it more consistent by using the specified
145+
replica set name, regardless of how it is configured. Previously, the driver
146+
considered the replica set name only if it was set in the connection string.
147+
148+
For example, the following two code samples both return the value
149+
``ClusterConnectionMode.MULTIPLE``. Previously, the second example returned
150+
``ClusterConnectionMode.SINGLE``.
151+
152+
.. code-block:: kotlin
153+
154+
ClusterSettings.builder()
155+
.applyConnectionString(ConnectionString("mongodb://127.0.0.1:27017/?replicaSet=replset"))
156+
.build()
157+
.mode
158+
159+
.. code-block:: kotlin
160+
161+
ClusterSettings.builder()
162+
.hosts(listOf(ServerAddress("127.0.0.1", 27017)))
163+
.requiredReplicaSetName("replset")
164+
.build()
165+
.mode
166+
167+
- ``BsonDecimal128`` values respond to method calls in the same way as
168+
``Decimal128`` values. ``BsonDecimal128.isNumber()`` now returns ``true`` and
169+
``BsonDecimal128.asNumber()`` returns the equivalent ``BsonNumber``.
170+
171+
- Removes the `ServerAddress <{+core-api+}/ServerAddress.html>`__
172+
methods ``getSocketAddress()`` and ``getSocketAddresses()``.
173+
174+
Instead of ``getSocketAddress()``, use the ``getByName()`` instance
175+
method of ``java.net.InetAddress``.
176+
177+
Instead of ``getSocketAddresses()``, use the ``getAllByName()`` instance
178+
method of ``java.net.InetAddress``.
179+
180+
- Removes the `UnixServerAddress <{+core-api+}/UnixServerAddress.html>`__
181+
methods ``getSocketAddress()`` and ``getUnixSocketAddress()``.
182+
183+
Instead of ``getSocketAddress()``, use the ``getByName()`` instance
184+
method of ``java.net.InetAddress``.
185+
186+
Instead of ``getUnixSocketAddress()``, construct an instance of
187+
``jnr.unixsocket.UnixSocketAddress``. Pass the full path of the UNIX
188+
socket file to the constructor. By default, MongoDB creates a UNIX
189+
socket file located at ``"/tmp/mongodb-27017.sock"``. To learn more
190+
about the ``UnixSocketAddress`` class, see the `UnixSocketAddress <https://www.javadoc.io/doc/com.github.jnr/jnr-unixsocket/latest/jnr/unixsocket/UnixSocketAddress.html>`__ API documentation.
191+
192+
- Removes the ``Parameterizable`` interface. Instead of
193+
implementing this interface on a custom ``Codec`` type,
194+
override the ``CodecProvider.get()`` method on the
195+
codec's ``CodecProvider`` if the codec is intended for a parameterized
196+
type.
197+
198+
- Removes the ``isSlaveOk()`` method from the
199+
``ReadPreference`` and ``TaggableReadPreference`` classes. To check whether a read preference allows
200+
reading from a secondary member of a replica set, use the ``isSecondaryOk()`` methods from
201+
these classes instead.
202+
203+
- Removes the ``DBCollection.getStats()`` and ``DBCollection.isCapped()``
204+
helper methods for the ``collStats`` command. Instead of these methods, you can use the
205+
``$collStats`` aggregation pipeline stage.
206+
207+
- Removes the ``MapCodec`` and ``IterableCodec`` classes.
208+
Instead of ``MapCodec``, use ``MapCodecProvider``. Instead of ``IterableCodec``,
209+
use ``CollectionCodecProvider``, or ``IterableCodecProvider`` for ``Iterable``
210+
types that aren't ``Collection`` types.
211+
212+
- Removes the ``sharded()`` and ``nonAtomic()`` methods from the
213+
``MapReducePublisher`` and ``MapReduceIterable`` classes.
214+
215+
- Removes the following methods for use with ``geoHaystack`` indexes:
216+
217+
- ``Indexes.geoHaystack()``
218+
- ``IndexOptions.getBucketSize()``
219+
- ``IndexOptions.bucketSize()``
220+
221+
Instead, you can use the ``$geoNear`` aggregation pipeline stage or a geospatial
222+
query operator on a 2d index. For more information, see the
223+
:manual:`Geospatial Queries </geospatial-queries>` page in the {+mdb-server+} manual.
224+
225+
- Removes the ``oplogReplay`` option from find operations. The
226+
following ``oplogReplay`` methods are no longer available:
227+
228+
- ``DBCursor.oplogReplay()``
229+
- ``DBCollectionFindOptions.isOplogReplay()``
230+
- ``DBCollectionFindOptions.oplogReplay()``
231+
- ``FindPublisher.oplogReplay()``
232+
- ``FindIterable.oplogReplay()``
233+
234+
- Removes the following ``Exception`` constructors:
235+
236+
- ``MongoBulkWriteException(BulkWriteResult, List<BulkWriteError>, WriteConcernError, ServerAddress)``
237+
- ``MongoCursorNotFoundException(long, ServerAddress)``
238+
- ``MongoQueryException(ServerAddress, int, String)``
239+
- ``MongoQueryException(ServerAddress, int, String, String)``
240+
- ``MongoQueryException(MongoCommandException)``
241+
242+
- Removes the following overloads for the ``BulkWriteResult.acknowledged()`` method:
243+
244+
- ``acknowledged(Type, int, List<BulkWriteUpsert>)``
245+
- ``acknowledged(Type, int, Integer, List<BulkWriteUpsert>)``
246+
- ``acknowledged(int, int, int, Integer, List<BulkWriteUpsert>)``
247+
248+
- Removes the following ``ChangeStreamDocument`` constructors:
249+
250+
- ``ChangeStreamDocument(String, BsonDocument, BsonDocument, BsonDocument,
251+
TDocument, TDocument, BsonDocument, ...)``
252+
- ``ChangeStreamDocument(String, BsonDocument, BsonDocument, BsonDocument,
253+
TDocument, BsonDocument, BsonTimestamp, ...)``
254+
- ``ChangeStreamDocument(OperationType, BsonDocument, BsonDocument, BsonDocument,
255+
TDocument, BsonDocument, BsonTimestamp, ...)``
256+
257+
- Removes the following constructors for events:
258+
259+
- ``CommandEvent(RequestContext, int, ConnectionDescription, String)``
260+
- ``CommandEvent(int, ConnectionDescription, String)``
261+
- ``CommandEvent(RequestContext, long, int, ConnectionDescription, String)``
262+
- ``CommandFailedEvent(RequestContext, int, ConnectionDescription, String,
263+
long, Throwable)``
264+
- ``CommandFailedEvent(int, ConnectionDescription, String, long, Throwable)``
265+
- ``CommandStartedEvent(RequestContext, int, ConnectionDescription, String,
266+
String, BsonDocument)``
267+
- ``CommandStartedEvent(int, ConnectionDescription, String, String, BsonDocument)``
268+
- ``CommandSucceededEvent(RequestContext, int, ConnectionDescription, String,
269+
BsonDocument, long)``
270+
- ``CommandSucceededEvent(int, ConnectionDescription, String, BsonDocument, long)``
271+
- ``ConnectionCheckedInEvent(ConnectionId)``
272+
- ``ConnectionCheckedOutEvent(ConnectionId, long)``
273+
- ``ConnectionCheckedOutEvent(ConnectionId)``
274+
- ``ConnectionCheckOutFailedEvent(ServerId, long, Reason)``
275+
- ``ConnectionCheckOutFailedEvent(ServerId, Reason)``
276+
- ``ConnectionCheckOutStartedEvent(ServerId)``
277+
- ``ConnectionReadyEvent(ConnectionId)``
278+
- ``ServerHeartbeatFailedEvent(ConnectionId, long, Throwable)``
279+
- ``ServerHeartbeatSucceededEvent(ConnectionId, BsonDocument, long)``
280+
281+
- Removes the ``errorLabels`` option from the ``WriteConcernError``
282+
class. This includes the ``addLabel()`` and ``getErrorLabels()`` methods and the
283+
constructor that includes an ``errorLabels`` parameter. Instead, you can use
284+
the error labels included in the ``MongoException`` object that contains the
285+
``WriteConcernError``.
286+
287+
- Removes the following classes from the
288+
``com.mongodb.event`` package:
289+
290+
- ``ConnectionAddedEvent``
291+
- ``ConnectionPoolOpenedEvent``
292+
- ``ConnectionRemovedEvent``
293+
- ``ClusterListenerAdapter``
294+
- ``ConnectionPoolListenerAdapter``
295+
- ``ServerListenerAdapter``
296+
- ``ServerMonitorListenerAdapter``
297+
298+
The driver also removes the following related methods from the
299+
``ConnectionPoolListener`` interface:
300+
301+
- ``connectionAdded()``
302+
- ``connectionPoolOpened()``
303+
- ``connectionRemoved()``
304+
305+
For more information about the ``com.mongodb.event`` package, see the
306+
`API documentation. <{+core-api+}/event/package-summary.html>`__
307+
308+
.. _kotlin-sync-breaking-changes-v5.0-list-collections:
309+
310+
- Adds the ``authorizedCollection`` option for the ``listCollections`` command.
311+
This introduces a breaking binary change in the ``MongoDatabase.listCollectionNames()``
312+
method. This change does not require any changes to source code, but you must
313+
recompile any code that uses this method.
314+
315+
- Removes the following methods and types related to the
316+
`Stream
317+
<https://mongodb.github.io/mongo-java-driver/4.11/apidocs/mongodb-driver-core/com/mongodb/connection/Stream.html>`__
318+
interface:
319+
320+
- ``MongoClientSettings.Builder.streamFactoryFactory()`` method.
321+
Use the ``MongoClientSettings.Builder.transportSettings()`` method instead.
322+
- ``MongoClientSettings.getStreamFactoryFactory()`` method.
323+
Use the ``MongoClientSettings.getTransportSettings()`` method instead.
324+
- ``NettyStreamFactoryFactory`` class.
325+
Instead, call the ``TransportSettings.nettyBuilder()`` method to create
326+
a ``NettyTransportSettings`` object. Then, call the ``MongoClientSettings.Builder.transportSettings()``
327+
method to apply the settings.
328+
- ``NettyStreamFactory`` class.
329+
- ``AsynchronousSocketChannelStreamFactory`` class.
330+
- ``AsynchronousSocketChannelStreamFactoryFactory`` class.
331+
- ``BufferProvider`` interface.
332+
- ``SocketStreamFactory`` class.
333+
- ``Stream`` interface.
334+
- ``StreamFactory`` interface.
335+
- ``StreamFactoryFactory`` interface.
336+
- ``TlsChannelStreamFactoryFactory`` class.
337+
338+
.. tip::
339+
340+
To view breaking changes for earlier driver versions, see the
341+
:github:`Release Notes <mongodb/mongo-java-driver/releases>` in the
342+
``mongo-java-driver`` GitHub repository.
343+
344+
.. _kotlin-sync-server-release-changes:
345+
346+
Server Release Compatibility Changes
347+
------------------------------------
348+
349+
A server release compatibility change is a modification
350+
to the {+driver-short+} that discontinues support for a set of
351+
{+mdb-server+} versions.
352+
353+
The driver discontinues support for a {+mdb-server+} version after it reaches
354+
end-of-life (EOL).
355+
356+
To learn more about the MongoDB support for EOL products,
357+
see the `Legacy Support Policy <https://www.mongodb.com/support-policy/legacy>`__.
358+
359+
.. _kotlin-sync-server-8.1-incompatibility:
360+
361+
Server Version 8.1 Support Changes
362+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
363+
364+
You cannot use a 3.x version of the {+driver-short+} to connect to a
365+
MongoDB deployment running {+mdb-server+} v8.1 or later. Starting in {+mdb-server+} v8.1,
366+
the ``buildinfo`` command requires authentication, causing an
367+
incompatibility with the v3.x driver.
368+
369+
.. _kotlin-sync-server-release-change-v5.5:
370+
371+
Driver Version 5.5 Server Support Changes
372+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
373+
374+
The v5.5 driver drops support for {+mdb-server+} 4.0.
375+
To use the v5.5 driver, you must connect to {+mdb-server+} 4.2 or later. To
376+
learn how to upgrade your {+mdb-server+} deployment, see
377+
:manual:`Release Notes </release-notes>` in the {+mdb-server+} manual.
378+
379+
.. _kotlin-sync-server-release-change-v5.2:
380+
381+
Driver Version 5.2 Server Support Changes
382+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
383+
384+
The v5.2 driver drops support for {+mdb-server+} 3.6.
385+
To use the v5.2 driver, you must connect to {+mdb-server+} 4.0 or later. To
386+
learn how to upgrade your {+mdb-server+} deployment, see
387+
:manual:`Release Notes </release-notes>` in the {+mdb-server+} manual.
388+
389+
.. _kotlin-sync-server-release-change-v4.8:
390+
391+
Driver Version 4.8 Server Support Changes
392+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
393+
394+
The v4.8 driver drops support for {+mdb-server+} 3.4 and earlier.
395+
To use the v4.8 driver, you must connect to {+mdb-server+} 3.6 or later. To learn
396+
how to upgrade your {+mdb-server+} deployment, see :manual:`Release
397+
Notes </release-notes>` in the {+mdb-server+} manual.

0 commit comments

Comments
 (0)