Start Using the Kotlin SDK

  • tutorial
    +
    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

    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

    implementation("com.couchbase.client:kotlin-client:1.4.0")
    implementation "com.couchbase.client:kotlin-client:1.4.0"
    <dependency>
      <groupId>com.couchbase.client</groupId>
      <artifactId>kotlin-client</artifactId>
      <version>1.4.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
    repositories {
        mavenCentral()
    
        maven {
            url = uri("https://oss.sonatype.org/content/repositories/snapshots")
            mavenContent { snapshotsOnly() }
        }
    }
    build.gradle
    repositories {
        mavenCentral()
    
        maven {
            url "https://oss.sonatype.org/content/repositories/snapshots"
            mavenContent { snapshotsOnly() }
        }
    }
    pom.xml
    <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.

    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.

    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.