Install and Start Using the Kotlin SDK with Couchbase Server

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

    These pages cover the first Developer Preview of the Couchbase Kotlin SDK 1.0 (DP1). Developer Preview code is likely to change without notice, and should not be used in production.

    Installing the SDK

    This guide assumes you are familiar with setting up a Kotlin project using Maven or Gradle.

    The Couchbase Kotlin SDK requires Java 8 or later. We recommend running the latest Java LTS version with the highest patch version available.

    Couchbase publishes all stable artifacts to Maven Central. The latest version (as of July 2021) is 1.0.0-dp.1.

    You can use your favorite dependency management tool to install the SDK. The following snippet shows how to do it with Maven.


    For Gradle, you can use:

    implementation 'com.couchbase.client:kotlin-client:1.0.0-dp.1'

    Hello Couchbase

    Here’s an example that demonstrates the simplest way to perform a N1QL query and get a document from the K/V service.

    • Local Couchbase Server

    • Couchbase Cloud Sample

    import com.couchbase.client.kotlin.Cluster
    import com.couchbase.client.kotlin.query.execute
    import kotlinx.coroutines.runBlocking
    public fun main() {
        // Assumes you have Couchbase running locally
        // and the "travel-sample" sample bucket loaded.
        // Connect and open a bucket
        val cluster = Cluster.connect("", "Administrator", "password")
        try {
            val bucket = cluster.bucket("travel-sample")
            val collection = bucket.defaultCollection()
            runBlocking {
                // Perform a N1QL query and buffer the results
                val queryResult = cluster
                    .query("select * from `travel-sample` limit 3")
                queryResult.rows.forEach { println(it) }
                // Get a document from the K/V service
                val getResult = collection.get("airline_10")
                println(getResult.contentAs<Map<String, Any?>>())
        } finally {
            runBlocking { cluster.disconnect() }

    Connecting to Couchbase Cloud is slightly different. You’ll need to configure the client to use TLS, and specify the trusted CA certificate used by the Couchbase deployment.

    import com.couchbase.client.core.env.SecurityConfig
    import com.couchbase.client.kotlin.Cluster
    import com.couchbase.client.kotlin.env.dsl.TrustSource
    import kotlinx.coroutines.runBlocking
    import java.time.Duration
    public fun main() {
        // Update these variables to point to your Cloud instance and credentials.
        val endpoint = ""
        val username = "username"
        val password = "password"
        val bucketName = "bucket"
        val encodedTlsCertificate =
    ... your certificate content in here ...
    -----END CERTIFICATE-----
        val tlsCertificates = SecurityConfig.decodeCertificates(
        // Connect and open a bucket
        val cluster = Cluster.connect(endpoint, username, password) {
            security {
                enableTls = true
                // See TrustSource for alternate ways to load certificates
                // (from filesystem, from KeyStore, etc.)
                trust = TrustSource.certificates(tlsCertificates)
                // During development, if you want to trust all certificates then
                // use InsecureTrustManagerFactory as the trust source.
                // As the name points out, this is INSECURE!
                // trust = TrustSource.factory(InsecureTrustManagerFactory.INSTANCE)
        try {
            val bucket = cluster.bucket(bucketName)
            val collection = bucket.defaultCollection()
            runBlocking {
                // Create a JSON Document
                val arthur = mapOf(
                    "name" to "Arthur",
                    "email" to "",
                    "interests" to listOf("Holy Grail", "African Swallows")
                // Store the Document
                collection.upsert("u:king_arthur", arthur)
                // Load the document and print it (content and metadata)
        } finally {
            runBlocking { cluster.disconnect() }

    More documentation and examples are coming in the future. Meanwhile, please explore the code samples on GitHub.

    Additional Resources

    The API reference can be found here.

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