Code-first：GORM#

type User struct {
  ID    uint   `gorm:"primaryKey"`
  Email string `gorm:"uniqueIndex"`
  Posts []Post
}

db.Where("email = ?", email).First(&user)

真相源是 Go struct。你改了 struct，跑一下 AutoMigrate，数据库跟着变。问题是：Go struct 能表达的东西远比 SQL schema 少。分区表、部分索引、CHECK 约束、物化视图——这些在 struct tag 里根本没法写。而且 db.Where("email = ?", email) 里的 "email" 是个字符串，拼错了编译器不管，运行时才炸。

Schema-first：Ent#

func (User) Fields() []ent.Field {
  return []ent.Field{
    field.Int("id"),
    field.String("email").Unique(),
  }
}

真相源是 Go 的 schema DSL。跑 go generate，Ent 帮你生成查询代码、迁移 SQL、甚至 GraphQL resolver。类型安全做得很好，但代价是生成代码量巨大（一个实体可能生成上千行），而且你被锁在 Ent 的查询 API 里——想写个窗口函数或者递归 CTE？得跳出框架用 raw SQL。

SQL-first：sqlc#

-- schema.sql
CREATE TABLE users (
  id   BIGSERIAL PRIMARY KEY,
  email TEXT NOT NULL UNIQUE
);

-- query.sql
-- name: GetUser :one
SELECT id, email FROM users WHERE id = $1;

真相源是 SQL 本身。你写的就是真正的 SQL——能在 psql 里直接跑的那种。sqlc 读这些文件，验证语法和类型，生成对应的 Go 函数。

这个选择的后果是深远的：

• 表达力接近原生 SQL。CTE、窗口函数、LATERAL JOIN、递归查询、JSON 操作符这类常见高级特性都能直接写。少数复杂语句可能仍受 sqlc analyzer / codegen 能力限制，但你不需要被 ORM 的查询 API 绑住。
• SQL 就是文档。新人看 query.sql 就知道这个服务跟数据库之间的所有交互，不用在代码里翻 ORM 调用链。
• DBA 友好。DBA 可以直接审查 .sql 文件，不用理解 Go 代码。
• 可测试。.sql 文件可以直接在数据库客户端里跑，不需要启动 Go 程序。

Parser：不是正则，是真正的 PostgreSQL parser#

这是 sqlc 最硬核的设计决策之一。

v1.25.0 之前，sqlc 通过 cgo 调用 pganalyze/pg_query_go——这是 PostgreSQL 源码里的 parser 编译成的 C 库。好处是语法兼容度高，坏处是需要 C 编译器，Windows 上很痛苦。

v1.25.0 起，sqlc 切换到 wasilibs/go-pgquery——把同一个 C parser 编译成 WebAssembly，通过 tetratelabs/wazero（纯 Go 的 WASM 运行时）执行。它把构建和分发成本降了下来：

• 纯 Go 编译，零 cgo 依赖
• Windows、macOS、Linux 原生支持
• 交叉编译无障碍

为什么这很重要？ 因为用真实的 PostgreSQL parser 意味着 sqlc 不是靠正则去猜 SQL。CREATE TABLE ... PARTITION BY、WITH RECURSIVE、LATERAL JOIN、jsonb_path_query 这类 PostgreSQL 语法，parser 都有机会按数据库的规则理解。如果你写了一条语法错误的 SQL，sqlc 会在 generate 阶段就告诉你，而不是等到运行时数据库报错。

MySQL 使用 TiDB 生态的 parser，SQLite 也有自己的方言分析实现；v1.25.0 同时把连接 SQLite 数据库的依赖从 mattn/go-sqlite3 换成了 modernc.org/sqlite，减少 cgo 依赖。重点不是“一套 parser 吃所有方言”，而是按数据库引擎分别处理。

Compiler：从 AST 到类型信息#

Parser 输出 AST 之后，internal/compiler/ 包接手做两件事：

1. Schema 分析：读 schema.sql，建立一个内存中的 catalog——哪些表、哪些列、什么类型、哪些约束。这就是 sqlc 的”数据库”。

2. Query 分析：对每条查询的 AST 做类型推导：

• SELECT id, email FROM users WHERE id = $1 → 参数 $1 的类型是 bigint（因为 users.id 是 BIGSERIAL），返回值是 (int64, string)
• SELECT count(*) FROM users → 返回值是 int64
• SELECT u.*, p.title FROM users u JOIN posts p ON ... → 返回值是 users 的所有列 + posts.title

v1.23.0 起还支持数据库辅助分析：连接到真实数据库获取元数据，解决静态分析搞不定的场景（比如自定义函数的返回类型、复杂聚合表达式）。

基本映射#

sqlc 内置了一套 SQL 类型到 Go 类型的映射表：

Nullable 处理#

这是每个数据库工具都要面对的问题：SQL 里的 NULL 在 Go 里怎么表示？

sqlc 的默认策略是用 database/sql 的 Null 类型：

-- name: GetUser :one
SELECT id, email, bio FROM users WHERE id = $1;

如果 bio 列是 TEXT（可空），生成的 struct 是：

type GetUserRow struct {
  ID    int64
  Email string
  Bio   sql.NullString  // 可空列
}

如果你使用 pgx/v5 或 SQLite，也可以在 sqlc.yaml 里配置用指针代替：

gen:
  go:
    sql_package: "pgx/v5"
    emit_pointers_for_null_types: true

这样 Bio 就变成 *string。如果还是默认的 database/sql，可空字段会继续使用 sql.NullString 这类类型。或者用第三方库：

overrides:
  - db_type: "text"
    nullable: true
    go_type:
      import: "gopkg.in/guregu/null.v4"
      package: "null"
      type: "String"

自定义类型映射#

sqlc 的 override 系统允许你精确控制类型映射：

overrides:
  - db_type: "uuid"
    go_type:
      import: "github.com/google/uuid"
      type: "UUID"
  - column: "users.created_at"
    go_type: "time.Time"
  - db_type: "pg_catalog.timestamptz"
    nullable: true
    go_type:
      import: "gopkg.in/guregu/null.v4"
      package: "null"
      type: "Time"

可以按 db_type（全局）或 column（精确到某张表的某列）来配置。这比 GORM 的 struct tag 灵活得多——你不需要在每个用到 UUID 的 struct 上都加 tag，配置一次全局生效。

枚举类型#

PostgreSQL 的 CREATE TYPE ... AS ENUM 会被 sqlc 生成为带常量的 Go 类型：

CREATE TYPE status AS ENUM ('active', 'inactive', 'banned');

生成：

type Status string

const (
  StatusActive   Status = "active"
  StatusInactive Status = "inactive"
  StatusBanned   Status = "banned"
)

编译期就能检查你有没有传一个不存在的枚举值。

零运行时开销意味着什么#

盯着生成的代码看一眼，你会发现：

• SQL 是常量字符串。const getAuthor = "SELECT ..." 在编译期就确定了，运行时不做任何拼接。
• 参数直接传递。q.db.QueryRowContext(ctx, getAuthor, id) 里的 id 从生成函数签名开始就是 int64，参数类型在编译期已确定，不经过 ORM 反射层。
• 结果直接 Scan。row.Scan(&i.ID, &i.Name, &i.Bio) 是 database/sql 最原始的用法，没有反射、没有 struct tag 查找。
• 没有 sqlc 的运行时依赖。这个例子里的生成代码只 import database/sql 和 context。你甚至可以删掉 sqlc，生成的代码照样编译运行。

这就是”零运行时开销”的含义：生成的代码接近你会手写的 database/sql 代码。sqlc 的主要工作都在 generate 阶段完成，业务运行时不需要加载一个 sqlc 框架。

GORM：反射的代价#

var user User
db.Where("email = ?", email).First(&user)

这一行背后发生了什么：

1. Where("email = ?", email) — 运行时拼接 SQL 字符串
2. First(&user) — 通过反射检查 User struct 的字段和 tag，确定 SELECT 哪些列
3. 结果返回后，再通过反射把每列的值填到 struct 对应字段里
4. 如果有 hook（BeforeFind、AfterFind），还要通过反射检查并调用

每次查询都要走这套反射流程。简单场景下网络延迟远大于反射开销，但在高并发、大结果集的场景下，GORM 的 CPU 开销是 raw database/sql 的 2-5 倍。

更关键的问题是类型安全："email = ?" 里的 email 是字符串，拼错了编译器不管。字段改名了，全局搜索替换是唯一的办法。

Ent：生成代码的膨胀#

user, err := client.User.
  Query().
  Where(user.EmailEQ(email)).
  Only(ctx)

Ent 的类型安全做得很好——user.EmailEQ 是生成的函数，拼错了编译不过。但代价是：

• 一个实体可能生成上千行代码（包括各种 predicate、edge traversal、mutation）
• 查询 API 是 Ent 自己的，不是 SQL。想写窗口函数？得用 ent/dialect/sql，回到拼字符串
• 关系查询生成的 SQL 往往比手写的复杂，即使是简单场景

Ent 适合关系密集、需要 GraphQL 集成的场景。但如果你的需求是”写 SQL，类型安全”，它的抽象层太厚了。

sqlx：运行时的 struct tag#

var user User
err := db.Get(&user, "SELECT id, email, bio FROM users WHERE id = $1", id)

sqlx 是最轻量的选择——它就是 database/sql 加了个 struct 扫描。但：

• "SELECT id, email, bio FROM users WHERE id = $1" 是字符串，没有编译期验证
• struct tag db:"email" 拼错了，运行时才报错（而且报错信息不一定明显）
• 每次 Get / Select 都要通过反射读 struct tag，虽然有缓存但仍有开销

sqlx 的定位是”比 raw SQL 少写点代码”，但它不解决类型安全问题。

squirrel：查询构建器#

query, args, _ := sq.Select("id", "email").
  From("users").
  Where(sq.Eq{"id": id}).
  ToSql()

row := db.QueryRow(query, args...)

squirrel 解决的是动态拼 SQL 的问题——比字符串拼接安全，比 fmt.Sprintf 优雅。但：

• 零类型安全。"id"、"email"、"users" 全是字符串
• 结果还是要手动 Scan
• 每次调用都在运行时构建 SQL 字符串

squirrel 适合查询条件高度动态的场景，但它和 sqlc 解决的是不同的问题。

对比总结#

sqlc.embed：JOIN 结果的优雅组织#

多表 JOIN 的结果默认是扁平的——所有列混在一个 struct 里。sqlc.embed 让你把结果组织成嵌套 struct：

-- name: GetStudentWithScores :many
SELECT sqlc.embed(students), sqlc.embed(test_scores)
FROM students
JOIN test_scores ON test_scores.student_id = students.id
WHERE students.id = $1;

生成：

type GetStudentWithScoresRow struct {
  Student   Student
  TestScore TestScore
}

比起手动定义一个包含所有列的扁平 struct，这种方式更清晰，而且 Student 和 TestScore 可以复用 models.go 里已有的类型。

sqlc.slice：动态 IN 查询#

-- name: GetUsersByIDs :many
SELECT * FROM users WHERE id IN (sqlc.slice('ids'));

生成的函数接受 []int64 参数，sqlc 在运行时展开成正确数量的占位符。

注意：这是 sqlc 为数不多的运行时开销场景。因为 IN 的参数数量是动态的，无法在编译期确定占位符数量，必须在运行时构建 SQL 字符串。这是为了实用性做的权衡——动态 IN 查询太常见了。

Prepared Statements#

非 pgx/v5 驱动需要先开启配置：

gen:
  go:
    emit_prepared_queries: true

queries, err := db.Prepare(ctx, conn)
if err != nil {
  return err
}
// 后续调用复用预编译的 statement
user, err := queries.GetAuthor(ctx, authorID)

开启 emit_prepared_queries 后，sqlc 生成的 Prepare 函数会一次性预编译所有查询。如果使用 pgx/v5，pgx 自身已经有隐式 prepared statement 支持，不需要额外开启这个 sqlc 选项。

WASM 插件系统#

v1.23.0 起，sqlc 把代码生成器抽成了独立的 WASM 插件。sqlc-gen-go 本身就是一个插件：

version: "2"
plugins:
  - name: golang
    wasm:
      url: "https://downloads.sqlc.dev/plugin/sqlc-gen-go_v1.4.0.wasm"
      sha256: "..."
sql:
  - schema: "schema.sql"
    queries: "query.sql"
    engine: "postgresql"
    codegen:
      - plugin: golang
        out: "db"
        options:
          package: "db"
          sql_package: "pgx/v5"

WASM 插件运行在沙箱里——没有文件系统访问、没有网络、没有环境变量（除非显式授权）。这意味着社区可以安全地开发和分发插件，不用担心供应链攻击。

目前已有 Go、Python、Kotlin、TypeScript 的官方插件，社区还有 PHP、Zig 等语言的实现。

sqlc vet：SQL 静态分析#

rules:
  - name: no-delete-without-where
    message: "DELETE without WHERE is dangerous"
    rule: |
      query.sql.matches("(?is).*\\bdelete\\s+from\\b.*") &&
      !query.sql.matches("(?is).*\\bwhere\\b.*")

sqlc vet 用 CEL（Common Expression Language）定义规则，可以在 CI 里跑，防止危险的 SQL 模式进入代码库。配合数据库连接还能跑 EXPLAIN，检查查询计划是否合理。