From a2162fce1d8ec1669e5beec2af69066833b308ee Mon Sep 17 00:00:00 2001 From: Kyle Conroy Date: Wed, 1 Jun 2022 22:49:59 -0700 Subject: [PATCH] docs: Add documentation for version 2 of the configuration file --- docs/reference/config.md | 127 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 121 insertions(+), 6 deletions(-) diff --git a/docs/reference/config.md b/docs/reference/config.md index e87f999258..c405c81ca7 100644 --- a/docs/reference/config.md +++ b/docs/reference/config.md @@ -1,8 +1,123 @@ -# Configuration file (version 1) +# 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 + +```yaml +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 +``` + +Each mapping in the `sql` collection has the following keys: + +- `engine`: + - Either `postgresql` or `mysql`. +- `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: + - `go`: + - Go code generation options + - `kotlin`: + - Kotlin code generation options + - `python`: + - Python code generation options + - `json`: + - JSON output options +- `strict_function_checks` + - If true, return an error if a called SQL function does not exist. Defaults to `false`. + +### 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` or `database/sql`. Defaults to `database/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 to `false`. +- `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 of `nil`. Defaults to `false`. +- `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 to `false`. +- `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 or `none` to use the column name in the DB. Defaults to `none`. +- `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 the `dataclass` decorator. Defaults to `false`. + +### json + +## Version 1 + ```yaml version: "1" packages: @@ -28,16 +143,16 @@ packages: output_querier_file_name: "querier.go" ``` -Each package document has the following keys: +Each mapping in the `packages` collection has the following keys: - `name`: - - The package name to use for the generated code. Defaults to `path` basename + - The package name to use for the generated code. Defaults to `path` basename. - `path`: - - Output directory for generated code + - Output directory for generated code. - `queries`: - - Directory of SQL queries or path to single SQL file; or a list of paths + - 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 + - Directory of SQL migrations or path to single SQL file; or a list of paths. - `engine`: - Either `postgresql` or `mysql`. Defaults to `postgresql`. - `sql_package`: