README
¶
sqlc-gen-queries
A CLI tool that generates sqlc-compatible SQL queries from your database schema catalog. Point it at a schema catalog and a configuration file, and it produces ready-to-use query files for sqlc.
Features
- Generate CRUD queries (
SELECT,INSERT,UPDATE,DELETE) from a database schema catalog - Primary key CRUD and FK-based List operations generated by default — no configuration needed
- Opt-in to additional queries (Copy, FK joins, non-FK index queries) via
queriesallowlist - Configurable via YAML — shares the same
sqlc.yamlconfiguration file - Works as a standalone CLI or as part of a CI/CD pipeline
- Supports custom query templates
Installation
go install github.com/sqlc-contrib/sqlc-gen-queries/cmd/sqlc-gen-queries@latest
Schema Catalog
The --catalog-file (schema.json by default) is a JSON representation of your
database schema. Generate it using Atlas, an
open-source schema management tool:
atlas schema inspect \
--url "postgres://user:pass@localhost:5432/mydb?sslmode=disable" \
--format '{{ json . }}' > schema.json
This produces a JSON catalog containing tables, columns, indexes, primary keys,
foreign keys, and other schema metadata that sqlc-gen-queries uses to generate
queries.
Configuration
sqlc-gen-queries reads configuration from the same sqlc.yaml file used by
sqlc. To share the config file without sqlc rejecting
unknown keys, register a dummy plugin with true as the command:
version: "2"
plugins:
- name: gen-queries
process:
cmd: "true"
sql:
- schema: "schema/migration"
queries: "ent/query"
engine: "postgresql"
codegen:
- plugin: gen-queries
out: "ent/query"
options:
queries:
- "CopyUsers"
- "GetUserWithPost"
Default queries (always generated)
Primary key CRUD operations, List queries (including FK-index-based list queries), and their Exec/Batch variants are generated automatically for every table:
| Query | Description |
|---|---|
Get<Table> |
Select a row by primary key |
BatchGet<Tables> |
Batch select rows by primary key |
List<Tables> |
Paginated list with filtering |
List<Tables>By<Columns> |
Paginated list by foreign key index |
Insert<Table> |
Insert a row |
ExecInsert<Table> |
Insert a row (exec, returns affected rows) |
BatchInsert<Tables> |
Batch insert rows |
BatchExecInsert<Tables> |
Batch insert rows (exec) |
Update<Table> |
Update a row by primary key |
ExecUpdate<Table> |
Update a row by primary key (exec) |
BatchUpdate<Tables> |
Batch update rows by primary key |
BatchExecUpdate<Tables> |
Batch update rows by primary key (exec) |
Delete<Table> |
Delete a row by primary key |
ExecDelete<Table> |
Delete a row by primary key (exec) |
BatchDelete<Tables> |
Batch delete rows by primary key |
BatchExecDelete<Tables> |
Batch delete rows by primary key (exec) |
Opt-in queries
These queries are only generated when explicitly listed in options.queries:
| Query | Description |
|---|---|
Copy<Tables> |
Bulk insert via PostgreSQL COPY protocol |
Get<Table>With<Related> |
Select with FK join |
BatchGet<Tables>With<Related> |
Batch select with FK join |
Get<Table>By<Columns> |
Select by non-PK unique index |
List<Tables>By<Columns> |
Paginated list by non-FK non-unique index |
Update<Tables>By<Columns> |
Update by non-unique index |
Delete<Tables>By<Columns> |
Delete by non-unique index |
All opt-in queries also have their Exec/Batch/BatchExec variants available.
Usage
Run sqlc-gen-queries before sqlc generate so that the generated .sql
query files are available for sqlc to produce Go code:
sqlc-gen-queries --config-file sqlc.yaml --catalog-file schema.json
sqlc generate
| Flag | Environment Variable | Default | Description |
|---|---|---|---|
--config-file |
SQLC_CONFIG_FILE |
sqlc.yaml |
Path to the sqlc configuration file |
--catalog-file |
SQLC_CATALOG_FILE |
schema.json |
Path to the catalog file |
Contributing
Contributions are welcome! Please open an issue or pull request.
To set up a development environment with Nix:
nix develop
go test ./...
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
sqlc-gen-queries
command
|
|
|
internal
|
|
|
sqlc
Package sqlc provides data structures for working with sqlc catalog files.
|
Package sqlc provides data structures for working with sqlc catalog files. |
|
sqlc/template
Package template provides embedded SQL templates for code generation.
|
Package template provides embedded SQL templates for code generation. |