Connecting to SurrealDB

The Kotlin SDK connects to SurrealDB over WebSocket or HTTP, with automatic transport selection and reconnection.

The first step towards interacting with SurrealDB is to create a connection to a database instance. This involves constructing a SurrealClient with a SurrealClientConfig, then selecting a namespace and database. The SDK supports remote connections over WebSocket and HTTP.

API references

Method	Description
`SurrealClient(config)`	Creates a new client from a configuration
`client.connect()`	Establishes the connection explicitly
`client.close()`	Closes the connection and releases resources
`client.use(ns, db)`	Selects a namespace and database
`client.version()`	Returns the server version
`client.ping()`	Pings the server

Opening a connection

Construct a SurrealClient with a SurrealClientConfig whose url points at your SurrealDB instance. By default (autoConnect = true) the client connects lazily on the first request, so you rarely need to call .connect() yourself.

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

val client = SurrealClient(SurrealClientConfig(url = "ws://localhost:8000"))

Connection string protocols

The URL scheme determines the transport. For more on server configuration, see the start command documentation.

Protocol	Description
`ws://`	Plain WebSocket connection
`wss://`	Secure WebSocket connection (TLS)
`http://`	Plain HTTP connection
`https://`	Secure HTTP connection (TLS)

The WebSocket engine maintains a single long-lived connection, while the HTTP engine issues a request per call.

Feature support by protocol

Not all features are available on every transport. You can check support at runtime with .supports(); unsupported calls throw SurrealFeatureNotSupportedException.

Feature	WebSocket	HTTP
Authentication	Yes	Yes
Queries	Yes	Yes
CRUD operations	Yes	Yes
Live queries	Yes	No
Transactions	Yes	No
Multiple sessions	Yes	No
Refresh tokens	Yes	No
Export / Import	Yes	Yes
SurrealML	Yes	Yes

See Features and events for the full SurrealFeature enum.

Selecting a namespace and database

After connecting, select a namespace and database with .use().

client.use("surrealdb", "docs")

Reconnection

The WebSocket engine automatically reconnects with exponential backoff. Tune this through the ReconnectConfig on your SurrealClientConfig.

import com.surrealdb.kotlin.SurrealClientConfig
import com.surrealdb.kotlin.engine.ReconnectConfig

val client = SurrealClient(
    SurrealClientConfig(
        url = "wss://example.com",
        reconnect = ReconnectConfig(
            enabled = true,
            initialDelayMillis = 250,
            maxDelayMillis = 30_000,
            multiplier = 1.5,
            maxAttempts = null, // null means retry indefinitely
        ),
    ),
)

Observing connection events

The client exposes a connectionEvents SharedFlow you can collect to react to lifecycle changes.

import com.surrealdb.kotlin.engine.SurrealConnectionEvent
import kotlinx.coroutines.launch

scope.launch {
    client.connectionEvents.collect { event ->
        when (event) {
            is SurrealConnectionEvent.Connected -> println("connected")
            is SurrealConnectionEvent.Reconnecting -> println("reconnecting, attempt ${event.attempt}")
            is SurrealConnectionEvent.Disconnected -> println("disconnected")
            is SurrealConnectionEvent.Error -> println("error: ${event.cause.message}")
            else -> {}
        }
    }
}

Closing a connection

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

client.close()

Learn more

SurrealClient API reference for complete method signatures
Client configuration for all configuration options
Authentication for signing in and managing sessions
Error handling for handling connection errors