Kora Database Cassandra

Kora Database Cassandra

Kora sub-skill — obey the kora-v2 meta rules on every task: R0 ground the workspace on Kora 2.0 refs before starting (framework source at tag 2.0.0.RC1 + kora-examples at migration/2.0; kora-docs is 1.x only) · R1 read this sub-skill before writing code · R2 Kora 2.0 APIs only — no Spring/Micronaut/Quarkus, no Kora 1.x APIs, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

⚑ The driver moved Maven coordinates, not Java packages

Kora 2.0 resolves the DataStax driver from org.apache.cassandra:java-driver-core (with org.apache.cassandra:java-driver-metrics-micrometer for driver metrics), replacing the 1.x com.datastax.oss:java-driver-core. The groupId changed; the package names did not. CqlSession, Row, ResultSet, SettableByName, GettableByName, UdtValue, UserDefinedType and ConsistencyLevel all still live under com.datastax.oss.driver.api.*, and every Kora 2.0 Cassandra API imports them from there.

So import com.datastax.oss.driver.api.core.cql.Row; is correct in a 2.0 service; only a build file that names com.datastax.oss:java-driver-core is stale. In practice you never write the coordinate at all — io.koraframework:database-cassandra brings the driver transitively.

Quick Start

1. Dependency

Java (build.gradle):

configurations {
    koraBom
    annotationProcessor.extendsFrom(koraBom); compileOnly.extendsFrom(koraBom); implementation.extendsFrom(koraBom)
    api.extendsFrom(koraBom); testImplementation.extendsFrom(koraBom); testAnnotationProcessor.extendsFrom(koraBom)
}

dependencies {
    koraBom platform("io.koraframework:kora-bom:$koraVersion")   // koraVersion=2.0.0.RC1
    annotationProcessor "io.koraframework:annotation-processors"

    implementation "io.koraframework:database-cassandra"
    implementation "io.koraframework:config-hocon"
    implementation "io.koraframework:logging-logback"
}

Kotlin (build.gradle.kts) — KSP instead of annotationProcessor, never kapt:

plugins {
    kotlin("jvm") version "2.4.10"
    id("com.google.devtools.ksp") version "2.3.11"
}

dependencies {
    implementation(platform("io.koraframework:kora-bom:${property("koraVersion")}"))
    ksp("io.koraframework:symbol-processors:${property("koraVersion")}")

    implementation("io.koraframework:database-cassandra")
    implementation("io.koraframework:config-hocon")
    implementation("io.koraframework:logging-logback")
}

Java toolchain 25 is the floor for every Kora 2.0 artifact.

2. Enable the module

@KoraApp
public interface Application extends HoconConfigModule, LogbackModule, CassandraDatabaseModule {

    static void main(String[] args) {
        KoraApplication.run(ApplicationGraph::graph);
    }
}

3. Entity

@EntityCassandra
public record User(
    String id,
    @Column("value1") int field1,
    String value2,
    @Nullable String value3
) {}

@Nullable is JSpecify (org.jspecify.annotations.Nullable) and is type-use: put it directly on the type it qualifies. Without @Nullable on a component, a null column throws NullPointerException from the generated row mapper.

@Table is only needed for SQL macros; @Id only matters to macros too — Cassandra needs no primary-key marker for hand-written CQL. Column names default to snake_case of the component name when @Column is absent.

4. Repository

@Repository
public interface UserRepository extends CassandraRepository {

    @Query("SELECT * FROM users WHERE id = :id")
    @Nullable
    User findById(String id);

    @Query("SELECT * FROM users")
    List<User> findAll();

    @Query("INSERT INTO users(id, value1, value2, value3) VALUES (:user.id, :user.field1, :user.value2, :user.value3)")
    void insert(User user);

    @Query("DELETE FROM users WHERE id = :id")
    void deleteById(String id);
}

Entity parameter binding: when a method parameter is an entity, each column binds through the dotted accessor :param.field (:user.id). A bare :id resolves only when id is itself the name of a method parameter, as in findById(String id). An unused method parameter is a compile error (Query parameter is unused).

5. Configuration

cassandra {
  auth {
    login = ${CASSANDRA_USER}
    password = ${CASSANDRA_PASS}
  }
  basic {
    contactPoints = ${CASSANDRA_CONTACT_POINTS}
    dc = ${CASSANDRA_DC}
    sessionKeyspace = ${CASSANDRA_KEYSPACE}
    request {
      timeout = 5s
    }
  }
  telemetry.logging.enabled = true
}

telemetry.logging.enabled and telemetry.metrics.enabled default to false in Kora 2.0 — turn them on explicitly or you get no query logs and no db_* metrics.

Execution model — what a repository method may return

Kora 2.0 contracts are synchronous and run on virtual threads. Cassandra keeps one narrow exception: the Java generator still emits the driver's own executeAsync path.

• Kotlin suspend is rejected at compile time. The KSP repository builder fails before any generator runs, with Suspend methods are not supported by the repository generator. The suggested replacement is Java StructuredTaskScope for real parallelism.
• Flow<T> is not a usable Kotlin return type either: nothing in the framework tests or the migrated Kotlin example uses it, and the generator's non-suspend path applies the mapper to a ResultSet while the Flow branch supplies a CassandraRowMapper whose apply takes a Row — the generated file does not type-check.
• Reactor is gone. database-cassandra has no Reactor dependency, no Mono/Flux handling and no CassandraReactiveResultSetMapper. Do not add reactor-core for it.
• Optional<T> works in Java only; in Kotlin use T?.
• UpdateCount is a JDBC-only return type — the Cassandra generator does not handle it.

Java async example (this is the shape the migrated Kora example ships and tests):

@Repository
public interface UserAsyncRepository extends CassandraRepository {

    @Query("SELECT * FROM users WHERE id = :id")
    CompletableFuture<User> findById(String id);

    @Query("SELECT * FROM users")
    CompletionStage<List<User>> findAll();

    @Query("INSERT INTO users(id, value1) VALUES (:user.id, :user.field1)")
    CompletionStage<Void> insert(User user);
}

See Async Patterns Reference for chaining, batching and the Kotlin migration path.

CRUD, batches and lightweight transactions

// Batch: one single-row statement, the list parameter marked @Batch.
// The generator builds a BatchStatement with DefaultBatchType.UNLOGGED.
@Query("INSERT INTO users(id, value1) VALUES (:user.id, :user.field1)")
void insertBatch(@Batch List<User> user);

// LWT: the first column of the result is the [applied] flag, so boolean works
@Query("INSERT INTO users(id, value1) VALUES (:user.id, :user.field1) IF NOT EXISTS")
boolean insertIfNotExists(User user);

@Query("UPDATE users SET value2 = :value2 WHERE id = :id IF value2 = :oldValue2")
boolean updateIfMatches(String id, String value2, String oldValue2);

@Query("TRUNCATE users")
void deleteAll();

A @Batch method must not declare a result mapper — the generator returns no mapped result for batch statements. Cassandra has no transactions: CassandraExecutor has no inTx and there is nothing equivalent to JDBC's JdbcExecutor.inTx(...). LWT (IF/IF NOT EXISTS) is per-partition compare-and-set, not a multi-statement transaction.

IN clauses need care: Kora ships no CassandraParameterColumnMapper<List<T>> for native element types, so @Query("… WHERE id IN :ids") List<User> findByIds(List<String> ids) fails the graph with No component found for dependency: CassandraParameterColumnMapper<List<String>>. Bind an IN list with CassandraQuery.named().bindIn(...) through executor(), or supply your own list mapper via @Mapping.

User-defined types

@Repository
public interface UserRepository extends CassandraRepository {

    @EntityCassandra
    record Entity(String id, Name name) {

        @UDT
        record Name(String first, String last) {}
    }

    @Query("SELECT * FROM entities_udt WHERE id = :id")
    @Nullable
    Entity findById(String id);

    @Query("INSERT INTO entities_udt(id, name) VALUES (:entity.id, :entity.name)")
    void insert(Entity entity);
}

CREATE TYPE IF NOT EXISTS username(first text, last text);
CREATE TABLE IF NOT EXISTS entities_udt (id VARCHAR, name FROZEN<username>, PRIMARY KEY (id));

@UDT carries no type name. The generated mappers read the user-defined type off the bound statement's own metadata (_stmt.getType(index)) and address fields by column name, so the CQL type may be called anything — only the field names have to line up. Kora generates mappers for a scalar UDT and for List<UDT>; Set<UDT> and Map<K, UDT> are not generated and need a hand-written mapper. Details in UDT Mapping Reference.

Driver profiles

Request tuning lives under basic.request. A profile overrides any basic.request.* / advanced.* key it declares and inherits the rest from the root section.

cassandra {
  basic.request {
    consistency = "QUORUM"
    serialConsistency = "SERIAL"
    timeout = 5s
  }
  profiles {
    analytics {
      basic.request.consistency = "ONE"
      basic.request.timeout = 30s
      basic.request.pageSize = 1000
    }
  }
}

@CassandraProfile("analytics")
@Query("SELECT * FROM events WHERE type = :type ALLOW FILTERING")
List<Event> findByType(String type);

@CassandraProfile is @Target(METHOD) — it cannot go on the repository interface. See Consistency Reference.

Manual queries — executor() and CassandraQuery

CassandraRepository.executor() returns a CassandraExecutor (this replaces the 1.x getCassandraConnectionFactory()). It exposes the live CqlSession plus telemetry-wrapped helpers, and pairs with the CassandraQuery builder for dynamic CQL:

var query = CassandraQuery.named()
    .cql("SELECT id, name FROM users WHERE tenant_id = :tenant_id")
    .bind("tenant_id", tenantId)
    .cqlIf(" AND status = :status", status != null)
    .bindIf("status", status, status != null)
    .cqlIf(" AND id IN (:ids)", !ids.isEmpty())
    .bindInIf("ids", ids, !ids.isEmpty())
    .opts(o -> o.consistencyLevel(DefaultConsistencyLevel.LOCAL_QUORUM).pageSize(500))
    .build();

List<User> users = repository.executor()
    .queryList(query, row -> new User(row.getString("id"), row.getString("name")));

CassandraExecutor also has currentSession(), telemetry(), query(...), queryOne(...) and queryOptional(...). queryOne returns @Nullable T. Full API in the CQL Repository Reference.

Custom mappers and the @Component rule

Whether a mapper needs @Component is decided by its constructor, because the generated repository either constructs the mapper itself or asks the graph for it:

• Java — mapper class is final and has a public no-arg constructor, and @Mapping carries no tag → the repository does new Mapper() in its own constructor. @Component is then optional.
• Kotlin — class is not open and has a single no-arg constructor → same, constructed inline.
• Anything else (constructor dependencies, a non-final/open class, a tagged mapping) → the mapper becomes a constructor parameter of the generated repository and must be in the graph, or the build fails with No component found for dependency: ….

Declare one component per mapper type; two @Components implementing the same CassandraRowMapper<T> give Multiple components match dependency:. Kora's own scalar mappers in CassandraMapperModule are @DefaultComponent, so your own @Component for the same type wins without conflict.

Kotlin nullability trap. The contracts are @NullMarked, so an override must match the declared nullability exactly. CassandraParameterColumnMapper.apply takes @Nullable T value:

class FieldTypeParameterMapper : CassandraParameterColumnMapper<FieldType> {
    override fun apply(stmt: SettableByName<*>, index: Int, value: FieldType?) {   // T? — required
        if (value != null) stmt.setInt(index, value.code) else stmt.setToNull(index)
    }
}

With value: FieldType Kotlin reports 'apply' overrides nothing and never mentions nullability. The Java twin compiles either way, so a mechanically ported mapper fails only on the Kotlin side. Return types may be narrowed to non-null; only parameters must stay nullable.

Assets

Entities and UDTs

Repositories

Mappers

Reference Documents

Migrating a Kora 1.x Cassandra repository

The config section is still cassandra and the key layout under basic / advanced / profiles / auth / telemetry is unchanged — JDBC's db → jdbc rename has no Cassandra counterpart. What did change under telemetry is the defaults: logging and metrics are now off unless enabled.

Common Pitfalls

Best Practices

1. Model tables from query patterns. Cassandra has no joins and no ad-hoc filtering; every ALLOW FILTERING in production code is a modelling bug waiting to happen.
2. Annotate DAOs with @EntityCassandra so row and result-set mappers are generated in the first processing round rather than through the late extension fallback.
3. Prefer synchronous signatures. They run on virtual threads and keep stack traces intact; reach for Java CompletionStage only when you actually pipeline the futures.
4. Use @Nullable, not Optional, for nullable single-row results — and it is the only option in Kotlin.
5. Keep DTOs and DAOs apart. An @Json HTTP model is not a Cassandra entity.
6. Scope consistency with @CassandraProfile, not by rewriting queries.
7. Test against a real container. The Kora examples use io.goodforgod:testcontainers-extensions-scylla with @KoraAppTest; see kora-testing-junit-java / kora-testing-junit-kotlin.