sqlc-ydb

Generate typed query code from YQL for YDB in Go, Python, C++, C#, Java, JavaScript, 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 release plan for release status.

Supported targets

Each link opens the authors example for the selected SDK or framework:

Language	SDK / framework examples
Go	YDB native SDK, database/sql
Python	YDB native SDK, DB-API, SQLAlchemy
C++	YDB native SDK, userver
C#	ADO.NET, Dapper, linq2db
Java	YDB native SDK, JDBC, Spring JDBC, Hibernate
JavaScript	YDB native SDK, ESM with TypeScript declarations
Rust	YDB native SDK
PHP	YDB native SDK

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
DECLARE $author_id AS Uint64;
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.
• Targets: generated APIs, types and runtime contracts.
• Architecture: analysis and generation boundaries.
• Development: contributor commands and tests.
• Roadmap: planned compiler features.
• Release plan: release gates, ydb.tech guide and consumer acceptance.

For repository work, start with AGENTS.md.