kandra-test/io.kandra.test/KandraTestBackend

KandraTestBackend

Connection provider for live-cluster tests: one abstraction over the shared Testcontainers Cassandra (KandraTestcontainers) and the env-driven Scylla Cloud cluster (KandraCloud).

Selected by KANDRA_TEST_BACKEND: unset / docker (default, behaviour unchanged) or cloud (requires the KANDRA_CLOUD_* env, see KandraCloud; TLS via KANDRA_CLOUD_TLS=true).

Tests read connection facts from here instead of KandraTestcontainers.container:

install(Kandra) {
    contactPoints = KandraTestBackend.contactPointsCsv
    localDatacenter = KandraTestBackend.localDatacenter
    keyspace = KandraTestBackend.keyspaceName("ktor")
}
KandraTestBackend.newSession().use { it.execute("DROP KEYSPACE IF EXISTS $ks") }

All sessions built here use a 30s request timeout (the driver's 2s default is too tight for DDL against a freshly started container under load, and for WAN latency to the cloud cluster).

Types

FreshKeyspace

class FreshKeyspace : AutoCloseable

A temporary keyspace: session is bound to it, admin is unbound.

Properties

concurrencyBudgetSeconds

val concurrencyBudgetSeconds: Long

Wall-clock budget, in seconds, for tests that race several simulated instances through the LWT/DDL bootstrap paths. 30 s against the Docker container. 180 s against the cloud, where each DDL statement takes 1-5 s (schema agreement over a ~245 ms WAN; measured 2026-10-25 on ScyllaDB Cloud) and simultaneous claims contend in Paxos.

contactPointsCsv

val contactPointsCsv: String

Contact points as a host:port CSV, ready for Kandra's contactPoints config string.

isCloud

val isCloud: Boolean

True when KANDRA_TEST_BACKEND=cloud. Fails fast if the cloud env is not configured.

localDatacenter

val localDatacenter: String

password

val password: String

tlsEnabled

val tlsEnabled: Boolean

truststore

val truststore: KandraCloud.TempTruststore?

Shared truststore (cloud + TLS + CA PEM only; null otherwise). Built once per JVM, deleted on JVM exit.

username

val username: String

Auth credentials (never log). Docker's container runs AllowAllAuthenticator, so both are blank there.

Functions

createKeyspace

fun createKeyspace(name: String, rf: Int = 1)

CREATE KEYSPACE IF NOT EXISTS (SimpleStrategy; on the cloud: effectiveRf and tablets disabled).

createKeyspaceCql

fun createKeyspaceCql(name: String, rf: Int = 1): String

CQL used by createKeyspace (for tests that run it on their own session).

dropKeyspace

fun dropKeyspace(name: String)

effectiveRf

fun effectiveRf(requested: Int): Int

Replication factor to actually create. The cloud cluster cannot serve an RF=1 keyspace reliably (partitions with no live replica), so RF 1 is bumped to 3 there; tests that assert on replication metadata must use this value rather than assume what they asked for.

freshKeyspace

fun freshKeyspace(tag: String, rf: Int = 1): KandraTestBackend.FreshKeyspace

Creates a unique keyspace and returns sessions for it; FreshKeyspace.close always drops it.

keyspaceName

fun keyspaceName(tag: String): String

A unique keyspace name. Docker: kandra_<tag>_<32 hex> (as the tests always used); cloud: the cleanup-friendly kt_<tag>_<8 hex>. Keep tag short (lowercase alphanumeric/underscore).

newSession

fun newSession(keyspace: String? = null): CqlSession

Opens a session (optionally bound to keyspace). Caller must close it.

sessionBuilder

fun sessionBuilder(): CqlSessionBuilder

A configured (unbuilt) session builder with 30s timeouts. Caller owns the built session.