diff --git a/source/reference/upgrade.txt b/source/reference/upgrade.txt index d1c97a35..2c8d8ae1 100644 --- a/source/reference/upgrade.txt +++ b/source/reference/upgrade.txt @@ -8,4 +8,390 @@ 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 v5.0 to v5.5, address all breaking changes from +the versions after v5.0 including any listed for v5.5. + +.. _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`` 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. + +.. _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 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: + +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-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 or later. 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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.