Quickstart

The Kotlin SDK for SurrealDB makes it straightforward to connect to your instance and start querying data with coroutines. This guide walks you through connecting, authenticating, and performing basic operations.

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

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() builder to insert a record. Pass a Table to create in a table with a generated ID, or a RecordId to create a record with a specific ID. Builders are terminated with await() (raw JSON) or the typed awaitAs<T>() 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

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() to execute SurrealQL statements with bound parameters, or .queryAs<T>() 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()

What's next?

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 authentication, live queries, transactions, and multiple sessions.