# Kuery Client

> Write SQL as it is

A Kotlin/JVM database client built on Spring Data — interpolated runtime values become bind parameters via a compiler plugin

## Table of Contents

### Guide

- [Introduction](/introduction.md): Overview of Kuery Client's features, motivation, and the SQL builder with string interpolation (R2DBC / JDBC).
- [Getting Started](/getting-started.md): Add Kuery Client to an existing Kotlin/Spring Boot project, choose R2DBC or JDBC, configure the client, and run the first query.
- [Building SQL](/basics.md): Build safe static and dynamic SQL with +/add, interpolation, constants, collections, reusable helpers, and the lower-level addUnsafe/bind APIs.
- [Fetching Results](/fetching-results.md): Execute queries and map results with single, list, flow, sequence, rowsUpdated, generatedValues, and statement options.
- [Row Mapping](/row-mapping.md): How query results are mapped to Kotlin types: single-column scalars, data classes via constructor mapping (snake_case to camelCase), enums, nullability, value classes, and raw maps.
- [Transaction](/transaction.md): Use Spring transactions with Kuery Client — programmatic (TransactionalOperator / TransactionTemplate) and declarative @Transactional.

### Safety

- [Compile-Time Checks](/compiler-safety-check.md): All compile-time diagnostics reported by the kuery-client compiler plugin — unsafe SQL strings, bind() misuse, SQL syntax validation, redundant trimIndent — and the strict option that escalates the safety warnings into compile errors.
- [SQL Syntax Check (opt-in)](/sql-syntax-check.md): The opt-in KUERY_SQL_SYNTAX compiler warning that validates statically-known SQL with a SQL parser at compile time.

### Advanced

- [Type Conversion](/type-conversion.md): Register Spring's @WritingConverter / @ReadingConverter via the builder's converters(...) to support custom types.
- [Observation](/observation.md): Wire Micrometer ObservationRegistry and ObservationConvention; recorded tags, sql_id generation and its constraints, with a Prometheus/Actuator example.
- [Helpers](/helpers.md): Use the built-in values helper to create multi-row INSERT statements with every value safely bound.

### Reference

- [Configuration](/configuration.md): Reference for the Kuery Client Gradle plugin and runtime client-builder options, including defaults and recommended settings.
- [Supported Platforms](/supported-platforms.md): Databases, drivers, and JVM platforms exercised by Kuery Client's automated test suite, plus database-specific behavior to account for.
- [Examples](/examples.md): Run the repository's Spring WebFlux/R2DBC and Spring WebMVC/JDBC example applications against MySQL.
- [Compatibility](/compatibility.md): API stability policy, Kotlin version policy, and the version compatibility matrix between Kuery Client releases and Kotlin / Spring Boot / Spring Data versions.