https://github.com/sqlc-contrib/sqlc-gen-queries
A query generation tool that produces sqlc-compatible SQL from your database schema.
https://github.com/sqlc-contrib/sqlc-gen-queries
cli generator sqlc
Last synced: 5 months ago
JSON representation
A query generation tool that produces sqlc-compatible SQL from your database schema.
- Host: GitHub
- URL: https://github.com/sqlc-contrib/sqlc-gen-queries
- Owner: sqlc-contrib
- License: mit
- Created: 2025-11-24T10:53:32.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-02-02T01:58:10.000Z (6 months ago)
- Last Synced: 2026-02-02T11:36:10.152Z (6 months ago)
- Topics: cli, generator, sqlc
- Language: Go
- Homepage:
- Size: 883 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# sqlc-gen-queries
[](https://github.com/sqlc-contrib/sqlc-gen-queries/actions/workflows/ci.yml)
[](https://github.com/sqlc-contrib/sqlc-gen-queries/releases)
[](LICENSE)
[](https://go.dev)
[](https://sqlc.dev)
[](https://github.com/sqlc-contrib/sqlc-gen-queries/actions/workflows/ci.yml)
A CLI tool that generates [sqlc](https://sqlc.dev)-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 operations generated by default — no configuration needed
- Opt-in to additional queries (List, Copy, FK joins, non-unique index queries) via `queries` allowlist
- Configurable via YAML — shares the same `sqlc.yaml` configuration file
- Works as a standalone CLI or as part of a CI/CD pipeline
- Supports custom query templates
## Installation
```bash
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](https://github.com/ariga/atlas), an
open-source schema management tool:
```bash
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](https://sqlc.dev). To share the config file without sqlc rejecting
unknown keys, register a dummy plugin with `true` as the command:
```yaml
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:
- "ListUsers"
- "CopyUsers"
- "GetUserWithPost"
```
### Default queries (always generated)
Primary key CRUD operations and their Exec/Batch variants are generated
automatically for every table:
| Query | Description |
| ------------------------- | ------------------------------------------ |
| `Get` | Select a row by primary key |
| `BatchGet` | Batch select rows by primary key |
| `Insert` | Insert a row |
| `ExecInsert` | Insert a row (exec, returns affected rows) |
| `BatchInsert` | Batch insert rows |
| `BatchExecInsert` | Batch insert rows (exec) |
| `Update` | Update a row by primary key |
| `ExecUpdate` | Update a row by primary key (exec) |
| `BatchUpdate` | Batch update rows by primary key |
| `BatchExecUpdate` | Batch update rows by primary key (exec) |
| `Delete` | Delete a row by primary key |
| `ExecDelete` | Delete a row by primary key (exec) |
| `BatchDelete` | Batch delete rows by primary key |
| `BatchExecDelete` | Batch delete rows by primary key (exec) |
### Opt-in queries
These queries are only generated when explicitly listed in `options.queries`:
| Query | Description |
| ------------------------------- | ---------------------------------------- |
| `List` | Paginated list with filtering |
| `Copy` | Bulk insert via PostgreSQL COPY protocol |
| `GetWith` | Select with FK join |
| `BatchGetWith` | Batch select with FK join |
| `GetBy` | Select by non-PK unique index |
| `ListBy` | Paginated list by non-unique index |
| `UpdateBy` | Update by non-unique index |
| `DeleteBy` | 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:
```bash
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](https://nixos.org):
```bash
nix develop
go test ./...
```
## License
[MIT](LICENSE)