koryki on Maven Central

koryki is now available on Maven Central. Two projects are published, both licensed under Apache 2.0:

• koryki core 0.1.0 — the first public release of the Java implementation: the transpiler that turns KQL into SQL, the dialects for eight database engines, and the support libraries around them. Thirteen artifacts under the group ai.koryki.core.
• koryki northwind 0.1.2 — the shared test data: the schema catalog and semantic layer of the Northwind sample database, and the database itself for DuckDB. Two artifacts under the group ai.koryki.northwind.

Until now, trying koryki meant cloning the repository and building it yourself. Now it is a dependency like any other.

Getting started

Add the core transpiler plus the dialect for your database. With Gradle:

dependencies {
    implementation("ai.koryki.core:koryki-core:0.1.0")
    implementation("ai.koryki.core:koryki-duckdb:0.1.0")
}

With Maven:

<dependency>
    <groupId>ai.koryki.core</groupId>
    <artifactId>koryki-core</artifactId>
    <version>0.1.0</version>
</dependency>
<dependency>
    <groupId>ai.koryki.core</groupId>
    <artifactId>koryki-duckdb</artifactId>
    <version>0.1.0</version>
</dependency>

Each dialect brings koryki-core with it, so strictly speaking the dialect alone is enough — but naming both makes it visible what the build depends on. Java 21 is required.

What is in the release

The language and the transpiler

• koryki-core — turns KQL into SQL, by way of IQL, koryki's intermediate query language: the intermediate query model, the rewrite rules, the type system and function catalog, the validators, and a JDBC execution layer.
• koryki-kqlcore — the KQL grammar and the ANTLR lexer and parser generated from it.

The dialects — each renders the intermediate model as one engine's SQL and adapts its JDBC driver:

• koryki-duckdb
• koryki-postgresql
• koryki-oracle
• koryki-snowflake
• koryki-trino
• koryki-mariadb (also MySQL)
• koryki-mssql
• koryki-sqlite

Support

• koryki-northwind — ready-made services for the Northwind sample database, built on the artifacts from the northwind project below.
• koryki-testkit — the JUnit harness for the shared KQL/IQL fixture corpus.
• koryki-tools — documentation tooling and a function-catalog audit.

The northwind project

Every koryki implementation is tested against the same cases, and those cases live in a project of their own: koryki-java/northwind. Two of its modules are now published:

• koryki-northwind-catalog — db.json, the physical schema, and model.json, the semantic layer of the test databases: which entities exist and which links between them are permitted.
• koryki-northwind-duckdb — the Northwind database for DuckDB: the DDL, the data scripts and the prebuilt northwind.duckdb.

Most projects will never name them directly — koryki-northwind in core brings both along. But if you want to read the semantic layer in your own code, or run your own queries against the same data koryki is tested on, they are a dependency away:

dependencies {
    testImplementation("ai.koryki.northwind:koryki-northwind-catalog:0.1.2")
    testRuntimeOnly("ai.koryki.northwind:koryki-northwind-duckdb:0.1.2")
}

The third module, the query corpus — KQL and IQL queries with their expected SQL, results and rejections per dialect — is not published; implementations read it from a checkout of the repository.

Why the release process matters

In the previous post I argued that trust in a query should come from being able to check it, not from being told it is right. The same applies to the software that does the translating. A transpiler that sits between a domain expert and the database has to be something you can inspect and verify — so both releases were built with that in mind:

• Signed. Every artifact is signed with PGP in CI, and both projects use the same key. Its fingerprint is stated in each repository, and RELEASES.md shows how to check a download against it, by hand or on every Gradle build through dependency verification.
• Reproducible. Jars are built with fixed timestamps and file order, so the same commit gives the same bytes. Nothing from the build machine, such as a user name, a host or a build time, ends up in the artifacts.
• Complete. Every jar ships with sources, javadoc, LICENSE and NOTICE, and identifies its own version in the manifest.
• Open. The source is on GitHub, and the grammar and the transformation rules are documented.

What a first release means

These are 0.x versions: until 1.0, the API may still change, and not every change will be backwards compatible. If you try koryki and something does not work the way you expect — or a query renders differently from what you expected on your database — I would like to hear about it: open an issue on GitHub.

If you would rather see koryki in action before adding a dependency, the demo is still at demo.koryki.ai.