wicked-sqlc

A PostgreSQL-focused sqlc fork that generates type-safe Go code for wpgx and dcache. Write SQL; generate query methods with timeouts, optional caching, cache invalidation, replica access, and load/dump helpers for tests.

Architecture

We regularly rebase wicked-sqlc onto upstream sqlc releases. Our changes fall into two layers: compiler changes in the fork and a dedicated Go backend.

Compiler — Parses SQL, resolves schema dependencies, and infers SQL types and parameter nullability. In wpgx mode, the first schema file owns the primary model; the remaining files supply dependencies and are analyzed first.
Codegen contract — sqlc's GenerateRequest carries the catalog, typed queries, and comments. A small WickedMetadata extension adds the primary schema source, its relation, and top-level SELECT classification. Options such as timeout, cache, and invalidate travel as ordinary query comments, not custom compiler parameters.
Wicked backend — internal/codegen/wicked maps SQL types to Go and renders the templates. It parses comment options and generates cache keys, timeout handling, invalidation hooks, replica APIs, and test helpers. The generated code uses wpgx and dcache at runtime.

The backend runs in-process, bundled in the sqlc binary. There is no separate plugin to install. sql_package: wpgx selects it; other Go configurations use upstream's standard Go backend.

Compiler fixes stay in this fork until validated with the full wicked stack, then can be proposed upstream independently. Generation-specific conventions stay in the wicked backend.

Use it

Install a release binary (Linux, macOS; the SHA-256 is checked):

curl -fsSL https://raw.githubusercontent.com/Stumble/sqlc/main/scripts/install.sh | sh -s -- v2.4.1

Or build the current main branch with the Go version specified in go.mod:

git clone https://github.com/Stumble/sqlc.git
cd sqlc
make install

See GUIDE.md for platforms, checksums and Windows.

Select the backend in sqlc.yaml:

version: '2'
sql:
  - engine: postgresql
    schema: books/schema.sql
    queries: books/query.sql
    gen:
      go:
        sql_package: wpgx
        package: books
        out: books

Every query requires a timeout. Caching is opt-in:

-- name: GetBook :one
-- -- timeout: 500ms
-- -- cache: 10m
SELECT * FROM books WHERE id = @id;

Run sqlc generate to generate code, or sqlc diff to check that it is up to date. Existing wicked projects keep the same configuration and commands.

See the guide for schema conventions, query options, and runtime setup, or bookstore for a working example. Upstream documentation covers standard sqlc features.

The original upstream README is preserved below.