Installation

YoSQL turns .sql files into Java repositories at build time. Pick the tooling that matches your build, point it at your SQL, and the generated code is ordinary Java from then on.

What you need

Java 25 or later, both to run YoSQL and to compile and run what it generates. Generated code uses var, text blocks, records and sequenced collections, so it does not compile on older releases.

Nothing else. YoSQL is not a dependency of your application — it runs during your build and the code it leaves behind calls only the JDK and your JDBC driver. Nothing needs to be on the classpath at run time, which is also why a generated repository works unchanged inside a GraalVM native image.

Choosing the tooling

The command line tool is also the way to generate code once and never think about YoSQL again: run it, commit the result, and drop it from your build entirely.

Your first statement

Write a .sql file under src/main/yosql:

-- name: findTenant
-- returning: single
-- resultRowType: com.example.domain.Tenant
select id, slug, created_at
from tenant
where id = :id

Write the record it should build:

package com.example.domain;

public record Tenant(UUID id, String slug, Instant createdAt) {
}

Run your build. You get a TenantRepository with a findTenant method returning Optional<Tenant>, and a converter that reads each column by name and calls the constructor — no reflection, nothing resolved at run time.

From here, SQL files covers how statements are written and configuration covers everything you can change about the output.

Verifying a download

Releases of the command line tool and the Ant task ship a SHA256SUMS file alongside the archives, signed with cosign keyless signing. To check an archive you downloaded from the releases page :

sha256sum --check --ignore-missing SHA256SUMS
cosign verify-blob SHA256SUMS \
  --bundle SHA256SUMS.bundle \
  --certificate-identity-regexp 'https://github\.com/metio/yosql/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Artifacts published to Maven Central are signed with PGP instead, which your build tool checks for you.

Releases

A new version is published on the 8th of each month, named after that date — 2026.8.8 for the August 2026 release. A month with no changes gets no release. When a release needs you to change something, it is described under upgrading .