Skip to content
Kaumei JDBCKaumei JDBCKaumei JDBC

Release 0.2.0 (2026-09-02)

Overview

Section titled “Overview”

Kaumei JDBC 0.2.0 is a public preview release. It is published in Maven Central Repository. It focuses on proving that annotation processing can generate practical JDBC code without hiding SQL or leaning on reflection. It also introduces framework-independent local JDBC transactions and a new Avaje Inject integration aligned with the existing Spring examples. Expect APIs to change before 1.0.0, but the core experience is ready for review and early adoption.

Bug fixes

Section titled “Bug fixes”
  • #1 Annotation processing fails for records with components of the same type
  • Prevent statement leaks during JDBC batch creation
  • Prevent placeholder count overflow
  • Fix stream null characteristics
  • Isolate annotation processor failures per method
  • Fix configuration error handling
  • Honor statement configuration for scalar selects

Improvements

Section titled “Improvements”
  • Improve annotation-processor diagnostics when required Kaumei JDBC artifacts are missing from the compile classpath.
  • Improve diagnostics for collection parameters used without expansion: When a List or array cannot be converted as a single SQL value, the processor now points to the matching :parameter.* expansion syntax.
  • Add @JdbcUpdate.returnGeneratedColumns to request generated keys by name, including support for Oracle JDBC drivers.
  • Support double-quoted identifiers in @JdbcName for case-sensitive database names, such as Oracle identifiers.
  • Clarify JDBC converter exception handling in spec
  • Clarify array return semantics for JDBC selects
  • Add the jdbc-tx local JDBC transaction manager with programmatic transaction types, attributes, rollback rules, synchronisation callbacks, and intermediate commits. See the Transactions guide.
  • Add @KaumeiTx and the framework-independent KaumeiTxProxy for declarative transaction handling. A bare @KaumeiTx deliberately defaults to MANDATORY.
  • Add an Avaje Inject integration that delegates @KaumeiTx methods to jdbc-tx through a compile-time aspect.
  • Align the existing Spring DataSource, Hibernate, and JPA examples with the Avaje integration example.
  • Separate the public JDBC Processor and Transaction Manager contracts.
  • Add @JdbcCall for generated callable statements with scalar input, output, and input/output parameters. The generated code remains JDBC-driver-independent; database-specific callable syntax and driver configuration remain application-owned.

Breaking changes

Section titled “Breaking changes”
  • Move the JDBC core API to io.kaumei.jdbc.core:
    All runtime types formerly declared in io.kaumei.jdbc now use the io.kaumei.jdbc.core package. Update hand-written imports and types in method signatures accordingly. Runtime implementation types now reside in io.kaumei.jdbc.core.internal.
  • Prefix generated implementation suffixes with $:
    The default generated type name changes from <InterfaceName>Jdbc to <InterfaceName>$Jdbc. Configure @JdbcConfig(generatedClassSuffix = "Jdbc") to retain the previous naming convention.
  • Validate void return types for JDBC native targets:
    The annotated JDBC method and its native target method must now declare exactly the same return type, including void.
  • Fix SQL tokenizer parsing:
    Quoted fragments now escape their delimiter by doubling it, and a backslash no longer escapes a quote delimiter. SQL annotations that relied on backslash-escaped quotes must be updated.
  • Handle unsupported JDBC interface inheritance
  • Reject unsupported generic JDBC declarations
  • Stop copying interface annotations to generated classes
  • Validate converter and native target visibility

Installation

Section titled “Installation”

The 0.2.0 library artifacts are available from Maven Central. Follow the installation guide for setup.

Use the same version for jdbc-annotation, jdbc-core, and jdbc-processor, and enable annotation processing in your build. Add jdbc-tx with the same version when Kaumei JDBC should own local transaction boundaries.

Known limitations

Section titled “Known limitations”
  • Loading SQL from the classpath.
  • No first-class support yet for targeting several database dialects from one interface.
  • The JDBC processor does not yet generate @KaumeiTx transaction calls. Use KaumeiTxProxy or a framework integration.
  • Diagnostics and documentation will continue to improve based on user feedback.

Road to 1.0.0

Section titled “Road to 1.0.0”

During the 0.x series, planned work includes:

  • Gather feedback and evaluate whether this approach is useful in practice.
  • Stabilise the annotation processor output and contract tests.
  • Stabilise the transaction API and its framework integration boundaries.

If there is little interest or feedback, the project may simply stay as it is.

Feedback is welcome on Codeberg issues.