Cassandra Coroutine Client

Latest stable Based on Bluetape4k release 1.11.0

What this library owns

bluetape4k-cassandra adds Kotlin session factories, coroutine queries, and row and statement extensions to the Apache Cassandra Java Driver. It does not operate the Cassandra cluster or its schema. The application still chooses contact points, credentials, keyspaces, and when sessions end.

Decisions before adopting it

Decide whether each operation creates and closes its own session or the application reuses sessions.
For reuse, use bounded configuration dimensions such as contact point, datacenter, routing profile, credential version, and client id rather than request-specific values.
Choose blocking execute or coroutine-based executeSuspending to match the calling layer.
Decide whether the application may create keyspaces or deployment manages them separately.

Add the dependency

Expose only the central BOM version instead of repeating versions for individual bluetape4k artifacts.

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:<version>"))
    implementation("io.github.bluetape4k:bluetape4k-cassandra")
}

First query

The code that creates a direct session also closes it. Keeping the query inside use closes the session after either a successful return or an exception.

import io.bluetape4k.cassandra.cqlSessionOf
import java.net.InetSocketAddress

val contactPoint = InetSocketAddress("127.0.0.1", 9042)

val releaseVersion = cqlSessionOf(
    contactPoint = contactPoint,
    localDatacenter = "datacenter1",
    keyspaceName = "system",
).use { session ->
    session.execute("SELECT release_version FROM system.local")
        .one()
        ?.getString("release_version")
}

API decision map

Task	Start with	Ownership or caution
Create a session for a short scope	`cqlSessionOf`, `cqlSession`	The caller closes it with `use` or `close`.
Reuse a session for one connection context	`CqlSessionProvider`, `CqlSessionIdentity`	The identity is the cache boundary; the provider registers shutdown.
Query or prepare from a coroutine	`executeSuspending`, `prepareSuspending`	Preserve caller cancellation and paging boundaries.
Map rows and driver values to Kotlin types	`RowSupport`, `GettableSupport`, `DataTypeSupport`	Check null and column-type contracts first.
Assemble statements and query builders	`StatementSupport`, `QueryBuilderSupport`	Keep consistency, timeout, and keyspace visible at the call site.
Manage keyspaces and integration tests	`CassandraAdmin`, `AbstractCassandraTest`	Separate production DDL authority from test-container lifecycle.

Learning path

Recommended patterns

Close directly created sessions where they are created, and reuse shared sessions through a bounded CqlSessionIdentity. Keep query values behind bind markers, map each Row into a domain type at the read boundary, and treat multi-page results as partially consumable and cancellable.

Integrations

The module builds on the Apache Cassandra Java Driver core, query builder, and mapper runtime, and connects asynchronous execution and paging to Kotlin Coroutines. An application that uses mapper-generated EntityHelper types must also configure the DataStax mapper annotation processor in its build.

Configuration

The application owns contact points, localDatacenter, authentication, TLS, keyspace, and statement consistency and timeout. Provider identities should contain only a bounded set of log-approved connection or credential configuration IDs.

Failure behavior

Blank keyspaces and local datacenters are rejected at the input boundary. Query preparation and execution, row mapping, and next-page fetch failures propagate at their respective operation boundaries. For bootstrap authentication failures, inspect the 1.11.0 admin-session settings first.

Operations

Keyspace creation and deletion are real cluster side effects. Separate production privileges and replication policy from application startup, and observe session shutdown, query and paging failures, batch size, and timeout. See Operational boundaries and Testcontainers verification for the full checklist.

Testing

Tests that require real Cassandra behavior use Testcontainers and a working Docker runtime. Do not run them in parallel with other heavy integration tests.

./gradlew :bluetape4k-cassandra:test --no-build-cache --no-configuration-cache

Workshops

There is no module-specific workshop yet. The examples and source/test links verified against 1.11.0 provide a sequential path through sessions, coroutine paging, mapping, QueryBuilder, and operations.

1.11.0 limitation

In 1.11.0, CqlSessionProvider builds its keyspace-bootstrap admin session with builderSupplier().build(). The trailing builder block applies only to the final keyspace-bound session. Put contact point, local datacenter, authentication, and TLS settings required by both sessions in builderSupplier. This differs from the behavior introduced by PR #986 after 1.11.0.

Release diagrams

These diagrams are loaded directly from README assets published with the 1.11.0 release and pinned to its immutable commit. They describe this manual’s released structure and runtime flows, not later Snapshot changes. Select a preview to open the SVG at the same release commit.