Upgrade Driver Versions

Version 5.5 Breaking Changes

• The driver is no longer compatible with MongoDB Server version 4.0. To learn more about this change, see the Driver Version 5.5 Server Support Changes section.

Version 5.2 Breaking Changes

This driver version introduces the following breaking changes:

• Drops support for MongoDB Server v3.6. To learn more about this change, see the Driver Version 5.2 Server Support Changes 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.

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.

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:

  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.

  ClusterSettings.builder()
      .applyConnectionString(ConnectionString("mongodb://127.0.0.1:27017/?replicaSet=replset"))
      .build()
      .mode

  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 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 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 Geospatial Queries page in the MongoDB 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.

• 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.

Server Version 8.1 Support Changes

You cannot use a 3.x version of the Kotlin Sync driver to connect to a MongoDB deployment running MongoDB Server v8.1 or later. Starting in MongoDB Server v8.1, the buildinfo command requires authentication, causing an incompatibility with the v3.x driver.

Driver Version 5.5 Server Support Changes

The v5.5 driver drops support for MongoDB Server 4.0. To use the v5.5 driver, you must connect to MongoDB Server 4.2 or later. To learn how to upgrade your MongoDB Server deployment, see Release Notes in the MongoDB Server manual.

Driver Version 5.2 Server Support Changes

The v5.2 driver drops support for MongoDB Server 3.6. To use the v5.2 driver, you must connect to MongoDB Server 4.0 or later. To learn how to upgrade your MongoDB Server deployment, see Release Notes in the MongoDB Server manual.

Driver Version 4.8 Server Support Changes

The v4.8 driver drops support for MongoDB Server 3.4 and earlier. To use the v4.8 driver, you must connect to MongoDB Server 3.6 or later. To learn how to upgrade your MongoDB Server deployment, see Release Notes in the MongoDB Server manual.