From 2a875e8a9d12fa303583529ce48eb8eb210b90d4 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 25 Jul 2025 11:11:22 -0400 Subject: [PATCH 1/3] DOCSP-51349: Upgrade guide --- source/reference/upgrade.txt | 389 ++++++++++++++++++++++++++++++++++- 1 file changed, 388 insertions(+), 1 deletion(-) diff --git a/source/reference/upgrade.txt b/source/reference/upgrade.txt index d1c97a35..33098b6d 100644 --- a/source/reference/upgrade.txt +++ b/source/reference/upgrade.txt @@ -8,4 +8,391 @@ Upgrade Driver Versions :local: :backlinks: none :depth: 1 - :class: singlecol \ No newline at end of file + :class: singlecol + +.. meta:: + :keywords: backwards compatibility, update + +Overview +-------- + +In this section, you can identify the changes you must +make to your application to upgrade your driver to a new version. + +Before you upgrade, perform the following actions: + +- Ensure the new driver version is compatible with the {+mdb-server+} versions + your application connects to and the Java Runtime Environment (JRE) your + application runs on. To view compatibility information, see the + :ref:`Compatibility ` page. +- Address any breaking changes between the current version of the driver + your application is using and your planned upgrade version in the + :ref:`Breaking Changes ` section. To learn + more about {+mdb-server+} release compatibility changes, see the + :ref:`` section. + +.. tip:: + + To minimize the number of changes your application might require when + you upgrade driver versions in the future, use the + :ref:`{+stable-api+}. ` + +.. _kotlin-sync-breaking-changes: + +Breaking Changes +---------------- + +A breaking change is a modification in a convention or behavior in +a specific version of the driver that might prevent your application from +working properly if not addressed before upgrading. + +The breaking changes in this section are categorized by the driver version that +introduced them. When upgrading driver versions, address all the breaking +changes between the current and upgrade versions. For example, if you +are upgrading the driver from v4.0 to v4.7, address all breaking changes from +the version after v4.0 including any listed for v4.7. + +.. _kotlin-sync-breaking-changes-v5.5: + +Version 5.5 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- The driver is no longer compatible with {+mdb-server+} version + 4.0. To learn more about this change, see the + :ref:`kotlin-sync-server-release-change-v5.5` section. + +.. _kotlin-sync-breaking-changes-v5.2: + +Version 5.2 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This driver version introduces the following breaking changes: + +- Drops support for {+mdb-server+} v3.6. To learn more about this change, + see the :ref:`` section. + +- Revises the `mongodb-crypt `__ + dependency versioning to match the versioning for the JVM drivers. Future versions of + ``mongodb-crypt`` will be released alongside the driver and will share the same version number. + You must upgrade your ``mongodb-crypt`` dependency to v5.2.0 when upgrading your driver for + this release. + +.. _kotlin-sync-breaking-changes-v5.1: + +Version 5.1 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This driver version introduces the following breaking changes: + +- When using the ``MONGODB-OIDC`` authentication mechanism, you must + not include comma characters in the ``authMechanismProperties`` connection + string value. + +.. _kotlin-sync-breaking-changes-v5.0: + +Version 5.0 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This driver version introduces the following breaking changes: + +- Introduces the following changes to the ``ConnectionId`` class: + + - The ``ConnectionId`` constructor now accepts a value of type ``long`` as its second + parameter instead of type ``int``. Similarly, the constructor now accepts a value of + type ``Long`` as its third parameter instead of type ``Integer``. Because this change breaks + binary compatibility, recompile any existing code that calls the + ``ConnectionId`` constructor. + + - The ``withServerValue()`` method now accepts a parameter of type ``long`` rather than + type ``int``. Because this change breaks binary compatibility, you must recompile any code + that calls the ``withServerValue()`` method. + + - The ``getServerValue()`` method now returns a value of type ``Long`` instead of type + ``Integer``. Similarly, the ``getLocalValue()`` method returns a value of type + ``long`` instead of type ``int``. Because this change breaks both binary and source + compatibility, update any source code that uses these methods and rebuild your binary. + +- Replaces the following record annotations from the + ``org.bson.codecs.record.annotations`` package with + annotations of the same name from the ``org.bson.codecs.pojo.annotations`` package: + + - ``BsonId`` + - ``BsonProperty`` + - ``BsonRepresentation`` + +- Changes the data type of the ``connectTimeout`` timeout duration parameter for the + ``SocketSettings.Builder.connectTimeout()`` and + ``SocketSettings.Builder.readTimeout()`` methods. The data type of this + parameter is now ``long`` instead of ``int``. + + In earlier versions, this parameter is of type ``int`` for both methods. This + change breaks binary compatibility and requires recompiling, but does not + require code changes. + +- Removes the ``Filters.eqFull()`` method, released + exclusively in ``Beta``, which allowed you + to construct an equality filter when performing a vector search. + Instead, you can use the ``Filters.eq()`` method when instantiating a + ``VectorSearchOptions`` type, as shown in the following code: + + .. code-block:: kotlin + + val opts = vectorSearchOptions().filter(eq("x", 8)) + +- Changes how ``ClusterSettings`` computes the ``ClusterConnectionMode`` + setting, making it more consistent by using the specified + replica set name, regardless of how it is configured. Previously, the driver + considered the replica set name only if it was set in the connection string. + + For example, the following two code samples both return the value + ``ClusterConnectionMode.MULTIPLE``. Previously, the second example returned + ``ClusterConnectionMode.SINGLE``. + + .. code-block:: kotlin + + ClusterSettings.builder() + .applyConnectionString(ConnectionString("mongodb://127.0.0.1:27017/?replicaSet=replset")) + .build() + .mode + + .. code-block:: kotlin + + ClusterSettings.builder() + .hosts(listOf(ServerAddress("127.0.0.1", 27017))) + .requiredReplicaSetName("replset") + .build() + .mode + +- ``BsonDecimal128`` values respond to method calls in the same way as + ``Decimal128`` values. ``BsonDecimal128.isNumber()`` now returns ``true`` and + ``BsonDecimal128.asNumber()`` returns the equivalent ``BsonNumber``. + +- Removes the `ServerAddress <{+core-api+}/ServerAddress.html>`__ + methods ``getSocketAddress()`` and ``getSocketAddresses()``. + + Instead of ``getSocketAddress()``, use the ``getByName()`` instance + method of ``java.net.InetAddress``. + + Instead of ``getSocketAddresses()``, use the ``getAllByName()`` instance + method of ``java.net.InetAddress``. + +- Removes the `UnixServerAddress <{+core-api+}/UnixServerAddress.html>`__ + methods ``getSocketAddress()`` and ``getUnixSocketAddress()``. + + Instead of ``getSocketAddress()``, use the ``getByName()`` instance + method of ``java.net.InetAddress``. + + Instead of ``getUnixSocketAddress()``, construct an instance of + ``jnr.unixsocket.UnixSocketAddress``. Pass the full path of the UNIX + socket file to the constructor. By default, MongoDB creates a UNIX + socket file located at ``"/tmp/mongodb-27017.sock"``. To learn more + about the ``UnixSocketAddress`` class, see the `UnixSocketAddress `__ API documentation. + +- Removes the ``Parameterizable`` interface. Instead of + implementing this interface on a custom ``Codec`` type, + override the ``CodecProvider.get()`` method on the + codec's ``CodecProvider`` if the codec is intended for a parameterized + type. + +- Removes the ``isSlaveOk()`` method from the + ``ReadPreference`` and ``TaggableReadPreference`` classes. To check whether a read preference allows + reading from a secondary member of a replica set, use the ``isSecondaryOk()`` methods from + these classes instead. + +- Removes the ``DBCollection.getStats()`` and ``DBCollection.isCapped()`` + helper methods for the ``collStats`` command. Instead of these methods, you can use the + ``$collStats`` aggregation pipeline stage. + +- Removes the ``MapCodec`` and ``IterableCodec`` classes. + Instead of ``MapCodec``, use ``MapCodecProvider``. Instead of ``IterableCodec``, + use ``CollectionCodecProvider``, or ``IterableCodecProvider`` for ``Iterable`` + types that aren't ``Collection`` types. + +- Removes the ``sharded()`` and ``nonAtomic()`` methods from the + ``MapReducePublisher`` and ``MapReduceIterable`` classes. + +- Removes the following methods for use with ``geoHaystack`` indexes: + + - ``Indexes.geoHaystack()`` + - ``IndexOptions.getBucketSize()`` + - ``IndexOptions.bucketSize()`` + + Instead, you can use the ``$geoNear`` aggregation pipeline stage or a geospatial + query operator on a 2d index. For more information, see the + :manual:`Geospatial Queries ` page in the {+mdb-server+} manual. + +- Removes the ``oplogReplay`` option from find operations. The + following ``oplogReplay`` methods are no longer available: + + - ``DBCursor.oplogReplay()`` + - ``DBCollectionFindOptions.isOplogReplay()`` + - ``DBCollectionFindOptions.oplogReplay()`` + - ``FindPublisher.oplogReplay()`` + - ``FindIterable.oplogReplay()`` + +- Removes the following ``Exception`` constructors: + + - ``MongoBulkWriteException(BulkWriteResult, List, WriteConcernError, ServerAddress)`` + - ``MongoCursorNotFoundException(long, ServerAddress)`` + - ``MongoQueryException(ServerAddress, int, String)`` + - ``MongoQueryException(ServerAddress, int, String, String)`` + - ``MongoQueryException(MongoCommandException)`` + +- Removes the following overloads for the ``BulkWriteResult.acknowledged()`` method: + + - ``acknowledged(Type, int, List)`` + - ``acknowledged(Type, int, Integer, List)`` + - ``acknowledged(int, int, int, Integer, List)`` + +- Removes the following ``ChangeStreamDocument`` constructors: + + - ``ChangeStreamDocument(String, BsonDocument, BsonDocument, BsonDocument, + TDocument, TDocument, BsonDocument, ...)`` + - ``ChangeStreamDocument(String, BsonDocument, BsonDocument, BsonDocument, + TDocument, BsonDocument, BsonTimestamp, ...)`` + - ``ChangeStreamDocument(OperationType, BsonDocument, BsonDocument, BsonDocument, + TDocument, BsonDocument, BsonTimestamp, ...)`` + +- Removes the following constructors for events: + + - ``CommandEvent(RequestContext, int, ConnectionDescription, String)`` + - ``CommandEvent(int, ConnectionDescription, String)`` + - ``CommandEvent(RequestContext, long, int, ConnectionDescription, String)`` + - ``CommandFailedEvent(RequestContext, int, ConnectionDescription, String, + long, Throwable)`` + - ``CommandFailedEvent(int, ConnectionDescription, String, long, Throwable)`` + - ``CommandStartedEvent(RequestContext, int, ConnectionDescription, String, + String, BsonDocument)`` + - ``CommandStartedEvent(int, ConnectionDescription, String, String, BsonDocument)`` + - ``CommandSucceededEvent(RequestContext, int, ConnectionDescription, String, + BsonDocument, long)`` + - ``CommandSucceededEvent(int, ConnectionDescription, String, BsonDocument, long)`` + - ``ConnectionCheckedInEvent(ConnectionId)`` + - ``ConnectionCheckedOutEvent(ConnectionId, long)`` + - ``ConnectionCheckedOutEvent(ConnectionId)`` + - ``ConnectionCheckOutFailedEvent(ServerId, long, Reason)`` + - ``ConnectionCheckOutFailedEvent(ServerId, Reason)`` + - ``ConnectionCheckOutStartedEvent(ServerId)`` + - ``ConnectionReadyEvent(ConnectionId)`` + - ``ServerHeartbeatFailedEvent(ConnectionId, long, Throwable)`` + - ``ServerHeartbeatSucceededEvent(ConnectionId, BsonDocument, long)`` + +- Removes the ``errorLabels`` option from the ``WriteConcernError`` + class. This includes the ``addLabel()`` and ``getErrorLabels()`` methods and the + constructor that includes an ``errorLabels`` parameter. Instead, you can use + the error labels included in the ``MongoException`` object that contains the + ``WriteConcernError``. + +- Removes the following classes from the + ``com.mongodb.event`` package: + + - ``ConnectionAddedEvent`` + - ``ConnectionPoolOpenedEvent`` + - ``ConnectionRemovedEvent`` + - ``ClusterListenerAdapter`` + - ``ConnectionPoolListenerAdapter`` + - ``ServerListenerAdapter`` + - ``ServerMonitorListenerAdapter`` + + The driver also removes the following related methods from the + ``ConnectionPoolListener`` interface: + + - ``connectionAdded()`` + - ``connectionPoolOpened()`` + - ``connectionRemoved()`` + + For more information about the ``com.mongodb.event`` package, see the + `API documentation. <{+core-api+}/event/package-summary.html>`__ + +.. _kotlin-sync-breaking-changes-v5.0-list-collections: + +- Adds the ``authorizedCollection`` option for the ``listCollections`` command. + This introduces a breaking binary change in the ``MongoDatabase.listCollectionNames()`` + method. This change does not require any changes to source code, but you must + recompile any code that uses this method. + +- Removes the following methods and types related to the + `Stream + `__ + interface: + + - ``MongoClientSettings.Builder.streamFactoryFactory()`` method. + Use the ``MongoClientSettings.Builder.transportSettings()`` method instead. + - ``MongoClientSettings.getStreamFactoryFactory()`` method. + Use the ``MongoClientSettings.getTransportSettings()`` method instead. + - ``NettyStreamFactoryFactory`` class. + Instead, call the ``TransportSettings.nettyBuilder()`` method to create + a ``NettyTransportSettings`` object. Then, call the ``MongoClientSettings.Builder.transportSettings()`` + method to apply the settings. + - ``NettyStreamFactory`` class. + - ``AsynchronousSocketChannelStreamFactory`` class. + - ``AsynchronousSocketChannelStreamFactoryFactory`` class. + - ``BufferProvider`` interface. + - ``SocketStreamFactory`` class. + - ``Stream`` interface. + - ``StreamFactory`` interface. + - ``StreamFactoryFactory`` interface. + - ``TlsChannelStreamFactoryFactory`` class. + +.. tip:: + + To view breaking changes for earlier driver versions, see the + :github:`Release Notes ` in the + ``mongo-java-driver`` GitHub repository. + +.. _kotlin-sync-server-release-changes: + +Server Release Compatibility Changes +------------------------------------ + +A server release compatibility change is a modification +to the {+driver-short+} that discontinues support for a set of +{+mdb-server+} versions. + +The driver discontinues support for a {+mdb-server+} version after it reaches +end-of-life (EOL). + +To learn more about the MongoDB support for EOL products, +see the `Legacy Support Policy `__. + +.. _kotlin-sync-server-release-change-v5.5: + +Driver Version 5.5 Server Support Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The v5.5 driver drops support for {+mdb-server+} 4.0. +To use the v5.5 driver, you must connect to {+mdb-server+} 4.2 or later. To +learn how to upgrade your {+mdb-server+} deployment, see +:manual:`Release Notes ` in the {+mdb-server+} manual. + +.. _kotlin-sync-server-8.1-incompatibility: + +Server Version 8.1 Support Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You cannot use a 3.x version of the {+driver-short+} to connect to a +MongoDB deployment running {+mdb-server+} v8.1. Starting in {+mdb-server+} v8.1, +the ``buildinfo`` command requires authentication, causing an +incompatibility with the v3.x driver. + +.. _kotlin-sync-server-release-change-v5.2: + +Driver Version 5.2 Server Support Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The v5.2 driver drops support for {+mdb-server+} 3.6. +To use the v5.2 driver, you must connect to {+mdb-server+} 4.0 or later. To +learn how to upgrade your {+mdb-server+} deployment, see +:manual:`Release Notes ` in the {+mdb-server+} manual. + +.. _kotlin-sync-server-release-change-v4.8: + +Driver Version 4.8 Server Support Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The v4.8 driver drops support for {+mdb-server+} 3.4 and earlier. +To use the v4.8 driver, you must connect to {+mdb-server+} 3.6 or later. To learn +how to upgrade your {+mdb-server+} deployment, see :manual:`Release +Notes ` in the {+mdb-server+} manual. +how to upgrade your {+mdb-server+} deployment, see :manual:`Release +Notes ` in the {+mdb-server+} manual. From cf499f493c172191f6c765c5cf15696c1c0fdb51 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 25 Jul 2025 11:22:59 -0400 Subject: [PATCH 2/3] edits --- source/reference/upgrade.txt | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/source/reference/upgrade.txt b/source/reference/upgrade.txt index 33098b6d..824b8992 100644 --- a/source/reference/upgrade.txt +++ b/source/reference/upgrade.txt @@ -49,8 +49,8 @@ working properly if not addressed before upgrading. The breaking changes in this section are categorized by the driver version that introduced them. When upgrading driver versions, address all the breaking changes between the current and upgrade versions. For example, if you -are upgrading the driver from v4.0 to v4.7, address all breaking changes from -the version after v4.0 including any listed for v4.7. +are upgrading the driver from v5.0 to v5.5, address all breaking changes from +the version after v5.0 including any listed for v5.5. .. _kotlin-sync-breaking-changes-v5.5: @@ -337,7 +337,7 @@ This driver version introduces the following breaking changes: .. tip:: To view breaking changes for earlier driver versions, see the - :github:`Release Notes ` in the + :github:`Release Notes ` in the ``mongo-java-driver`` GitHub repository. .. _kotlin-sync-server-release-changes: @@ -355,16 +355,6 @@ end-of-life (EOL). To learn more about the MongoDB support for EOL products, see the `Legacy Support Policy `__. -.. _kotlin-sync-server-release-change-v5.5: - -Driver Version 5.5 Server Support Changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The v5.5 driver drops support for {+mdb-server+} 4.0. -To use the v5.5 driver, you must connect to {+mdb-server+} 4.2 or later. To -learn how to upgrade your {+mdb-server+} deployment, see -:manual:`Release Notes ` in the {+mdb-server+} manual. - .. _kotlin-sync-server-8.1-incompatibility: Server Version 8.1 Support Changes @@ -375,6 +365,16 @@ MongoDB deployment running {+mdb-server+} v8.1. Starting in {+mdb-server+} v8.1, the ``buildinfo`` command requires authentication, causing an incompatibility with the v3.x driver. +.. _kotlin-sync-server-release-change-v5.5: + +Driver Version 5.5 Server Support Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The v5.5 driver drops support for {+mdb-server+} 4.0. +To use the v5.5 driver, you must connect to {+mdb-server+} 4.2 or later. To +learn how to upgrade your {+mdb-server+} deployment, see +:manual:`Release Notes ` in the {+mdb-server+} manual. + .. _kotlin-sync-server-release-change-v5.2: Driver Version 5.2 Server Support Changes @@ -394,5 +394,3 @@ The v4.8 driver drops support for {+mdb-server+} 3.4 and earlier. To use the v4.8 driver, you must connect to {+mdb-server+} 3.6 or later. To learn how to upgrade your {+mdb-server+} deployment, see :manual:`Release Notes ` in the {+mdb-server+} manual. -how to upgrade your {+mdb-server+} deployment, see :manual:`Release -Notes ` in the {+mdb-server+} manual. From f6e669100072405605c323c11d1c66e7c61fc753 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 25 Jul 2025 13:42:16 -0400 Subject: [PATCH 3/3] edits --- source/reference/upgrade.txt | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/source/reference/upgrade.txt b/source/reference/upgrade.txt index 824b8992..2c8d8ae1 100644 --- a/source/reference/upgrade.txt +++ b/source/reference/upgrade.txt @@ -50,7 +50,7 @@ The breaking changes in this section are categorized by the driver version that introduced them. When upgrading driver versions, address all the breaking changes between the current and upgrade versions. For example, if you are upgrading the driver from v5.0 to v5.5, address all breaking changes from -the version after v5.0 including any listed for v5.5. +the versions after v5.0 including any listed for v5.5. .. _kotlin-sync-breaking-changes-v5.5: @@ -73,7 +73,7 @@ This driver version introduces the following breaking changes: - Revises the `mongodb-crypt `__ dependency versioning to match the versioning for the JVM drivers. Future versions of - ``mongodb-crypt`` will be released alongside the driver and will share the same version number. + ``mongodb-crypt`` are released alongside the driver and share the same version number. You must upgrade your ``mongodb-crypt`` dependency to v5.2.0 when upgrading your driver for this release. @@ -84,9 +84,10 @@ Version 5.1 Breaking Changes This driver version introduces the following breaking changes: -- When using the ``MONGODB-OIDC`` authentication mechanism, you must - not include comma characters in the ``authMechanismProperties`` connection - string value. +- When using the ``MONGODB-OIDC`` authentication mechanism, you cannot + include comma characters in the ``authMechanismProperties`` connection + string value. If your ``authMechanismProperties`` value includes a comma, + pass the value as a connection option in a ``MongoClientSettings`` instance. .. _kotlin-sync-breaking-changes-v5.0: @@ -361,7 +362,7 @@ Server Version 8.1 Support Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You cannot use a 3.x version of the {+driver-short+} to connect to a -MongoDB deployment running {+mdb-server+} v8.1. Starting in {+mdb-server+} v8.1, +MongoDB deployment running {+mdb-server+} v8.1 or later. Starting in {+mdb-server+} v8.1, the ``buildinfo`` command requires authentication, causing an incompatibility with the v3.x driver.