Base Project
This commit is contained in:
Tran Anh Tuan
170
docs/sqlc/config.md
Normal file
170
docs/sqlc/config.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 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: "<engine>"
|
||||
queries: "<path>"
|
||||
schema: "<path>"
|
||||
gen:
|
||||
go:
|
||||
package: "<name>"
|
||||
out: "<path>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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.<lang>.overrides`. |
|
||||
| `rename` | map | ❌ | (Deprecated v1) — Không dùng trong v2, thay bằng `gen.<lang>.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.<lang>` với `out` + `package` (hoặc tương đương cho ngôn ngữ khác).
|
||||
Reference in New Issue
Block a user