A language-agnostic CLI that generates database-access code from PostgreSQL stored functions and procedures — consistent, customizable, and fully offline-capable.
- What is it · What's New · Install · Quick start · CLI commands · Why db-gen · Architecture · Development
- Reference docs: Usage & CLI · Configuration — every setting, grouped by area · Templating · Copy targets · Context mapping & generators · Validation · Examples / cookbook · Example templates · Feature inventory
See the annotated Docs index below for one-line descriptions of each.
db-gen connects to a PostgreSQL database, reads the metadata of your stored functions and procedures, and generates the boilerplate code that calls them — in whatever language and style your templates define. It is not an ORM: you keep writing SQL functions, and db-gen writes the typed call/mapping code around them.
Everything db-gen needs — configuration and templates — lives in your repository. The tool is a single self-contained executable with no runtime dependencies, no internet requirement, and no framework lock-in. The same binary generates the same code today and in five years.
Headline features:
- Language-agnostic — output is driven entirely by Go templates you control; C#, Go, Elixir, TypeScript, anything.
- DbContext / Models / Processors core generation, plus an extensible Additional Generators framework for any other output (TypeScript types, providers, WebSocket endpoints, …).
- Three-tier type mapping — distinct types for base, nullable returns, nullable params, and optional (DEFAULT) params.
- Context parameter injection — map
_user_id,created_by,tenant_id, … to a context object instead of threading them through call sites. - Copy targets — generate bulk-
COPY-into-staging-table code from a table's columns, language-agnostically. - Parameter security levels — tag parameters
none/secure/strict/omitso templates can generate secure logging (mask or omit sensitive values). - Schema change detection — see what changed in your routines and copy-target tables since the last generation.
- Offline generation — export routine metadata to JSON and generate without a database connection.
- Template variables. A new
TemplateVariablesconfig key holds a free-form string→string map that db-gen passes through to every template, read with the newtemplateVarfunction:{{templateVar .Config.TemplateVariables "GeneratedNs"}}. This lets one shared template set serve several projects that differ only in config — point each project'sdb-gen.jsonat its own namespaces and keep a single set of templates. Lookup is case-insensitive. See docs/configuration.md → template variables. - Parameter security levels. Each parameter now carries a logging-sensitivity level —
none(log plainly),secure(plain or masked depending on a runtime flag in your code),strict(always masked),omit(never logged) — exposed to templates asProperty.SecurityLevel.- How it works: you assign levels in config — globally by name (
ParameterSecurityMappings), as a project-wide default (DefaultParameterSecurityLevel, defaults tosecure), or per function (Functions[].Parameters[].SecurityLevel, highest precedence). db-gen resolves the effective level and hands it to your template; your template renders the masking, so the tool stays language-agnostic (same philosophy as copy targets). A template branches on$p.SecurityLevelto emit"******", a runtime-flag ternary, or the raw value — and dropsomitparams from the log line entirely. See docs/templating.md → parameter security levels.
- How it works: you assign levels in config — globally by name (
- Example templates. New top-level
examples/with anonymized, real-world-shaped starting points: a C#DbContext/Model/Processorset, acommon-providerthat turnsSecurityLevelinto safe log lines, and a per-routine TypeScript model. See examples/README.md. - Metadata contract test. A golden-file test (
test/e2e/templates/metadata.gotmpl→test/e2e/golden/metadata/contract.txt) dumps every field db-gen exposes to templates, so any change to the template-facing data model shows up as a reviewable diff. validatecommand.db-gen validatechecks your configuration and templates without generating anything: it verifies settings are consistent, parses every template, and — when a database is reachable — renders each against your real routines to catch field/method typos. Exits non-zero on error, so it drops straight into CI. Use--offlineto skip the database and render step. See docs/usage.md → validate.--llmreference.db-gen --llm(ordb-gen llm) prints one self-contained plain-text reference — concepts, every command and flag, the full config-key reference, the template data model, and template functions — for pasting into an LLM/AI coding assistant so it gets the whole tool in one shot. No database or config needed. See docs/usage.md → llm.- Bare invocation prints version. Running
db-genwith no arguments now prints build/version information above the help output.
- Copy targets — generic bulk-
COPYcode generation. Declare a staging table and db-gen emits the metadata (ordered columns, type, nullability, context/data split, format hint) a per-language template needs to write a correctCOPY ... FROM STDIN. No language specifics live in the tool. Schema drift on those tables is now reported ingenerateanddatabase-changesoutput, so a changed staging column is no longer silent. See docs/copy-targets.md. - Test framework. A three-layer suite (pure unit, DB-backed integration, golden-file e2e) plus
make test/test-unit/test-integration/test-force/test-update-golden. See test/README.md. - Security & toolchain (v0.7.1–v0.7.2). Upgraded
pgx/x/textand the Go toolchain to 1.25 to clear allgovulncheckfindings.
See CHANGELOG.md for the full history.
- 📘 Usage & CLI reference — commands, flags, config resolution, offline workflow, change detection.
- ⚙️ Configuration reference — every config key, defaults, and what it does.
- 🧩 Templating — template data model, functions, per-routine overrides, type mapping.
- 📦 Copy targets — bulk-
COPYmetadata contract and example templates. - 🔐 Context mapping & additional generators
- ✅ Validation
- 📚 Examples / cookbook — config recipes for common setups.
- 🎁 Example templates — anonymized, real-world-shaped C# & TypeScript templates to copy from.
- 🗂️ Feature inventory — every feature, its config key, default, and test coverage.
Download the latest db-gen-win.exe / db-gen-linux from the Releases page and commit it next to your code. Keeping the binary in the repo is intentional — in five years it will still be there and still generate identical code.
Or build from source (Go 1.21+):
go build -o db-gen-win.exe . # Windows
go build -o db-gen-linux . # LinuxThe fastest way to see it work is the bundled test/ setup:
- Create the test database from the migrations / SQL in
test/. - Copy
test/db-gen.jsonand set your connection string (alocal.db-gen.jsonoverride keeps secrets out of the committed config). - Run generation:
db-gen generate --config test/db-gen.jsonA minimal config:
{
"ConnectionString": "postgresql://user:pass@localhost:5432/mydb",
"OutputFolder": "./generated",
"DbContextTemplate": "./templates/dbcontext.gotmpl",
"GeneratedFileExtension": ".cs",
"GeneratedFileCase": "pascalcase",
"Generate": [{ "Schema": "public", "AllFunctions": true }],
"Mappings": [
{ "DatabaseTypes": ["int4"], "MappedType": "int", "MappingFunction": "GetInt32" },
{ "DatabaseTypes": ["text"], "MappedType": "string", "MappingFunction": "GetString" }
]
}See docs/usage.md for the full command surface and docs/examples.md for richer recipes.
| Command | What it does |
|---|---|
generate |
Connect, read routines, and generate code. Reports schema changes since last run. |
validate |
Check the config and templates (parse + render) without generating files. Exits non-zero on error. |
routines [out] |
Export routine metadata to JSON for offline generation. |
database-changes |
Show what changed in the database since the last generation. |
llm |
Print a full CLI reference (concepts, commands, config, template model) for LLM/AI assistants. Same as --llm. |
completion [shell] |
Emit a shell-completion script (bash, zsh, fish, powershell). |
version |
Print version / build information. |
Global flags: --config/-s (config file path), --connectionString/-c, --debug/-d, --llm (print the LLM reference). See docs/usage.md.
- Consistency over years — a small versioned binary outlives the frameworks and SaaS tools it replaces. We lost projects to LLBLGen + .NET framework churn; db-gen avoids that by depending on nothing external.
- In-house templates & config — generation is fully under your control and lives in the repo; nothing depends on an internet service or installed tool.
- Customization — any language, db driver, or logger; just edit the template. You can even swap templates per environment (e.g. strip dev-only logging) in CI/CD.
- Offline — air-gapped, security-sensitive, or 2nd-base-camp-on-K2 environments are fully supported. Export routines to JSON once, generate forever without a connection.
Standard Go CLI: main.go → cmd/ (Cobra commands) → private/dbGen (generation core), private/database (PostgreSQL access), private/helpers, private/version. The generation flow and a full diagram are in docs/usage.md → How it works.
go build -o db-gen-win.exe . # build
make test # all tests (DB-backed ones skip if no DB)
make test-unit # fast, pure-Go unit tests only
make test-integration # DB-backed integration + e2e
make test-force # all tests, ignoring the Go test cache
make test-update-golden # regenerate e2e golden files after intentional changesSee test/README.md for the test framework layout.
Proprietary to Keenmate unless a LICENSE file in this repository states otherwise.
Created by Keenmate. The field-naming behavior is kept consistent with the original ecto_gen tool.