db-catalyst

module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Feb 7, 2026 License: MIT

README

db-catalyst

CI Security 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.

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 with go 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.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.
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.
examples
advanced command
advanced/db
advanced/types
complex command
complex/db
postgresql/db
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.
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/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/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 language-agnostic type representations and mappings between SQL types and programming language types.
 Package types provides language-agnostic type representations and mappings between SQL types and programming language types.

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.