pgxgen
pgxgen configuration file
| Type | object |
|---|---|
| File match |
pgxgen.yml
pgxgen.yaml
|
| Schema URL | https://catalog.lintel.tools/schemas/schemastore/pgxgen/latest.json |
| Source | https://raw.githubusercontent.com/tkcrm/pgxgen/refs/heads/master/schemas/pgxgen-schema.json |
Validate with Lintel
npx @lintel/lintel checkConfiguration file for pgxgen — code generator for PostgreSQL, MySQL, and SQLite. Replaces both pgxgen.yaml and sqlc.yaml.
Properties
Config schema version. Must be "2". Use pgxgen migrate to upgrade legacy v1 configs.
List of schema sources. Each schema is an independent generation unit with its own engine, migrations, models, and tables. Multiple schemas allow mixing engines (e.g. PostgreSQL + SQLite) in one project.
Optional user-provided template directories that override the built-in templates for CRUD SQL and Go models.
2 nested properties
Directory containing custom CRUD SQL templates. Files in this directory replace the built-in templates of the same name.
Directory containing custom Go model templates. Files in this directory replace the built-in templates of the same name.
Definitions
Human-readable schema name. Used in logs and to disambiguate output when multiple schemas are configured.
Database engine. Controls SQL dialect, type mapping, and the sqlc engine selected when generating sqlc.yaml.
Path to the directory (or single file) with SQL migration / schema files. Files are parsed in lexicographic order to derive table and column metadata.
14 nested properties
Directory where the generated Go models file will be written.
Go package name declared at the top of the generated models file.
Name of the generated models file. Defaults to models.go.
Full Go import path of the models package (e.g. github.com/your-org/project/internal/models). Used by sqlc overrides and by other generated code that needs to import these models.
Names of types defined manually in the models package. The generator skips emitting these names so your hand-written definitions are preserved.
Table or view names to exclude from model generation (e.g. internal migration tables).
Enum type names to exclude from model generation.
Add json:"…" struct tags to generated models.
Add db:"…" struct tags to generated models (useful for sqlx, scany, etc).
Use Go pointer types (*T) for nullable columns instead of nullable wrappers like pgtype.Text or sql.NullString.
Add // @name StructName comments above generated structs (useful for swaggo / Swagger generators).
SQL package used to choose the nullable / array type families in generated models (e.g. pgtype.Text vs sql.NullString).
Override the SQL → Go type mapping for the models generator. Affects only model structs (sqlc has its own sqlc.overrides.types).
Additional struct tags emitted on every generated model field. Combined with emit_json_tags / emit_db_tags.
Settings consumed when pgxgen generates .pgxgen/sqlc.yaml and runs sqlc.
3 nested properties
Keep .pgxgen/sqlc.yaml after the run. When false (default), the generated config and its containing directory are removed on both success and failure.
Default sqlc gen.go options applied to every generated repo. Maps 1:1 to sqlc's options of the same name.
14 nested properties
sqlc sql_package option — selects the driver-specific nullable / array types in generated sqlc code.
sqlc: emit prepared queries for performance.
sqlc: emit a Querier interface alongside the concrete Queries struct.
sqlc: add json:"…" struct tags to generated rows / params.
sqlc: add db:"…" struct tags to generated rows / params.
sqlc: export the constants holding the SQL text of each query.
sqlc: keep table names exact (no singularization). Off by default.
sqlc: emit empty slices instead of nil for :many queries that match no rows.
sqlc: return *Row instead of Row from generated queries.
sqlc: accept *Params instead of Params for generated queries with multi-field params.
sqlc: add a Valid() method on generated enum types.
sqlc: emit a slice with all values for each generated enum.
sqlc: maximum number of positional query parameters before sqlc switches the function signature to a single struct param.
sqlc: case style for json: tag values (camel, pascal, snake, or none).
Maps 1:1 to the sqlc overrides section. Lets you rename generated types and remap SQL types or specific columns.
3 nested properties
Rename generated identifiers (e.g. { d: Params } renames a struct named D to Params).
Override the Go type generated for a SQL type, optionally constrained to nullable columns.
Per-column overrides (e.g. add struct tags or change Go type for users.email).
Defaults inherited by every table in the schema. Choose one of two layouts: per-table repos (use *_prefix) OR a single shared repo (use queries_dir / output_dir).
8 nested properties
Per-table layout: queries directory is computed as {prefix}/{table_name}. Mutually exclusive with queries_dir. Not affected by package_prefix / package_suffix.
Per-table layout: sqlc output directory is computed as {prefix}/{package_prefix}{table_name}{package_suffix}. Mutually exclusive with output_dir.
Per-table layout: prefix prepended to the table name when forming the output directory and Go package name (e.g. repo_). Does not affect queries_dir_prefix.
Per-table layout: suffix appended to the table name when forming the output directory and Go package name (e.g. _repo). Does not affect queries_dir_prefix.
Single-repo layout: directory where every table's queries are placed. Mutually exclusive with queries_dir_prefix.
Single-repo layout: directory where every table's sqlc output is written. Mutually exclusive with output_dir_prefix.
Default CRUD generation settings inherited by every table.
3 nested properties
Remove stale generated CRUD files that no longer correspond to a configured method.
Drop the table name from generated method names (e.g. GetByID instead of GetUserByID).
Default method definitions applied to every table. Per-table tables.{name}.crud.methods overrides these key-by-key.
Default constants generation settings inherited by every table.
1 nested properties
Emit per-table column-name constants (e.g. UsersColumnEmail = "email").
Per-table configuration keyed by table name. Each entry merges with defaults and may override CRUD methods, constants, sqlc, and soft-delete settings.
Free-form SQL queries that are emitted alongside generated CRUD. Useful for joins, reports, or any query that does not fit the CRUD model.
Directory where the generated Go models file will be written.
Go package name declared at the top of the generated models file.
Name of the generated models file. Defaults to models.go.
Full Go import path of the models package (e.g. github.com/your-org/project/internal/models). Used by sqlc overrides and by other generated code that needs to import these models.
Names of types defined manually in the models package. The generator skips emitting these names so your hand-written definitions are preserved.
Table or view names to exclude from model generation (e.g. internal migration tables).
Enum type names to exclude from model generation.
Add json:"…" struct tags to generated models.
Add db:"…" struct tags to generated models (useful for sqlx, scany, etc).
Use Go pointer types (*T) for nullable columns instead of nullable wrappers like pgtype.Text or sql.NullString.
Add // @name StructName comments above generated structs (useful for swaggo / Swagger generators).
SQL package used to choose the nullable / array type families in generated models (e.g. pgtype.Text vs sql.NullString).
Override the SQL → Go type mapping for the models generator. Affects only model structs (sqlc has its own sqlc.overrides.types).
Additional struct tags emitted on every generated model field. Combined with emit_json_tags / emit_db_tags.
Settings consumed when pgxgen generates .pgxgen/sqlc.yaml and runs sqlc.
Keep .pgxgen/sqlc.yaml after the run. When false (default), the generated config and its containing directory are removed on both success and failure.
Default sqlc gen.go options applied to every generated repo. Maps 1:1 to sqlc's options of the same name.
14 nested properties
sqlc sql_package option — selects the driver-specific nullable / array types in generated sqlc code.
sqlc: emit prepared queries for performance.
sqlc: emit a Querier interface alongside the concrete Queries struct.
sqlc: add json:"…" struct tags to generated rows / params.
sqlc: add db:"…" struct tags to generated rows / params.
sqlc: export the constants holding the SQL text of each query.
sqlc: keep table names exact (no singularization). Off by default.
sqlc: emit empty slices instead of nil for :many queries that match no rows.
sqlc: return *Row instead of Row from generated queries.
sqlc: accept *Params instead of Params for generated queries with multi-field params.
sqlc: add a Valid() method on generated enum types.
sqlc: emit a slice with all values for each generated enum.
sqlc: maximum number of positional query parameters before sqlc switches the function signature to a single struct param.
sqlc: case style for json: tag values (camel, pascal, snake, or none).
Maps 1:1 to the sqlc overrides section. Lets you rename generated types and remap SQL types or specific columns.
3 nested properties
Rename generated identifiers (e.g. { d: Params } renames a struct named D to Params).
Override the Go type generated for a SQL type, optionally constrained to nullable columns.
Per-column overrides (e.g. add struct tags or change Go type for users.email).
Defaults inherited by every table in the schema. Choose one of two layouts: per-table repos (use *_prefix) OR a single shared repo (use queries_dir / output_dir).
Per-table layout: queries directory is computed as {prefix}/{table_name}. Mutually exclusive with queries_dir. Not affected by package_prefix / package_suffix.
Per-table layout: sqlc output directory is computed as {prefix}/{package_prefix}{table_name}{package_suffix}. Mutually exclusive with output_dir.
Per-table layout: prefix prepended to the table name when forming the output directory and Go package name (e.g. repo_). Does not affect queries_dir_prefix.
Per-table layout: suffix appended to the table name when forming the output directory and Go package name (e.g. _repo). Does not affect queries_dir_prefix.
Single-repo layout: directory where every table's queries are placed. Mutually exclusive with queries_dir_prefix.
Single-repo layout: directory where every table's sqlc output is written. Mutually exclusive with output_dir_prefix.
Default CRUD generation settings inherited by every table.
3 nested properties
Remove stale generated CRUD files that no longer correspond to a configured method.
Drop the table name from generated method names (e.g. GetByID instead of GetUserByID).
Default method definitions applied to every table. Per-table tables.{name}.crud.methods overrides these key-by-key.
Default constants generation settings inherited by every table.
1 nested properties
Emit per-table column-name constants (e.g. UsersColumnEmail = "email").
Per-table overrides. Anything omitted here is inherited from the schema's defaults.
Name of the primary-key column. Used by CRUD methods like get, update, delete to build the WHERE clause when no explicit where is set.
Override the queries directory for this table (otherwise resolved from defaults.queries_dir / defaults.queries_dir_prefix).
Override the sqlc output directory for this table (otherwise resolved from defaults.output_dir / defaults.output_dir_prefix).
Per-table sqlc options that override sqlc.defaults for this table only.
1 nested properties
sqlc query_parameter_limit for this table only.
1 nested properties
CRUD methods to generate for this table. Method keys are well-known: create, update, delete, get, find, total, exists, batch_create. An empty object ({}) enables a method with default settings.
1 nested properties
Override defaults.constants.include_column_names for this table.
Enable soft-delete behavior. The delete method becomes an UPDATE that sets the column to now(); get and find automatically add WHERE {column} IS NULL.
1 nested properties
Name of the soft-delete timestamp column (commonly deleted_at).
CRUD method definition. null or {} enables the method with default settings derived from the table.
Override the generated Go method name (e.g. GetByID).
RETURNING clause for INSERT/UPDATE/DELETE (PostgreSQL only). Use * to return all columns.
WHERE conditions keyed by column name. An empty object ({}) means column = $N. Use value/operator to customize.
Additional raw SQL conditions appended to the WHERE clause (e.g. "status = 'active'"). Combined with AND.
Columns to omit from this method's INSERT/UPDATE column list (e.g. [id, created_at]).
Override the generated value for specific columns with a literal SQL expression (e.g. { created_at: "now()" }). Such columns are filled by SQL instead of Go.
For find: emit LIMIT $N OFFSET $N and accept the corresponding parameters.
ORDER BY clause for find.
2 nested properties
Column name to order by.
Sort direction. Defaults to DESC.
Free-form SQL query emitted alongside generated CRUD.
Generated Go function name (e.g. GetActiveUsers).
sqlc query annotation: one (single row), many (slice of rows), exec (no result), copyfrom (PostgreSQL COPY FROM).
The SQL body. Use $1, $2, … for PostgreSQL parameters or ? for MySQL/SQLite.
Optional table name. When set, the query is emitted into that table's resolved queries_dir and uses its row type.
Explicit output directory for the query. Takes precedence over table.