docs: Add documentation for version 2 of the configuration file (#1657)

sqlc-dev · Jun 2, 2022 · ae66700 · ae66700
1 parent b0d6f13
commit ae66700
Showing 1 changed file with 121 additions and 6 deletions.
diff --git 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`: