Skip to content

Commit 2a875e8

Browse files
norareidynorareidy
committed
DOCSP-51349: Upgrade guide
1 parent 9084089 commit 2a875e8

File tree

1 file changed

+388
-1
lines changed

1 file changed

+388
-1
lines changed

‎source/reference/upgrade.txt

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

0 commit comments

Comments
 (0)