Skip to content

README.md

Latest commit

 

History

History
108 lines (82 loc) · 4.01 KB

README.md

File metadata and controls

108 lines (82 loc) · 4.01 KB
Raw

sqlcj

sqlcj is a SQL compiler and type-safe Java code generator for PostgreSQL, inspired by sqlc.

You write a PostgreSQL schema snapshot and named SQL queries. sqlcj analyzes them against the schema and generates one readable Java repository per named query group, with typed parameters and typed result records, which executes through a small JDBC runtime:

schema + named SQL  ->  sqlcj generate  ->  generated Java  ->  JDBC

sql:
  - name: Author
    schema: sql/schema.sql
    queries: sql/queries.sql
-- name: GetAuthor :one
SELECT *
FROM authors
WHERE id = $1;
AuthorRepository authors = new AuthorRepository(executor);

AuthorsRow author = authors.getAuthor(1L);

Every query of sql/queries.sql becomes a method of that one AuthorRepository, and the authors row it returns is the top-level AuthorsRow record generated once for the configured package.

The SQL stays visible and owned by the application. sqlcj is not an ORM, a migration tool, or a query builder: it does not run migrations, inspect a live database, or build queries at runtime.

Project status

sqlcj is pre-release. The current version is 0.1.0-SNAPSHOT, and no artifact has been published to Maven Central or any other public repository yet, so the CLI and runtime must be built from this repository. There is no released license or release procedure yet either.

Requirements

  • Java 21 for the CLI and for applications that use the generated code.
  • Maven, to build sqlcj and to build a consuming project.
  • PostgreSQL, reached through the application's own PostgreSQL JDBC driver. sqlcj does not ship a driver. Behavior is verified against PostgreSQL 16.

Artifacts

mvn -DskipTests install produces both artifacts from this repository:

Artifact What it is
sqlcj-cli/target/sqlcj-cli-0.1.0-SNAPSHOT.jar The executable command line tool. It bundles its own dependencies and starts dev.sqlcj.Main.
dev.sqlcj:sqlcj-runtime:0.1.0-SNAPSHOT The dependency of generated code. It has no dependencies of its own, so compiler, YAML, and SQL-parser libraries never reach an application.

The CLI and the runtime must always be used at the same version.

Commands

java -jar sqlcj-cli-0.1.0-SNAPSHOT.jar version    # print the tool version
java -jar sqlcj-cli-0.1.0-SNAPSHOT.jar generate   # compile sqlcj.yaml into Java
java -jar sqlcj-cli-0.1.0-SNAPSHOT.jar --help     # list the commands

generate reads sqlcj.yaml from the directory it is run in. --config <path> names another configuration file, so generation can run from any working directory:

java -jar sqlcj-cli-0.1.0-SNAPSHOT.jar generate --config ../project/sqlcj.yaml

A relative --config value is resolved against the directory the command is run in, while the relative paths inside the file stay relative to the file's own directory. generate exits with status 0 on success, and with status 1 after printing one diagnostic for invalid configuration, an unreadable source, a schema it cannot parse, a query it cannot compile, an output directory or file it cannot write, a stale generated file it cannot delete, or an output manifest it cannot read or write.

Getting started

Follow the Quickstart to build a Maven application that generates, compiles, and runs PostgreSQL create, read, list, update, and delete operations, including an application-controlled commit and rollback.

Documentation

  • Quickstart — an end-to-end PostgreSQL project from an empty directory.
  • Queries — query annotations, the supported SQL shapes, parameter and binding order, the generated API, and what is not supported.
  • Configuration — the sqlcj.yaml format, query-group names, path resolution, and generated Java naming.
  • PostgreSQL Support — the engine contract, accepted column types and CREATE TABLE constructs, null handling, and connection ownership.