Docs Menu

Docs HomeKotlin Coroutine


On this page

  • Why Am I Having Problems Connecting to a MongoDB Instance?
  • How is the Kotlin Driver Different from KMongo?
  • What is the Difference Between the Kotlin Driver and the Kotlin SDK?
  • How Does Connection Pooling Work in the Kotlin Driver?

On this page, you can find frequently asked questions and their corresponding answers.


If you can't find an answer to your question on this page, see the Issues & Help page for information on how to report issues.

If you have trouble connecting to a MongoDB deployment, see the Connection Troubleshooting Guide for possible solutions.

The Kotlin driver is the official MongoDB driver for Kotlin. It is developed by the MongoDB team and provides a native API for Kotlin applications to connect to MongoDB and work with data. It is implemented by wrapping the MongoDB Java driver.

KMongo is a popular community-developed library for working with MongoDB from Kotlin applications. It is a wrapper around the Java driver that was created prior to the creation of the official Kotlin driver to serve the needs of the Kotlin community.


As of July 2023, KMongo has been marked as deprecated.

The Kotlin driver was developed in collaboration with the creator of KMongo, Julien Buret, to give users an officially-supported driver.

The official Kotlin driver and KMongo have generally similar APIs. Notable similarities between the Kotlin driver and KMongo include:

  • Support for synchronous and coroutine-based operations

  • Support using data classes to represent MongoDB documents

  • Support KotlinX serialization

  • Support for MongoDB CRUD APIs and aggregation

Although the official Kotlin driver and KMongo are similar, there are some key differences:

  • The official driver does not have built-in support for reactor, rxjava2, Jackson, or GSON.

  • The official driver does not support MongoDB shell commands.

  • The official driver supports type-safe queries with the Builders API, whereas KMongo uses infix functions and property references for type-safe queries.

For more detailed information, see Migrate from KMongo.

MongoDB supports both mobile and server-side development in Kotlin. If you are developing a mobile application for Android or Kotlin Multiplatform (KMP), you can use the MongoDB Atlas Device Kotlin SDK to access Atlas App Services and to manage your Realm data.

The Kotlin driver supports server-side development by providing a complete library for building idiomatic Kotlin applications. You can learn how to develop asynchronous applications in this documentation for the Kotlin Coroutine Driver, or you can view the Kotlin Sync Driver documentation to learn more about synchronous programming.

Every MongoClient instance has a built-in connection pool for each server in your MongoDB topology. Connection pools open sockets on demand to support concurrent MongoDB operations in your multi-threaded application.

The maximum size of each connection pool is set by the maxPoolSize option, which defaults to 100. If the number of in-use connections to a server reaches the value of maxPoolSize, the next request to that server will wait until a connection becomes available.

Each MongoClient instance opens two additional sockets per server in your MongoDB topology for monitoring the server's state.

For example, a client connected to a 3-node replica set opens 6 monitoring sockets. It also opens as many sockets as needed to support an application's threads on each server, up to the value of maxPoolSize. If maxPoolSize is 100 and the application only uses the primary (the default), then only the primary connection pool grows and there can be at most 106 total connections. If the application uses a read preference to query the secondary nodes, their pools also grow and there can be 306 total connections.

Additionally, connection pools are rate-limited such that each connection pool can only create, at maximum, the value of maxConnecting connections in parallel at any time. Any additional thread stops waiting in the following cases:

  • One of the existing threads finishes creating a connection, or an existing connection is checked back into the pool.

  • The driver's ability to reuse existing connections improves due to rate-limits on connection creation.

You can set the minimum number of concurrent connections to each server with the minPoolSize option, which defaults to 0. The connection pool will be initialized with this number of sockets. If sockets are closed due to any network errors, causing the total number of sockets (both in use and idle) to drop below the minimum, more sockets are opened until the minimum is reached.

You can set the maximum number of milliseconds that a connection can remain idle in the pool before being removed and replaced with the maxIdleTimeMS option, which defaults to 0 (no limit).

The following default configuration for a MongoClient works for most applications:

val client = MongoClient("<connection string>")

Create a client once for each process, and reuse it for all operations. It is a common mistake to create a new client for each request, which is very inefficient.

To support high numbers of concurrent MongoDB operations within one process, you can increase maxPoolSize. Once the pool reaches its maximum size, additional threads wait for sockets to become available.

The driver does not limit the number of threads that can wait for sockets to become available, and it is the application's responsibility to limit the size of its pool to bound queuing during a load spike. Threads wait for the amount of time specified in the waitQueueTimeoutMS option, which defaults to 120000 (120 seconds).

A thread that waits more than the length of time defined by waitQueueTimeoutMS for a socket raises a connection error. Use this option if it is more important to bound the duration of operations during a load spike than it is to complete every operation.

When MongoClient.close() is called by any thread, the driver closes all idle sockets and closes all sockets that are in use as they are returned to the pool.

To learn more about connecting to MongoDB, see the Connection Guide.

←  API DocumentationConnection Troubleshooting →