Kotlin Driver Quick Start

Install Kotlin

Make sure that your system has Kotlin installed and running on JDK 1.8 or later. For more information on getting started with Kotlin/JVM development, refer to Get started with Kotlin/JVM in the Kotlin language documentation.

Create the Project

This guide shows you how to add the MongoDB Kotlin driver dependencies by using Gradle or Maven. We recommend that you use an integrated development environment (IDE) such as IntelliJ IDEA or Eclipse IDE to configure Gradle or Maven to build and run your project.

If you are not using an IDE, see the Creating New Gradle Builds guide or the Building Maven guide for more information on how to set up your project.

Add MongoDB as a Dependency

If you are using Gradle to manage your packages, add the following entry to your build.gradle.kts dependencies list:

dependencies {
    implementation("org.mongodb:mongodb-driver-kotlin-coroutine:5.2.1")
}

If you are using Maven to manage your packages, add the following entry to your pom.xml dependencies list:

<dependencies>
    <dependency>
        <groupId>org.mongodb</groupId>
        <artifactId>mongodb-driver-kotlin-coroutine</artifactId>
        <version>5.2.1</version>
    </dependency>
</dependencies>

After you configure your dependencies, ensure that they are available to your project by running the dependency manager and refreshing the project in your IDE.

Add Serialization Library Dependencies

To enable the driver to convert between Kotlin objects and BSON, the data format for documents in MongoDB, you must also add one or both of the following serialization packages to your application:

• bson-kotlinx (Recommended)

• bson-kotlin

If you are using Gradle to manage your packages, add one of the following entries to your build.gradle.kts dependencies list:

implementation("org.mongodb:bson-kotlinx:5.2.1")
// OR
implementation("org.mongodb:bson-kotlin:5.2.1")

If you are using Maven to manage your packages, add one of the following entries to your pom.xml dependencies list:

<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>bson-kotlinx</artifactId>
    <version>5.2.1</version>
</dependency>
<!--OR-->
<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>bson-kotlin</artifactId>
    <version>5.2.1</version>
</dependency>

After you configure your dependencies, ensure that they are available to your project by running the dependency manager and refreshing the project in your IDE.

To learn more about these packages, see Kotlin Serialization.

Query Your MongoDB Cluster from Your Application

Next, create a file called QuickStartDataClassExample.kt in your project.

Copy the following sample code into the file and replace the value of the uri variable with your MongoDB Atlas connection string that you saved in the preceding step. Replace the "<password>" placeholder of your connection string with the password you set for your user that has atlasAdmin permissions:

import com.mongodb.client.model.Filters.eq
import com.mongodb.kotlin.client.coroutine.MongoClient
import io.github.cdimascio.dotenv.dotenv
import kotlinx.coroutines.flow.firstOrNull
import kotlinx.coroutines.runBlocking
// Create data class to represent a MongoDB document
data class Movie(val title: String, val year: Int, val cast: List<String>)
fun main() {
    // Replace the placeholder with your MongoDB deployment's connection string
    val uri = CONNECTION_STRING_URI_PLACEHOLDER
    val mongoClient = MongoClient.create(uri)
    val database = mongoClient.getDatabase("sample_mflix")
    // Get a collection of documents of type Movie
    val collection = database.getCollection<Movie>("movies")
    runBlocking {
        val doc = collection.find(eq("title", "Back to the Future")).firstOrNull()
        if (doc != null) {
            println(doc)
        } else {
            println("No matching documents found.")
        }
    }
    mongoClient.close()
}

When you run the main function, the application prints the details of a movie document that matches the query, as shown in the following output:

Movie(
   title=Back to the Future,
   year=1985,
   cast=[Michael J. Fox, Christopher Lloyd, Lea Thompson, Crispin Glover]
)

If you don't see any output or receive an error, check whether you included the proper connection string in your application. Also, confirm that you successfully loaded the sample dataset into your MongoDB Atlas cluster.

javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request

After completing this step, you have a working application that uses the Kotlin driver to connect to your MongoDB cluster, run a query on the sample data, and print out the result.

Working with the Document Class (Alternative)

The preceding section demonstrates how to run a query on a sample collection to retrieve data by using a Kotlin data class. This section shows how to use the Document class to store and retrieve data from MongoDB.

In a new file called QuickStartDocumentExample.kt, paste the following sample code to run a query on your sample dataset in MongoDB Atlas. Replace the value of the uri variable with your MongoDB Atlas connection string:

import com.mongodb.client.model.Filters.eq
import com.mongodb.kotlin.client.coroutine.MongoClient
import io.github.cdimascio.dotenv.dotenv
import kotlinx.coroutines.flow.firstOrNull
import kotlinx.coroutines.runBlocking
import org.bson.Document
fun main() {
    // Replace the placeholder with your MongoDB deployment's connection string
    val uri = CONNECTION_STRING_URI_PLACEHOLDER
    val mongoClient = MongoClient.create(uri)
    val database = mongoClient.getDatabase("sample_mflix")
    val collection = database.getCollection<Document>("movies")
    runBlocking {
        val doc = collection.find(eq("title", "Back to the Future")).firstOrNull()
        if (doc != null) {
            println(doc.toJson())
        } else {
            println("No matching documents found.")
        }
    }
    mongoClient.close()
}

When you run the main function, the application prints the details of a movie document that matches the query, as shown in the following output:

{
  _id: ...,
  plot: 'A young man is accidentally sent 30 years into the past...',
  genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ],
  ...
  title: 'Back to the Future',
  ...
}

If you don't see any output or receive an error, check whether you included the proper connection string in your application. Also, confirm that you successfully loaded the sample dataset into your MongoDB Atlas cluster.