Kotlin

The Kotlin SDK for SurrealDB lets you connect to a database and query it from your application with coroutines. This guide covers connecting, authenticating, and running your first queries.

1. Install the SDK

Follow the installation guide to add the SDK as a dependency in your project. Once installed, import the client to start using it.

import com.surrealdb.kotlin.SurrealClient
import com.surrealdb.kotlin.SurrealClientConfig

2. Connect to SurrealDB

Create a SurrealClient with a SurrealClientConfig, then call .use() to select a namespace and database, and .signin() to authenticate.

The transport is selected automatically from the URL scheme:

• •

  WebSocket (ws://, wss://) for long-lived stateful connections that support live queries, transactions, and multiple sessions

• •

  HTTP (http://, https://) for short-lived stateless connections

import com.surrealdb.kotlin.SurrealClient
import com.surrealdb.kotlin.SurrealClientConfig
import kotlinx.coroutines.runBlocking
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

fun main() = runBlocking {
    val client = SurrealClient(SurrealClientConfig(url = "ws://localhost:8000"))

    client.signin(buildJsonObject {
        put("user", "root")
        put("pass", "root")
    })
    client.use("surrealdb", "docs")

    // ...

    client.close()
}

The client connects automatically on first use (autoConnect defaults to true). Call .close() when you are finished to release resources.

3. Inserting data into SurrealDB

To represent records in your application, define @Serializable data classes that match your table structure.

import kotlinx.serialization.Serializable

@Serializable
data class Person(val name: String, val age: Int)

Use the [`.create()`](/docs/reference/kotlin/api/core/surreal-client#create) builder to insert a record. Pass a [`Table`](/docs/reference/kotlin/api/values/table) to create in a table with a generated ID, or a [`RecordId`](/docs/reference/kotlin/api/values/record-id) to create a record with a specific ID. Builders are terminated with `await()` (raw JSON) or the typed [`awaitAs()`](/docs/reference/kotlin/api/core/query-builder#await-as) extension.

import com.surrealdb.kotlin.query.RecordId
import com.surrealdb.kotlin.query.Table
import com.surrealdb.kotlin.query.awaitAs
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

val created: Person = client
    .create(RecordId("person", "john"))
    .content(buildJsonObject {
        put("name", "John")
        put("age", 32)
    })
    .awaitAs()

4. Retrieving data from SurrealDB

Selecting records

The .select() builder retrieves records from a table or a single record by its RecordId. Refine it with .where() using the expression helpers.

import com.surrealdb.kotlin.query.Table
import com.surrealdb.kotlin.query.field
import com.surrealdb.kotlin.query.gte
import com.surrealdb.kotlin.query.awaitAs

val adults: List<Person> = client
    .select(Table("person"))
    .where(field("age") gte 18)
    .limit(50)
    .awaitAs()

Running SurrealQL queries

For more advanced use cases, use [`.query()`](/docs/reference/kotlin/api/core/surreal-client#query) to execute [SurrealQL](/docs/reference/query-language) statements with bound [parameters](/docs/reference/query-language/language-primitives/parameters), or [`.queryAs()`](/docs/reference/kotlin/api/core/surreal-client#query-as) to decode the result directly.

import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

val people: List<Person> = client.queryAs(
    "SELECT * FROM person WHERE age > \$min_age",
    buildJsonObject { put("min_age", 25) },
)

5. Closing the connection

Call .close() to release the connection and all associated resources.

client.close()

Next steps

You have learned how to install the SDK, connect to SurrealDB, create records, and retrieve data. There is a lot more you can do with the SDK, including updating and deleting records, authentication, live queries, and transactions.