panache-kotlin-dsl

A dynamic, type-safe way to write your queries

Changelog | Contributing

Examples

TODO

Getting Started

Gradle Kotlin DSL

Add the KSP Gradle plugin to your build file

plugins {
    id("com.google.devtools.ksp") version "2.3.0"
}

Add this library to your build file and register it with KSP

dependencies {
  implementation("ch.icken:panache-kotlin-dsl:0.1.1")
  ksp("ch.icken:panache-kotlin-dsl:0.1.1")
}

Optionally configure the behavior

ksp {
  arg("addGeneratedAnnotation", "true")
}

Gradle Groovy DSL

TODO

Apache Maven

TODO

Requirements

• Quarkus version 3.24.0 or newer
  • Dependency io.quarkus:quarkus-hibernate-orm-panache-kotlin is required
• Kotlin version 2.1.21 or newer
• KSP version 2.1.21-2.0.1 or newer
  • Note: Only KSP2 is supported. KSP1 is not supported!
  • When using any KSP version before 2.3.0, your KSP version needs to match your Kotlin version. This is a strict requirement!
    For example, when your Kotlin version is 2.1.21, your KSP version needs to be built for and start with the same version, such as 2.1.21-2.0.1

Features

Queries

• Supports the following expressions in a type-safe and null-safe way for all columns
  • eq, neq, lt, gt, lte, gte, in, notIn, between, and notBetween
• Supports like and notLike expressions in a null-safe way for String columns
• Supports and and or expressions for building up a query
• Adds the PanacheSingleResult sealed class and singleResultSafe() extension function to return a single result without throwing exceptions.
  • Allows you to handle no/multiple results with a when (result) { ... } block instead of try-catching

Code Generation

• Generate Columns for non-transient and non-mapped fields in Panache entities
• Generate query entry point extension functions for entities with Panache companion objects
  • where to start building a SELECT/DELETE queries, which may be chained to other Panache functions
  • update with setters to bulk-update multiple rows at once
  • Single expression updateAll to update all rows without requiring a WHERE clause
  • Single expression count, delete, find, stream, single, singleSafe, and multiple
• Allows for overriding the generated Column's type parameter using @ColumnType
  • Especially useful when using a JPA @Converter when the field's type is different to the column's type
• Optionally annotate generated code with @Generated so it can be excluded from test coverage reporting

Known Issues

• Code generation does not handle fields of generic types (e.g. List<E>, Set<E>, etc.), but as far as I'm aware this is difficult to get working with Hibernate anyway. Consider using @ColumnType from this library in combination with a JPA @Converter on such a field.

Planned Features

These features will be added some time in the future. Please do submit an issue if you'd like these sooner rather than later :)

• DSL for sorting expressions