db-catalyst

module
v0.12.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 11, 2026 License: MIT

README

db-catalyst

Go Report Card Go Version

db-catalyst turns SQL schemas and query files into deterministic, idiomatic Go 1.25+ persistence packages. The CLI keeps configuration lightweight while producing code that looks hand-written: context-first signatures, descriptive names, and zero hidden globals.

Why db-catalyst (positioning)

db-catalyst is a sqlc-family generator built around three deliberate choices:

  1. SQLite-first. SQLite (and Turso) is the primary, best-supported dialect — the real-world hardening corpus, the in-process verify oracle, FTS5/virtual-table handling, and the dynamic-query features all target it. PostgreSQL, MySQL, DuckDB, and ClickHouse are supported, but SQLite is where the depth is. (sqlc is the opposite: PostgreSQL-first, SQLite as the weakest dialect.)

  2. Built for AI-driven development. The tool assumes an LLM/agent is writing much of the SQL and needs fast, machine-readable feedback:

    • db-catalyst check --stdin --format json — one-shot query validation for agents;
    • db-catalyst mcp — a stdio MCP server exposing the analyzer to any agent runtime;
    • --format json diagnostics everywhere, with stable [Ennn] error codes;
    • --suggest — opt-in fix suggestions;
    • the verify tier ([verify] + db-catalyst verify) prepares every query against your real schema with an in-process SQLite oracle — no database server, no Docker — and writes a committable cache, so generated types are proven, not just inferred.

  3. Local-only CI, on purpose. There are no GitHub Actions workflows and that is intentional: development is driven by local AI agents, and the quality gate is task ci run on the developer's machine (lint, vet, race, coverage, fuzzing, codegen-compile e2e). Nothing merges or pushes red — see the push policy in CLAUDE.md. Don't "fix" the missing cloud CI; it is not missing.

Consequences of these choices (non-goals, not gaps):

  • No pgx-native codegen. Generated code targets database/sql (the DBTX interface); PostgreSQL types map through pgtype.* but a sql_package: pgx/v5 mode is out of scope while SQLite is the focus.
  • No release binaries / cloud release pipeline. Install from source with go install; version tags are cut locally after a green task ci.
  • No protobuf plugin wire. Codegen plugins use a versioned JSON IR contract over WASM (wazero); compatibility with existing sqlc-gen-* protobuf plugins is not a goal.

Supported Databases

  • SQLite (default, primary) — full support with modernc.org/sqlite or mattn/go-sqlite3, including the in-process verify oracle
  • Turso — SQLite-compatible Rust database (driver turso.tech/database/tursogo), with native vector (F32_BLOB) columns. See docs/turso.md.
  • PostgreSQL — type mapping via pgx/v5 pgtype.*, composite types, enums, origin-trace verify (DSN required)
  • MySQL — DDL/queries, type refinement verify (DSN required)
  • DuckDB, ClickHouse — including Nullable/Array/LowCardinality
database = "sqlite"   # sqlite | turso | postgres | mysql | duckdb | clickhouse

Requirements

  • Go 1.25.3 or newer
  • goimports: install with go install golang.org/x/tools/cmd/goimports@latest
  • task for the development workflow

Quick Start

# Install the CLI (binary lands in $(go env GOBIN) or GOPATH/bin)
go install ./cmd/db-catalyst

# View CLI usage
db-catalyst --help

# Fast local sanity loop: build + test + codegen-compile + lint
task quick

# Full local CI gate (what would normally live in cloud CI)
task ci

# Execute a focused package test
go test ./internal/config -run TestLoadConfig

Minimal config (db-catalyst.toml):

package  = "db"
out      = "internal/db"
database = "sqlite"
schemas  = ["schema.sql"]
queries  = ["queries/*.sql"]

[verify]            # recommended: prove query types against the real schema
enabled = true
engine  = "sqlite"

db-catalyst verify    # writes db-catalyst.verified.json (commit it)
db-catalyst generate

For AI agents

One-shot validation of agent-written SQL:

echo "SELECT id, json_extract(data,'$.x') AS x FROM t" | db-catalyst check --stdin --format json

Or run the MCP server and let the agent query the analyzer directly:

db-catalyst mcp

db-catalyst vet adds lint rules (no-select-star, no-unfiltered-update-delete, no-unbounded-many, query-plan-scan via EXPLAIN QUERY PLAN).

Migrating from sqlc

Coming from sqlc? Run sqlc2dbcat to convert sqlc.yaml automatically, then see the migration guide + parity matrix. Most .sql query files migrate unchanged (-- name: annotations and sqlc.* macros are the same).

Feature Flags

  • docs/feature-flags.md documents the configuration surface, including the [prepared_queries] toggles for metrics and thread-safe statement initialization.

Documentation

Core Documentation
  • Schema Reference: Complete guide to writing SQL schemas, including data types, constraints, indexes, and foreign keys.
  • Query Reference: How to write SQL queries with annotations, parameters, JOINs, CTEs, and advanced features.
  • Generated Code Reference: Understanding the generated Go code, interfaces, transactions, and usage patterns.
  • Verify Tier: live query verification against the real schema.
Additional Documentation

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see LICENSE file.

Directories

Path Synopsis
cmd
db-catalyst command
Package main implements the db-catalyst CLI.
 Package main implements the db-catalyst CLI.
sqlfix command
Package main implements the sqlfix tool for automated SQL rewrites.
 Package main implements the sqlfix tool for automated SQL rewrites.
sqlfix-sqlc command
Package main implements the sqlfix-sqlc tool for migrating sqlc configurations.
 Package main implements the sqlfix-sqlc tool for migrating sqlc configurations.
sqlc2dbcat module
examples
advanced command
advanced/db
advanced/types
cache_example/db
complex command
complex/db
mysql/db
postgresql/db
split_models command
Command split_models demonstrates the optional models-package split, where the generated table-model structs live in their own Go sub-package (.../db/models) that the main querier package and application code import.
 Command split_models demonstrates the optional models-package split, where the generated table-model structs live in their own Go sub-package (.../db/models) that the main querier package and application code import.
split_models/db
split_models/db/models
internal
cache
Package cache provides caching for parsed schemas and query ASTs.
 Package cache provides caching for parsed schemas and query ASTs.
checkcore
Package checkcore provides the core query-validation logic shared by the check subcommand and the MCP server tools.
 Package checkcore provides the core query-validation logic shared by the check subcommand and the MCP server tools.
cli
Package cli provides the command-line interface logic for db-catalyst.
 Package cli provides the command-line interface logic for db-catalyst.
codegen
Package codegen orchestrates the generation of Go code from SQL.
 Package codegen orchestrates the generation of Go code from SQL.
codegen/ast
Package ast provides types and logic for building Go ASTs.
 Package ast provides types and logic for building Go ASTs.
codegen/render
Package render formats and writes generated Go code.
 Package render formats and writes generated Go code.
codegen/rust
Package rust generates Rust code using text templates.
 Package rust generates Rust code using text templates.
codegen/sql
Package sql generates SQL schema definitions from a database catalog.
 Package sql generates SQL schema definitions from a database catalog.
codegen/typescript
Package typescript generates TypeScript code using text templates.
 Package typescript generates TypeScript code using text templates.
config
Package config loads and validates the db-catalyst configuration.
 Package config loads and validates the db-catalyst configuration.
diagnostics
Package diagnostics provides rich diagnostic information for db-catalyst.
 Package diagnostics provides rich diagnostic information for db-catalyst.
engine
Package engine defines the database engine abstraction layer.
 Package engine defines the database engine abstraction layer.
engine/builtin
Package builtin registers all built-in database engines.
 Package builtin registers all built-in database engines.
engine/clickhouse
Package clickhouse provides the ClickHouse database engine implementation.
 Package clickhouse provides the ClickHouse database engine implementation.
engine/duckdb
Package duckdb provides the DuckDB database engine implementation.
 Package duckdb provides the DuckDB database engine implementation.
engine/mysql
Package mysql provides the MySQL database engine implementation.
 Package mysql provides the MySQL database engine implementation.
engine/postgres
Package postgres provides the PostgreSQL database engine implementation.
 Package postgres provides the PostgreSQL database engine implementation.
engine/sqlite
Package sqlite provides the SQLite database engine implementation.
 Package sqlite provides the SQLite database engine implementation.
engine/turso
Package turso provides the Turso Database engine implementation.
 Package turso provides the Turso Database engine implementation.
equiv
Package equiv implements a build-time DIFFERENTIAL equivalence gate for the optional-filters feature.
 Package equiv implements a build-time DIFFERENTIAL equivalence gate for the optional-filters feature.
fileset
Package fileset handles file path resolution and glob expansion.
 Package fileset handles file path resolution and glob expansion.
logging
Package logging provides a configured slog logger for db-catalyst.
 Package logging provides a configured slog logger for db-catalyst.
mcp
Package mcp implements a minimal stdio JSON-RPC 2.0 server that exposes read-only db-catalyst tools to AI agents via the Model Context Protocol (MCP).
 Package mcp implements a minimal stdio JSON-RPC 2.0 server that exposes read-only db-catalyst tools to AI agents via the Model Context Protocol (MCP).
parser
Package parser provides a high-level SQL parser with functional options.
 Package parser provides a high-level SQL parser with functional options.
parser/grammars
Package grammars defines SQL dialect grammars.
 Package grammars defines SQL dialect grammars.
parser/languages/graphql
Package graphql implements a GraphQL schema parser.
 Package graphql implements a GraphQL schema parser.
pipeline
Package pipeline orchestrates the entire code generation process.
 Package pipeline orchestrates the entire code generation process.
plugin/contract
Package contract defines the versioned, serialized IR exchanged between db-catalyst and out-of-process WASM codegen plugins (RFC 0002).
 Package contract defines the versioned, serialized IR exchanged between db-catalyst and out-of-process WASM codegen plugins (RFC 0002).
plugin/wasm
Package wasm runs out-of-process codegen plugins as sandboxed WebAssembly modules via wazero (pure-Go, no CGO).
 Package wasm runs out-of-process codegen plugins as sandboxed WebAssembly modules via wazero (pure-Go, no CGO).
query/analyzer
Package analyzer validates and resolves SQL queries against a schema catalog.
 Package analyzer validates and resolves SQL queries against a schema catalog.
query/block
Package block handles the parsing of SQL query blocks.
 Package block handles the parsing of SQL query blocks.
query/cache
Package cache provides caching annotations for SQL queries.
 Package cache provides caching annotations for SQL queries.
query/parser
Package parser implements a SQL parser for query validation and parameter extraction.
 Package parser implements a SQL parser for query validation and parameter extraction.
schema/diagnostic
Package diagnostic provides shared types for schema parsing diagnostics.
 Package diagnostic provides shared types for schema parsing diagnostics.
schema/migration
Package migration provides helpers for detecting and preprocessing SQL migration files produced by common migration tools (goose, dbmate, golang-migrate).
 Package migration provides helpers for detecting and preprocessing SQL migration files produced by common migration tools (goose, dbmate, golang-migrate).
schema/model
Package model defines normalized schema catalog types produced by the parser.
 Package model defines normalized schema catalog types produced by the parser.
schema/parser
Package parser implements a DDL parser for SQLite schemas.
 Package parser implements a DDL parser for SQLite schemas.
schema/parser/clickhouse
Package clickhouse provides a ClickHouse DDL parser.
 Package clickhouse provides a ClickHouse DDL parser.
schema/parser/mysql
Package mysql provides SQL keyword constants for the MySQL parser.
 Package mysql provides SQL keyword constants for the MySQL parser.
schema/parser/postgres
Package postgres provides SQL keyword constants for the PostgreSQL parser.
 Package postgres provides SQL keyword constants for the PostgreSQL parser.
schema/tokenizer
Package tokenizer scans SQL source code into tokens.
 Package tokenizer scans SQL source code into tokens.
sqlfix
Package sqlfix implements tools for automated SQL rewrites and migration.
 Package sqlfix implements tools for automated SQL rewrites and migration.
sqlfix/overrides
Package overrides handles conversion of sqlc configuration overrides to db-catalyst format.
 Package overrides handles conversion of sqlc configuration overrides to db-catalyst format.
sqlfix/sqlcconfig
Package sqlcconfig parses sqlc configuration files.
 Package sqlcconfig parses sqlc configuration files.
suggest
Package suggest provides opt-in LLM-assisted query repair hints.
 Package suggest provides opt-in LLM-assisted query repair hints.
testing/chaos
Package chaos provides utilities for chaos testing parsers with corrupt inputs.
 Package chaos provides utilities for chaos testing parsers with corrupt inputs.
transform
Package transform handles custom type transformations.
 Package transform handles custom type transformations.
types
Package types provides PostgreSQL-specific type mappings.
 Package types provides PostgreSQL-specific type mappings.
verify
Package verify refines static query analysis using engine-native query metadata.
 Package verify refines static query analysis using engine-native query metadata.
verify/livedb
Package livedb implements a verify.Verifier backed by a real database via database/sql.
 Package livedb implements a verify.Verifier backed by a real database via database/sql.
verify/mysql
Package mysql implements a verify.Verifier for MySQL using the go-sql-driver/mysql driver via database/sql.
 Package mysql implements a verify.Verifier for MySQL using the go-sql-driver/mysql driver via database/sql.
verify/postgres
Package postgres implements a verify.Verifier for PostgreSQL using the pgx native driver (github.com/jackc/pgx/v5).
 Package postgres implements a verify.Verifier for PostgreSQL using the pgx native driver (github.com/jackc/pgx/v5).
verify/provision
Package provision defines the Provisioner abstraction for spinning up ephemeral database instances during verify runs, and provides:
 Package provision defines the Provisioner abstraction for spinning up ephemeral database instances during verify runs, and provides:
verify/sqlite
Package sqlite implements a verify.Verifier backed by an in-memory modernc.org/sqlite database.
 Package sqlite implements a verify.Verifier backed by an in-memory modernc.org/sqlite database.
vet
Package vet provides a SQL query lint engine for db-catalyst.
 Package vet provides a SQL query lint engine for db-catalyst.
test
compat/harness
Package harness provides a reusable shared compile-corpus test helper for the db-catalyst compatibility test program.
 Package harness provides a reusable shared compile-corpus test helper for the db-catalyst compatibility test program.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.