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.

<dependency>
  <groupId>com.couchbase.client</groupId>
  <artifactId>kotlin-client</artifactId>
  <version>1.0.0-dp.1</version>
</dependency>

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("127.0.0.1", "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")
                .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() }
    }
}

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.deps.io.netty.handler.ssl.util.InsecureTrustManagerFactory
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 = "--your-instance--.dp.cloud.couchbase.com"
    val username = "username"
    val password = "password"
    val bucketName = "bucket"

    val encodedTlsCertificate =
"""
-----BEGIN CERTIFICATE-----
... your certificate content in here ...
-----END CERTIFICATE-----
"""
    val tlsCertificates = SecurityConfig.decodeCertificates(
        listOf(encodedTlsCertificate)
    );

    // 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 {
            bucket.waitUntilReady(Duration.ofSeconds(10))

            // Create a JSON Document
            val arthur = mapOf(
                "name" to "Arthur",
                "email" to "kingarthur@couchbase.com",
                "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)
            println(collection.get("u:king_arthur"))
        }
    } 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.