README
¶
db-catalyst
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.
Supported Databases
- SQLite (default) - Full support with modernc.org/sqlite or mattn/go-sqlite3
- PostgreSQL - Type mapping and code generation using pgx/v5
- MySQL - Basic support (proof of concept)
Configure the database in your db-catalyst.toml:
# For SQLite (default)
database = "sqlite"
# For PostgreSQL
database = "postgresql"
# For MySQL
database = "mysql"
Requirements
- Go 1.25.3 or newer
goimports: install withgo install golang.org/x/tools/cmd/goimports@latest
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
# Run the smoke test suite
make test
# Run all tests (add the race detector when touching concurrency)
go test ./...
go test -race ./...
# Execute a focused package test
go test ./internal/config -run TestLoadConfig
Project planning lives in db-catalyst-spec.md and docs/.
PostgreSQL Support
db-catalyst now supports PostgreSQL with the pgx/v5 driver:
# db-catalyst.toml
package = "mydb"
out = "db"
database = "postgresql"
schemas = ["schema/*.sql"]
queries = ["queries/*.sql"]
PostgreSQL Types
The following PostgreSQL types are mapped to Go types:
| PostgreSQL Type | Go Type | Package |
|---|---|---|
UUID |
uuid.UUID |
github.com/google/uuid |
TEXT, VARCHAR |
pgtype.Text |
github.com/jackc/pgx/v5/pgtype |
INTEGER, INT |
pgtype.Int4 |
github.com/jackc/pgx/v5/pgtype |
BIGINT |
pgtype.Int8 |
github.com/jackc/pgx/v5/pgtype |
BOOLEAN |
pgtype.Bool |
github.com/jackc/pgx/v5/pgtype |
TIMESTAMPTZ |
pgtype.Timestamptz |
github.com/jackc/pgx/v5/pgtype |
NUMERIC, DECIMAL |
*decimal.Decimal |
github.com/shopspring/decimal |
JSONB |
[]byte |
- |
Arrays (e.g., TEXT[]) |
pgtype.Text |
github.com/jackc/pgx/v5/pgtype |
See the PostgreSQL example for a complete working example with UUIDs, JSONB, arrays, and more.
Migrating from sqlc
Coming from sqlc? Check out our comprehensive migration guide for step-by-step instructions to convert your existing sqlc projects to db-catalyst.
Feature Flags
docs/feature-flags.mddocuments 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.
Additional Documentation
db-catalyst-spec.md: high-level architecture, pipeline stages, and roadmap.docs/plans/db-catalyst-implementation-plan.md: milestone-by-milestone plan and validation matrix.docs/feature-flags.md: runtime and codegen switches available in configuration.docs/migrating-from-sqlc.md: guide for migrating existing sqlc projects.
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. |
|
examples
|
|
|
advanced
command
|
|
|
advanced/types
Package types provides domain types for the advanced example.
|
Package types provides domain types for the advanced example. |
|
complex
command
|
|
|
internal
|
|
|
cache
Package cache provides caching for parsed schemas and query ASTs.
|
Package cache provides caching for parsed schemas and query ASTs. |
|
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/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. |
|
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. |
|
parser
Package parser provides a high-level SQL parser with functional options.
|
Package parser provides a high-level SQL parser with functional options. |
|
parser/dialects
Package dialects implements SQL dialect parsers.
|
Package dialects implements SQL dialect parsers. |
|
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. |
|
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/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/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/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. |
|
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. |
Click to show internal directories.
Click to hide internal directories.