A newer version of this documentation is available.

Start Using the Kotlin SDK

tutorial

March 16, 2025

+ 12

A Kotlin application running on the JVM can use the Couchbase Kotlin SDK to access a Couchbase cluster.

The Couchbase Kotlin SDK is built on top of the same high performance I/O core as the Couchbase Java SDK. It provides idiomatic Kotlin features like default arguments, suspend functions, and tasteful DSLs.

Before You Start

You should know how to set up a new Kotlin project using Gradle (or using Maven). The SDK requires Kotlin 1.6.20 or later.
You will need Java 8 or later. We recommend running the latest Java LTS version with the highest patch version available.

Installing the SDK

All stable versions of the SDK are available on Maven Central.

You can use your favorite dependency management tool to include the SDK in your project.

Gradle (Kotlin)
Gradle (Groovy)
Maven

kotlin
Copy
implementation("com.couchbase.client:kotlin-client:1.2.0")

groovy
Copy
implementation "com.couchbase.client:kotlin-client:1.2.0"

xml
Copy
<dependency>
  <groupId>com.couchbase.client</groupId>
  <artifactId>kotlin-client</artifactId>
  <version>1.2.0</version>
</dependency>

Using a Snapshot Version (optional)

Couchbase publishes pre-release snapshot artifacts to the Sonatype OSS Snapshot Repository. If you wish to use a snapshot version, you’ll need to tell your build tool about this repository.

Gradle (Kotlin)
Gradle (Groovy)
Maven

build.gradle.kts

kotlin
Copy
repositories {
    mavenCentral()

    maven {
        url = uri("https://oss.sonatype.org/content/repositories/snapshots")
        mavenContent { snapshotsOnly() }
    }
}

build.gradle

groovy
Copy
repositories {
    mavenCentral()

    maven {
        url "https://oss.sonatype.org/content/repositories/snapshots"
        mavenContent { snapshotsOnly() }
    }
}

pom.xml

xml
Copy
<repositories>
  <repository>
    <id>sonatype-snapshots</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    <releases><enabled>false</enabled></releases>
    <snapshots><enabled>true</enabled></snapshots>
  </repository>
</repositories>

Hello Couchbase

Here’s an example that shows how to execute a SQL++ (formerly N1QL) query and get a document from the Key Value (KV) service.

Couchbase Capella
Local Couchbase Server

This version of the example assumes you are connecting to a Couchbase Capella free tier operational cluster, which has the travel-sample bucket installed by default.

(If you’re not using Couchbase Capella, click the Local Couchbase Server tab above.)

Before running the example:

Replace the address variable with the address of your Capella cluster.
Replace the username and password arguments with credentials for a cluster user that can read the travel-sample bucket.

kotlin
ViewCopy
import com.couchbase.client.kotlin.Cluster
import com.couchbase.client.kotlin.query.execute
import kotlinx.coroutines.runBlocking
import kotlin.time.Duration.Companion.seconds

fun main() {
    // Replace with your cluster address.
    val address = "--your-cluster--.cloud.couchbase.com"

    val cluster = Cluster.connect(
        connectionString = "couchbases://$address", (1)
        username = "username", // Replace with credentials
        password = "password", // of a database user account.
    )

    try {
        runBlocking {
            val collection = cluster
                .bucket("travel-sample")
                .waitUntilReady(10.seconds)
                .defaultCollection()

            // Execute a N1QL query
            val queryResult = cluster
                .query("select * from `travel-sample` limit 3")
                .execute()
            queryResult.rows.forEach { println(it) }
            println(queryResult.metadata)

            // Get a document from the K/V service
            val getResult = collection.get("airline_10")
            println(getResult)
            println(getResult.contentAs<Map<String, Any?>>())
        }
    } finally {
        runBlocking { cluster.disconnect() }
    }
}

1	For Capella, the connection string starts with `couchbases://` (note the final 's') to enable a secure connection with TLS.

This version of the example assumes you are connecting to a single-node Couchbase Server cluster running on your local computer.

Before running the example:

Install the travel-sample sample bucket.
Replace the username and password arguments with credentials for a cluster user that can read the travel-sample bucket. You can use the administrator credentials you chose when setting up the cluster.

kotlin
ViewCopy
import com.couchbase.client.kotlin.Cluster
import com.couchbase.client.kotlin.query.execute
import kotlinx.coroutines.runBlocking
import kotlin.time.Duration.Companion.seconds

fun main() {
    val cluster = Cluster.connect(
        connectionString = "couchbase://127.0.0.1",
        username = "username", // Replace with credentials
        password = "password", // of a database user account.
    )

    try {
        runBlocking {
            val collection = cluster
                .bucket("travel-sample")
                .waitUntilReady(10.seconds)
                .defaultCollection()

            // Execute a N1QL query
            val queryResult = cluster
                .query("select * from `travel-sample` limit 3")
                .execute()
            queryResult.rows.forEach { println(it) }
            println(queryResult.metadata)

            // Get a document from the K/V service
            val getResult = collection.get("airline_10")
            println(getResult)
            println(getResult.contentAs<Map<String, Any?>>())
        }
    } finally {
        runBlocking { cluster.disconnect() }
    }
}

Additional Resources

To see more documentation, select a chapter from the navigation sidebar on the left.

Join us on the Couchbase Discord server and the Couchbase Forum.

The Couchbase Playground has Kotlin examples you can edit and run in your web browser.

There are more code samples on GitHub.

The API reference is here.

Couchbase welcomes community contributions to the Kotlin SDK. The source code is available on GitHub.