# sqlc.yaml — Configuration Reference (Version 2) sqlc sử dụng **Configuration Version 2** khi khai báo `version: "2"` ở đầu file. Dưới đây là bộ quy tắc và danh sách đầy đủ các key. --- ## Cấu trúc tổng thể ```yaml version: "2" sql: - engine: "" queries: "" schema: "" gen: go: package: "" out: "" ``` --- ## Các key cấp gốc (root-level) | Key | Kiểu | Bắt buộc | Mô tả | | ----------- | ----- | -------- | ------------------------------------------------------------------------ | | `version` | `"2"` | ✅ | Khai báo phiên bản cấu hình. Giá trị `"2"` cho Version 2. | | `sql` | list | ✅ | Danh sách các block cấu hình, mỗi block sinh code cho một ngôn ngữ đích. | | `overrides` | map | ❌ | (Deprecated v1) — Không dùng trong v2, thay bằng `gen..overrides`. | | `rename` | map | ❌ | (Deprecated v1) — Không dùng trong v2, thay bằng `gen..rename`. | --- ## Các key bên trong mỗi phần tử của `sql[]` | Key | Kiểu | Bắt buộc | Mô tả | | ------------------------ | ----------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `engine` | string | ✅ | CSDL mục tiêu. Giá trị: `"postgresql"`, `"mysql"`, `"sqlite"`. | | `queries` | string / string[] | ✅ | Đường dẫn tới thư mục/file chứa các query `.sql`. Có thể là mảng nhiều path. | | `schema` | string / string[] | ✅ | Đường dẫn tới thư mục/file chứa schema DDL (`.sql`). | | `strict_function_checks` | bool | ❌ | Nếu `true`, sqlc sẽ báo lỗi khi gọi function không tồn tại trong schema. Mặc định `false`. | | `strict_order_by` | bool | ❌ | Nếu `true`, yêu cầu tất cả column trong `ORDER BY` phải tồn tại. Mặc định `false` (chỉ cho PostgreSQL). | | `query_parameter_limit` | int | ❌ | Giới hạn số lượng parameter trong một query. Mặc định `1` (nếu > 1 thì sqlc ưu tiên sinh `sql.NamedArg`). Đặt `0` để bỏ giới hạn. | | `codegen` | list | ❌ | Danh sách cấu hình cho **plugin codegen** bên ngoài. Mỗi item có `out`, `plugin`, `options`. | | `gen` | map | ✅ (ít nhất 1) | Map các ngôn ngữ sinh code. Các key con: `go`, `kotlin`, `python`, `json`, `typescript`, `java`, `swift`, `rust`, `csharp`. | --- ## Các key bên trong `gen.go` | Key | Kiểu | Bắt buộc | Mô tả | | -------------------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------- | | `out` | string | ✅ | Thư mục output cho Go code sinh ra. | | `package` | string | ✅ | Tên Go package. | | `sql_package` | string | ❌ | Package SQL driver. Giá trị: `"database/sql"`, `"pgx/v4"`, `"pgx/v5"`, `"lib/pq"`. Mặc định `"database/sql"`. | | `sql_driver` | string | ❌ | Tên driver cụ thể, dùng để sinh import đúng. VD: `"github.com/jackc/pgx/v5/stdlib"`. | | `emit_json_tags` | bool | ❌ | Nếu `true`, sinh `json:"column_name"` tag cho struct field. Mặc định `false`. | | `emit_db_tags` | bool | ❌ | Nếu `true`, sinh `db:"column_name"` tag. Mặc định `false`. | | `emit_prepared_queries` | bool | ❌ | Nếu `true`, sinh method `Prepare` cho mỗi query. Mặc định `false`. | | `emit_interface` | bool | ❌ | Nếu `true`, sinh interface ` Querier` thay vì chỉ struct. Mặc định `false`. | | `emit_empty_slices` | bool | ❌ | Nếu `true`, trả về `[]T` rỗng thay vì `nil` khi không có row. Mặc định `false`. | | `emit_result_struct_pointers` | bool | ❌ | Sinh con trỏ `*T` cho result struct. Mặc định `false`. | | `emit_params_struct_pointers` | bool | ❌ | Sinh con trỏ `*T` cho params struct. Mặc định `false`. | | `emit_method_with_db_argument` | bool | ❌ | Nếu `true`, mỗi method nhận thêm `DB` argument, cho phép dùng transaction dễ hơn. Mặc định `false`. | | `emit_pointers_for_null_types` | bool | ❌ | Nếu `true`, dùng con trỏ cho null type thay vì `sql.Null*`. Mặc định `false`. | | `emit_enum_valid_method` | bool | ❌ | Sinh method `Valid()` cho enum type. Mặc định `false`. | | `emit_all_enum_values` | bool | ❌ | Sinh constant cho tất cả giá trị enum. Mặc định `false`. | | `emit_build_tags` | string | ❌ | Thêm Go build tag vào file sinh ra. VD: `"//go:build linux"`. | | `json_tags_case_style` | string | ❌ | Style cho JSON tag. Giá trị: `"camel"`, `"pascal"`, `"snake"`, `"none"`. Mặc định phụ thuộc vào `emit_json_tags`. | | `output_db_file_name` | string | ❌ | Tên file chứa `DB` struct. Mặc định `"db.go"`. | | `output_models_file_name` | string | ❌ | Tên file chứa model struct. Mặc định `"models.go"`. | | `output_querier_file_name` | string | ❌ | Tên file chứa interface. Mặc định `"querier.go"`. | | `output_files_suffix` | string | ❌ | Hậu tố cho file query. Mặc định `""`. VD: `"_sql"` → `user_sql.go`. | | `inflection_exclude_table_names` | list | ❌ | Danh sách tên table không áp dụng quy tắc số nhiều. VD: `["user"]`. | | `overrides` | list | ❌ | Ghi đè kiểu dữ liệu cho column cụ thể hoặc cho kiểu Go toàn cục (xem chi tiết bên dưới). | | `rename` | map | ❌ | Map đổi tên. Key = tên cần đổi, Value = tên mới. Dùng để rename struct field. | | `import` | string | ❌ | Import path của Go module dùng trong generated code. | --- ## Cấu trúc của `overrides[]` (bên trong `gen.go`) ```yaml overrides: - db_type: "uuid" go_type: "github.com/google/uuid.UUID" - db_type: "timestamptz" go_type: "time.Time" - column: "users.status" go_type: "UserStatus" go_struct_tag: tags: json: "status,omitempty" - db_type: "text" go_type: import: "github.com/lib/pq" type: "StringArray" nullable: true ``` | Key | Mô tả | | --------------- | ------------------------------------------------------------------------- | | `db_type` | Kiểu dữ liệu SQL cần ghi đè. Dùng cùng với `go_type`. | | `column` | Đường dẫn `"table.column"` cụ thể. Ưu tiên cao hơn `db_type`. | | `go_type` | Kiểu Go thay thế. Có thể là string hoặc object `{import, type, pointer}`. | | `nullable` | bool — Nếu `true`, áp dụng cho phiên bản nullable của kiểu. | | `go_struct_tag` | Custom struct tag cho field. | --- ## `gen.json` | Key | Kiểu | Bắt buộc | Mô tả | | ---------- | ------ | -------- | --------------------------------------------------- | | `out` | string | ✅ | Thư mục output file JSON. | | `indent` | string | ❌ | Ký tự indent. Mặc định `" "`. | | `filename` | string | ❌ | Tên file output. Mặc định `"codegen_request.json"`. | --- ## `gen.typescript` | Key | Kiểu | Bắt buộc | Mô tả | | ------------------- | ------ | -------- | ------------------------------------------------------ | | `out` | string | ✅ | Thư mục output. | | `plugin` | string | ❌ | Tên plugin (nếu dùng plugin ngoài). | | `runtime` | string | ❌ | Runtime cho generated code: `"node"` hoặc `"browser"`. | | `driver` | string | ❌ | Driver: `"pg"` hoặc `"pg-query-stream"`. | | `emit_json_tags` | bool | ❌ | Sinh JSON tag cho property. | | `emit_result_types` | bool | ❌ | Sinh interface cho result. | --- ## Ví dụ hoàn chỉnh ```yaml version: "2" sql: - engine: "postgresql" queries: "query/" schema: "schema/" gen: go: package: "db" out: "db" sql_package: "pgx/v5" emit_json_tags: true emit_interface: true emit_empty_slices: true emit_prepared_queries: false json_tags_case_style: "camel" overrides: - db_type: "uuid" go_type: "github.com/google/uuid.UUID" - db_type: "timestamptz" go_type: "time.Time" - column: "orders.status" go_type: import: "warehouse-management/types" type: "OrderStatus" pointer: true inflection_exclude_table_names: - "status" ``` --- **Tóm lại**: Key bắt buộc tối thiểu cho một config sqlc v2 hoạt động là `version`, `sql[].engine`, `sql[].queries`, `sql[].schema`, và ít nhất một block `gen.` với `out` + `package` (hoặc tương đương cho ngôn ngữ khác).