sqlc-ydb

Inspired by sqlc, sqlc-ydb brings its SQL-first, typed query workflow to YDB as an independent implementation. Read the project history for the upstream YDB proposals, engine-plugin discussions, and the decision to build a standalone tool.

Generate typed query code from YQL for YDB in Go, Python, C++, C#, Java, Kotlin, TypeScript, Rust and PHP. One executable contains the parser, semantic analyzer and generators. Generation works offline and does not require a running YDB, Python, or any separately installed codegen plugin.

Supported YQL and configuration options are listed in the compatibility contract. See the changelog and GitHub Releases for release status. Installation and artifact verification are described in installation.

Install

Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/ydb-platform/sqlc-ydb/main/install.sh | bash

See installation for pinned versions, release candidates, Windows downloads and PATH setup.

Feature parity with sqlc

The core generate, compile, diff, init and version workflow is supported. Configuration is a subset of sqlc v2; queries use YQL parameters and :one, :many, or :exec annotations. Other database engines, external plugins, sqlc macros, database-assisted analysis and cloud workflows are not supported.

See the first-release summary for the comparison and known limitations, and the compatibility contract for the exact CLI, option and YQL coverage.

Supported targets

Language	Framework	Single Query	Multiple Queries in One Transaction
Go	YDB Query SDK	Test	Test
Go	database/sql	Test	Test
Python	YDB Query SDK	Test	Test
Python	DB-API	Test	Test
Python	SQLAlchemy	Test	Test
C++	YDB Query SDK	Test	Test
C++	userver	Test	Test
C#	ADO.NET	Test	Test
C#	Dapper	Test	Test
Java	YDB Query SDK	Test	Test
Java	JDBC	Test	Test
Java	jOOQ	Test	Test
Kotlin	YDB Query SDK	Test	Test
Kotlin	JDBC	Test	Test
Kotlin	Exposed	Test	Test
TypeScript	YDB Query SDK	Test	Test
Rust	YDB Query SDK	Test	Test
PHP	YDB SDK	Test	—

Links open integration tests using generated helpers. A single-query example shows an individual helper call; a transaction example shares one transaction across several calls. The caller owns transaction boundaries and retries. These suites run in CI against disposable YDB; locally, live tests require YDB_CONNECTION_STRING.

A dash means unsupported. PHP transaction support requires a raw-result API in the SDK that can join an existing transaction.

All targets are built into the executable. Only the generated application needs the selected runtime library. Configuration, generated APIs and type coverage are documented in the target reference.

Quick start

Build with Go 1.26:

go build -o bin/sqlc-ydb ./cmd/sqlc-ydb
./bin/sqlc-ydb generate -f examples/authors/sqlc.yaml
./bin/sqlc-ydb compile -f examples/authors/sqlc.yaml
./bin/sqlc-ydb diff -f examples/authors/sqlc.yaml

The authors example shares one schema, query file and configuration across all targets above.

All upstream example families are also adapted for YDB: authors, batch, booktest, jets and ondeck. Run make generate to regenerate them and make check-examples to verify analysis, generated outputs, Go builds and Python syntax.

version: "2"
sql:
  - engine: ydb
    schema: schema.sql
    queries: query.sql
    gen:
      go:
        package: db
        out: db
        sql_package: ydb
      python:
        out: queries
        runtime: ydb

-- name: GetAuthor :one
SELECT name FROM authors WHERE id = $author_id;

Use sqlc-ydb init for a starting configuration. Input and output paths are relative to the configuration file. generate completes analysis and rendering before writing any files; compile writes nothing; diff writes nothing and exits with status 1 if generated contents differ. Renamed queries or models can leave obsolete generated files: generate and diff report these for manual removal in their current output directories. See output ownership when moving outputs or sharing directories between configurations.

References

• Compatibility: supported SQL, configuration and output ownership.
• Installation: source builds, platform archives and version checks.
• Targets: generated APIs, types and runtime contracts.
• History: upstream proposals and the standalone project's origins.
• Source provenance: adapted sources and attribution.

For repository work, start with AGENTS.md.