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ể

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`)

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

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).

12 KiB Raw Blame History

sqlc.yaml — Configuration Reference (Version 2)

Cấu trúc tổng thể

Các key cấp gốc (root-level)

Các key bên trong mỗi phần tử của sql[]

Các key bên trong gen.go

Cấu trúc của overrides[] (bên trong gen.go)

gen.json

gen.typescript