Skip to content

DOCSP-51349: Upgrade guide #127

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 25, 2025
Merged

DOCSP-51349: Upgrade guide #127

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2a875e8
DOCSP-51349: Upgrade guide
norareidy Jul 25, 2025
cf499f4
edits
norareidy Jul 25, 2025
f6e6691
edits
norareidy Jul 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
388 changes: 387 additions & 1 deletion source/reference/upgrade.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,390 @@
:local:
:backlinks: none
:depth: 1
:class: singlecol
: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 <kotlin-sync-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 <kotlin-sync-breaking-changes>` section. To learn
more about {+mdb-server+} release compatibility changes, see the
:ref:`<kotlin-sync-server-release-changes>` 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-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:`<kotlin-sync-server-release-change-v5.2>` section.

- Revises the `mongodb-crypt <https://mvnrepository.com/artifact/org.mongodb/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"))

Check failure on line 155 in source/reference/upgrade.txt

View workflow job for this annotation

GitHub Actions / TDBX Vale rules 

[vale] reported by reviewdog 🐶
[MongoDB.Time24h2Digits] Show the hours, minutes, and seconds with two digits each, even if the leading digit is 0 ('1:27').

Raw Output:
{"message": "[MongoDB.Time24h2Digits] Show the hours, minutes, and seconds with two digits each, even if the leading digit is 0 ('1:27').", "location": {"path": "source/reference/upgrade.txt", "range": {"start": {"line": 155, "column": 69}}}, "severity": "ERROR"}
.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 <https://www.javadoc.io/doc/com.github.jnr/jnr-unixsocket/latest/jnr/unixsocket/UnixSocketAddress.html>`__ 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 </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<BulkWriteError>, 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<BulkWriteUpsert>)``
- ``acknowledged(Type, int, Integer, List<BulkWriteUpsert>)``
- ``acknowledged(int, int, int, Integer, List<BulkWriteUpsert>)``

- 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
<https://mongodb.github.io/mongo-java-driver/4.11/apidocs/mongodb-driver-core/com/mongodb/connection/Stream.html>`__
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 <mongodb/mongo-java-driver/releases>` in the
``mongo-java-driver`` GitHub repository.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be changed to the link for release notes in the mongo kotlin driver repo instead?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Kotlin driver folder is in the mongo-java-driver repo, i don't think there are specific Kotlin release notes (unless I'm missing something)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i see, thanks for checking in on that!


.. _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 <https://www.mongodb.com/support-policy/legacy>`__.

.. _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 </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 </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 </release-notes>` in the {+mdb-server+} manual.
Loading