Configuration
The sqlc
tool is configured via a sqlc.yaml
or sqlc.json
file. This file must be
in the directory where the sqlc
command is run.
Version 2
version: "2"
sql:
- schema: "postgresql/schema.sql"
queries: "postgresql/query.sql"
engine: "postgresql"
gen:
go:
package: "authors"
out: "postgresql"
- schema: "mysql/schema.sql"
queries: "mysql/query.sql"
engine: "mysql"
gen:
go:
package: "authors"
out: "mysql
sql
Each mapping in the sql
collection has the following keys:
engine
:Either
postgresql
ormysql
.
schema
:Directory of SQL migrations or path to single SQL file; or a list of paths.
queries
:Directory of SQL queries or path to single SQL file; or a list of paths.
gen
:A mapping to configure built-in code generators. Supports the following keys:
strict_function_checks
If true, return an error if a called SQL function does not exist. Defaults to
false
.
gen
The gen
mapping supports the following keys:
go
package
:The package name to use for the generated code. Defaults to
out
basename.
out
:Output directory for generated code.
sql_package
:Either
pgx/v4
ordatabase/sql
. Defaults todatabase/sql
.
emit_db_tags
:If true, add DB tags to generated structs. Defaults to
false
.
emit_prepared_queries
:If true, include support for prepared queries. Defaults to
false
.
emit_interface
:If true, output a
Querier
interface in the generated package. Defaults tofalse
.
emit_exact_table_names
:If true, struct names will mirror table names. Otherwise, sqlc attempts to singularize plural table names. Defaults to
false
.
emit_empty_slices
:If true, slices returned by
:many
queries will be empty instead ofnil
. Defaults tofalse
.
emit_exported_queries
:If true, autogenerated SQL statement can be exported to be accessed by another package.
emit_json_tags
:If true, add JSON tags to generated structs. Defaults to
false
.
emit_result_struct_pointers
:If true, query results are returned as pointers to structs. Queries returning multiple results are returned as slices of pointers. Defaults to
false
.
emit_params_struct_pointers
:If true, parameters are passed as pointers to structs. Defaults to
false
.
emit_methods_with_db_argument
:If true, generated methods will accept a DBTX argument instead of storing a DBTX on the
*Queries
struct. Defaults tofalse
.
emit_enum_valid_method
:If true, generate a Valid method on enum types, indicating whether a string is a valid enum value.
emit_all_enum_values
:If true, emit a function per enum type that returns all valid enum values.
json_tags_case_style
:camel
for camelCase,pascal
for PascalCase,snake
for snake_case ornone
to use the column name in the DB. Defaults tonone
.
output_db_file_name
:Customize the name of the db file. Defaults to
db.go
.
output_models_file_name
:Customize the name of the models file. Defaults to
models.go
.
output_querier_file_name
:Customize the name of the querier file. Defaults to
querier.go
.
output_files_suffix
:If specified the suffix will be added to the name of the generated files.
kotlin
package
:The package name to use for the generated code.
out
:Output directory for generated code.
emit_exact_table_names
:If true, use the exact table name for generated models. Otherwise, guess a singular form. Defaults to
false
.
python
package
:The package name to use for the generated code.
out
:Output directory for generated code.
emit_exact_table_names
:If true, use the exact table name for generated models. Otherwise, guess a singular form. Defaults to
false
.
emit_sync_querier
:If true, generate a class with synchronous methods. Defaults to
false
.
emit_async_querier
:If true, generate a class with asynchronous methods. Defaults to
false
.
emit_pydantic_models
:If true, generate classes that inherit from
pydantic.BaseModel
. Otherwise, define classes using thedataclass
decorator. Defaults tofalse
.
json
out
:Output directory for the generated JSON.
filename
:Filename for the generated JSON document. Defaults to
codegen_request.json
.
indent
:Indent string to use in the JSON document. Defaults to
Version 1
version: "1"
packages:
- name: "db"
path: "internal/db"
queries: "./sql/query/"
schema: "./sql/schema/"
engine: "postgresql"
emit_prepared_queries: true
emit_interface: false
emit_exact_table_names: false
emit_empty_slices: false
emit_exported_queries: false
emit_json_tags: true
emit_result_struct_pointers: false
emit_params_struct_pointers: false
emit_methods_with_db_argument: false
emit_enum_valid_method: false
emit_all_enum_values: false
json_tags_case_style: "camel"
output_db_file_name: "db.go"
output_models_file_name: "models.go"
output_querier_file_name: "querier.go"
packages
Each mapping in the packages
collection has the following keys:
name
:The package name to use for the generated code. Defaults to
path
basename.
path
:Output directory for generated code.
queries
:Directory of SQL queries or path to single SQL file; or a list of paths.
schema
:Directory of SQL migrations or path to single SQL file; or a list of paths.
engine
:Either
postgresql
ormysql
. Defaults topostgresql
.
sql_package
:Either
pgx/v4
ordatabase/sql
. Defaults todatabase/sql
.
emit_db_tags
:If true, add DB tags to generated structs. Defaults to
false
.
emit_prepared_queries
:If true, include support for prepared queries. Defaults to
false
.
emit_interface
:If true, output a
Querier
interface in the generated package. Defaults tofalse
.
emit_exact_table_names
:If true, struct names will mirror table names. Otherwise, sqlc attempts to singularize plural table names. Defaults to
false
.
emit_empty_slices
:If true, slices returned by
:many
queries will be empty instead ofnil
. Defaults tofalse
.
emit_exported_queries
:If true, autogenerated SQL statement can be exported to be accessed by another package.
emit_json_tags
:If true, add JSON tags to generated structs. Defaults to
false
.
emit_result_struct_pointers
:If true, query results are returned as pointers to structs. Queries returning multiple results are returned as slices of pointers. Defaults to
false
.
emit_params_struct_pointers
:If true, parameters are passed as pointers to structs. Defaults to
false
.
emit_methods_with_db_argument
:If true, generated methods will accept a DBTX argument instead of storing a DBTX on the
*Queries
struct. Defaults tofalse
.
emit_enum_valid_method
:If true, generate a Valid method on enum types, indicating whether a string is a valid enum value.
emit_all_enum_values
:If true, emit a function per enum type that returns all valid enum values.
json_tags_case_style
:camel
for camelCase,pascal
for PascalCase,snake
for snake_case ornone
to use the column name in the DB. Defaults tonone
.
output_db_file_name
:Customize the name of the db file. Defaults to
db.go
.
output_models_file_name
:Customize the name of the models file. Defaults to
models.go
.
output_querier_file_name
:Customize the name of the querier file. Defaults to
querier.go
.
output_files_suffix
:If specified the suffix will be added to the name of the generated files.
overrides
The default mapping of PostgreSQL/MySQL types to Go types only uses packages outside the standard library when it must.
For example, the uuid
PostgreSQL type is mapped to github.com/google/uuid
.
If a different Go package for UUIDs is required, specify the package in the
overrides
array. In this case, I’m going to use the github.com/gofrs/uuid
instead.
version: "1"
packages: [...]
overrides:
- go_type: "github.com/gofrs/uuid.UUID"
db_type: "uuid"
Each override document has the following keys:
db_type
:The PostgreSQL or MySQL type to override. Find the full list of supported types in postgresql_type.go or mysql_type.go. Note that for Postgres you must use the pg_catalog prefixed names where available.
go_type
:A fully qualified name to a Go type to use in the generated code.
go_struct_tag
:A reflect-style struct tag to use in the generated code, e.g.
a:"b" x:"y,z"
. If you want general json/db tags for all fields, useemit_db_tags
and/oremit_json_tags
instead.
nullable
:If true, use this type when a column is nullable. Defaults to
false
.
For more complicated import paths, the go_type
can also be an object.
version: "1"
packages: [...]
overrides:
- db_type: "uuid"
go_type:
import: "a/b/v2"
package: "b"
type: "MyType"
pointer: false # or true
Per-Column Type Overrides
Sometimes you would like to override the Go type used in model or query generation for a specific field of a table and not on a type basis as described in the previous section.
This may be configured by specifying the column
property in the override definition. column
should be of the form table.column
but you can be even more specific by specifying schema.table.column
or catalog.schema.table.column
.
version: "1"
packages: [...]
overrides:
- column: "authors.id"
go_type: "github.com/segmentio/ksuid.KSUID"
Package Level Overrides
Overrides can be configured globally, as demonstrated in the previous sections, or they can be configured on a per-package which scopes the override behavior to just a single package:
version: "1"
packages:
- overrides: [...]
rename
Struct field names are generated from column names using a simple algorithm: split the column name on underscores and capitalize the first letter of each part.
account -> Account
spotify_url -> SpotifyUrl
app_id -> AppID
If you’re not happy with a field’s generated name, use the rename
mapping
to pick a new name. The keys are column names and the values are the struct
field name to use.
version: "1"
packages: [...]
rename:
spotify_url: "SpotifyURL"