Kora Database Jdbc

Kora Database JDBC

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.

JDBC access to relational databases. A repository is a @Repository interface extending JdbcRepository; the annotation processor (Java) or KSP (Kotlin) generates $<Name>_Impl at compile time — no reflection, no runtime proxies.

Repository contracts are synchronous. There is no reactive, CompletionStage or Kotlin suspend repository in Kora 2.0; blocking JDBC runs on virtual threads. A suspend repository method is rejected by KSP with "Suspend methods are not supported by the repository generator." R2DBC and Vert.x SQL do not exist in 2.0 at all.

Quick start

1. Dependencies

dependencies {
    koraBom platform("io.koraframework:kora-bom:2.0.0.RC1")
    annotationProcessor "io.koraframework:annotation-processors"   // mandatory: generates $<Name>_Impl

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

    implementation "org.postgresql:postgresql:42.7.7"              // the driver is NOT bundled
}

Kotlin uses ksp("io.koraframework:symbol-processors") instead of annotationProcessor. Artifacts inherit their version from kora-bom — never pin io.koraframework:* individually. Java 25 is the floor: Kora 2.0 artifacts are compiled to class-file 69.

2. Plug the module into @KoraApp

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

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

JdbcDatabaseModule supplies the JdbcDataSource (which is the JdbcExecutor), the default column/row mappers from JdbcMapperModule, and the JdbcDatabaseConfig reader bound to the jdbc config section.

3. Define an entity

@EntityJdbc
@Table("entities")
public record Entity(
        @Id String id,
        @Column("value1") int field1,
        String value2,
        @Nullable String value3) {}

• @EntityJdbc — io.koraframework.database.jdbc.annotation.EntityJdbc (moved in 2.0; it was …database.jdbc.EntityJdbc in 1.x).
• @Table, @Column, @Id, @Embedded, @Batch, @Query, @Repository — all in io.koraframework.database.common.annotation, unchanged position.
• @Nullable — JSpecify org.jspecify.annotations.Nullable. It is a type-use annotation, so on a qualified nested type it goes before the simple name: Entity.@Nullable FieldType.
• Without @Column a field maps to its snake_lower_case name.

Kotlin uses use-site targets on data-class properties:

@EntityJdbc
@Table("entities")
data class Entity(
    @field:Id val id: String,
    @field:Column("value1") val field1: Int,
    val value2: String,
    val value3: String?
)

4. Repository with SQL macros

@Repository
public interface EntityRepository extends JdbcRepository {

    @Query("SELECT %{return#selects} FROM %{return#table} WHERE id = :id")
    @Nullable
    Entity findById(String id);

    @Query("SELECT %{return#selects} FROM %{return#table}")
    List<Entity> findAll();

    @Query("INSERT INTO %{entity#inserts}")
    UpdateCount insert(Entity entity);

    @Query("UPDATE %{entity#table} SET %{entity#updates} WHERE %{entity#where = @id}")
    UpdateCount update(Entity entity);

    @Query("DELETE FROM entities WHERE id = :id")
    UpdateCount deleteById(String id);
}

A macro target must be resolvable in that method: a parameter name, return, or a type parameter of the repository. %{entity#table} in a method that has no parameter called entity fails to compile with "Query macro target entity cannot be resolved" — write the table name literally there, or use %{V#table} in a generic base interface.

5. Database-generated identifier

@Query("INSERT INTO entities_sequence(name) VALUES (:entity.name)")
@Id
Long insertGenerated(Entity entity);              // via Statement.getGeneratedKeys()

@Query("INSERT INTO entities_sequence(name) VALUES (:entity.name)")
@Id
List<Long> insertGenerated(@Batch List<Entity> entity);   // works for @Batch too

@Query("INSERT INTO entities_sequence(name) VALUES (:entity.name) RETURNING id")
long insert(Entity entity);                       // explicit RETURNING projection

6. Transactions

@Component
public final class EntityService {

    private final EntityRepository repository;

    public EntityService(EntityRepository repository) {
        this.repository = repository;
    }

    public List<Entity> saveAll(Entity one, Entity two) {
        return repository.executor().inTx(() -> {
            repository.insert(one);
            repository.insert(two);
            return List.of(one, two);
        });
    }
}

JdbcRepository.executor() returns the JdbcExecutor (replaces 1.x getJdbcConnectionFactory()). Every repository call inside the lambda joins the same transaction; a thrown exception rolls the whole block back.

Kotlin needs an explicit SAM constructor — the inTx overloads no longer infer from a bare lambda:

val saved = repository.executor().inTx(JdbcExecutor.SqlSupplier {
    repository.insert(one)
    listOf(one)
})

repository.executor().inTx(JdbcExecutor.SqlRunnable {
    repository.deleteAll()
})

Without it the compiler reports Cannot infer type for type parameter T or Overload resolution ambiguity — neither mentions transactions.

Configuration (application.conf)

jdbc {
    jdbcUrl = ${POSTGRES_JDBC_URL}   // required
    username = ${POSTGRES_USER}      // required
    password = ${POSTGRES_PASS}      // required
    poolName = "kora"                // required
    maxPoolSize = 10
    minIdle = 0
    connectionTimeout = "10s"        // durations are strings, not millisecond numbers
    idleTimeout = "10m"
    maxLifetime = "15m"
    initializationFailTimeout = "10s"  // omit to skip the startup connectivity check entirely
    telemetry.logging.enabled = true    // default false
    telemetry.metrics.enabled = true    // default false
}

The section is jdbc, not db. A leftover db { } block compiles fine and dies at startup with ConfigValueException: Config expected value, but got null at path: 'ROOT.jdbc.username' — which names a section your config does not contain. The same rename applies to HOCON embedded in test sources through KoraConfigModification.ofString("""…""").

Full key list, telemetry sub-keys and the YAML form: database-jdbc-config-reference.md.

SQL macros

Macros expand at compile time into SQL you could have written by hand. # separates the target from the command; the target is a method parameter name, return, a nested path (return.user), or a repository/method type parameter.

Those eight are the whole set — table, table as, selects, columns, values, inserts, updates, where. There is no deletes command; write DELETE FROM … WHERE … yourself.

Field enumeration follows the command: = keeps only the listed fields, -= excludes them, and @id refers to the @Id field(s).

@Query("INSERT INTO %{entity#inserts -= @id}")           // every column except the @Id
@Id Long insert(Entity entity);

@Query("INSERT INTO %{entity#table}(%{entity#columns -= @id}) VALUES (%{entity#values -= @id})")
UpdateCount insertExplicit(Entity entity);

@Query("INSERT INTO %{entity#inserts} ON CONFLICT (%{entity#selects = @id}) DO UPDATE SET %{entity#updates}")
UpdateCount upsert(Entity entity);

Repository method signatures

Kotlin writes the same set with T? and Unit. suspend is rejected, and so are Mono/Flux/CompletionStage — those contracts no longer exist.

References

Assets

Generate a starter entity + repository:

python3 scripts/generate_repository.py --entity User --table users --id-type Long --lang java \
    --package com.example.repository --dry-run

Drop --dry-run to write the files.

Common pitfalls

Version compatibility