GitHub - be-hase/kuery-client: A Kotlin/JVM database client for those who want to write SQL

It looks like plain string interpolation...

val user: User? = kueryClient
    .sql { +"SELECT * FROM users WHERE user_id = $userId" }
    .singleOrNull()

...but it executes as a parameterized query. A Kotlin compiler plugin rewrites the interpolated runtime value into named parameter binding at compile time — so you get the readability of raw SQL without the risk of SQL injection:

SELECT * FROM users WHERE user_id = :p0  -- :p0 = userId, bound as a named parameter

♥️ Love SQL
- ORM libraries are convenient, but they each require learning their own DSL, which we believe is a steep cost. Kuery Client emphasizes writing SQL as it is.
🛡️ Safe by design
- Interpolated runtime values are converted into bind parameters by the compiler plugin, so the normal SQL-building path never concatenates them into the SQL text.
✅ Compile-time checks
- The compiler plugin warns when a SQL string cannot be converted safely, and can optionally validate SQL syntax — mistakes surface at compile time, not in production.
🍃 Built on Spring Data
- Kuery Client is implemented on top of spring-data-r2dbc and spring-data-jdbc. Use whichever you prefer. You can keep using Spring's ecosystem as is, such as @Transactional.
🔭 Observability
- It supports Micrometer Observation, so you can collect and customize metrics, tracing, and logging.
🧩 Extensible
- When dealing with complex data schemas, you often want to share common query logic. Kotlin's extension functions make this easy.

A Taste of the DSL

Dynamic SQL is just Kotlin — if / when / loops, no template syntax to learn. Whether using R2DBC or JDBC, the way of writing is almost the same.

data class User(...)

class UserRepository(private val kueryClient: KueryClient) {
    suspend fun findById(userId: Int): User? = kueryClient
        .sql { +"SELECT * FROM users WHERE user_id = $userId" }
        .singleOrNull()

    suspend fun search(status: String, vip: Boolean?): List<User> = kueryClient
        .sql {
            +"""
            SELECT * FROM users
            WHERE
            status = $status
            """
            if (vip != null) {
                +"AND vip = $vip"
            }
        }
        .list()

    suspend fun insertMany(users: List<User>): Long = kueryClient
        .sql {
            +"INSERT INTO users (username, email)"
            // useful helper function
            values(users) { listOf(it.username, it.email) }
        }
        .rowsUpdated()
}

There are only two things you need to remember:

Concatenate SQL strings using + (unaryPlus). Express logic such as if directly in Kotlin.
Bind parameters using string interpolation.

Motivation

We have used numerous ORM libraries, but in the end, we preferred libraries like MyBatis that allow writing SQL directly.

To construct SQL dynamically, custom template syntax (such as if/foreach) is often used, but we prefer to write logic using the syntax provided by the programming language as much as possible. We want to write dynamic SQL using Kotlin syntax, similar to kotlinx.html.

To meet these needs, we implemented Kuery Client.

Kuery Client simply provides the SQL builder shown above on top of the well-established spring-data-r2dbc / spring-data-jdbc. It is designed to be usable alongside plain spring-data code, so you can start small.

Getting Started

Kuery Client requires Java 17 or later and Gradle 8.4 or later.

Install

Replace <version> with the latest version, which you can find in the Maven Central badge above or on the Getting Started page.

plugins {
    id("dev.hsbrysk.kuery-client") version "<version>"
}

dependencies {
    implementation("dev.hsbrysk.kuery-client:kuery-client-spring-data-r2dbc:<version>")
    // or, implementation("dev.hsbrysk.kuery-client:kuery-client-spring-data-jdbc:<version>")
}

Build KueryClient

For kuery-client-spring-data-r2dbc:

val connectionFactory: ConnectionFactory = ...

val kueryClient = SpringR2dbcKueryClient.builder()
    .connectionFactory(connectionFactory)
    .build()

For kuery-client-spring-data-jdbc:

val dataSource: DataSource = ...

val kueryClient = SpringJdbcKueryClient.builder()
    .dataSource(dataSource)
    .build()

Let's Use It

val userId = "..."
val user: User? = kueryClient
    .sql { +"SELECT * FROM users WHERE user_id = $userId" }
    .singleOrNull()