跳转到主要内容

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
sqlc 直接从 SQL 生成 Go 结构体和查询方法,因此您的应用程序代码调用的是普通的 Go 函数,而不是在运行时构建查询。在您的代码和您编写的 SQL 之间没有 ORM 层。本指南创建一个小型的 posts 表,用 sqlc 针对 MySQL 生成代码,并在一个真实运行的服务器上运行它。

安装 sqlc

使用 Homebrew 安装 sqlc;如果您希望将其作为 Go 工具管理,也可以使用 go install:
确认版本:

项目布局

创建一个 Go 模块和三个文件:一个 schema、一个查询文件和一个 sqlc 配置文件。
schema.sql 定义 sqlc 将从中生成类型的表。body 没有 NOT NULL 约束,这一点稍后会很重要:

编写带注解的查询

sqlc 读取普通的 SQL 文件,并将每条语句上方的 -- name: 注释转换为一个生成的 Go 方法。查询名称后面的词决定返回形式::one 返回单行,:many 返回切片,:exec 不返回值,:execresult 返回原始的 sql.Result,:execrows 返回受影响的行数。 MySQL 的 INSERT 语句不支持 RETURNING,因此要取回新行的 ID 需要一个专门的注解。:execlastid 会替您调用 sql.Result.LastInsertId() 并直接返回它:

配置 sqlc.yaml

sqlc.yaml 将 sqlc 指向 schema 文件和查询文件,并设置 MySQL 引擎。路径相对于 sqlc.yaml 所在的位置解析,而不是相对于您运行 sqlc 的目录:
package 和 out 指定生成的 Go 包名和写入目录。sql_package: "database/sql" 告诉 sqlc 针对标准库的 database/sql 生成代码,这正是 go-sql-driver/mysql 所实现的接口。

生成代码

这会在 posts/ 中生成三个文件:db.go(Queries 结构体及其构造函数)、models.go(Post 结构体)和 query.sql.go(每个带注解的查询对应一个方法)。可空的 body 列出现在 models.go 中:

可空列生成 sql.NullString,而不是指针

因为 body TEXT 没有 NOT NULL 约束,sqlc 为它生成了 sql.NullString,而不是普通的 string 或 *string。同样的规则适用于从 INSERT 语句的参数列表生成的 CreatePostParams:
这意味着每次插入都必须显式构造一个 sql.NullString,即使是为了传入一个值:
要插入一行没有正文的记录,请设置 Valid: false,而不是将字段留为空字符串。空的 sql.NullString{} 零值已经是 Valid: false,因此它等同于显式写 sql.NullString{Valid: false}:
读回可空列时,需要先检查 .Valid,再信任 .String:
如果某一列需要允许 NULL,请把它作为一个有意的 schema 决定。在 schema.sql 中为 body 添加 NOT NULL 并重新运行 sqlc generate,生成的字段会在所有出现的地方从 sql.NullString 变为普通的 string,从而移除每个调用点的 .Valid 检查。

连接并运行迁移

创建数据库和一个使用真实密码的应用程序用户,权限限定在该数据库内:
在运行应用程序之前,用 mysql 客户端应用 schema.sql:
添加驱动,并通过 TCP 使用 parseTime=true 连接;MySQL 的 TIMESTAMP 和 DATETIME 列需要该参数才能扫描到 Go 的 time.Time 中,而不是 []byte:

CreatePost 返回 int64,GetPost 接受 uint64

id BIGINT UNSIGNED 在 sqlc 将其作为列生成的所有地方都映射为 uint64,包括 GetPost 的 id 参数。但是用 :execlastid 生成的 CreatePost 返回的是普通的 int64。这来自 sql.Result.LastInsertId(),标准库将其定义为 int64,与列实际是否有符号无关。将刚创建的 ID 传入 GetPost 需要显式转换:
针对真实运行的服务器端到端运行完整程序:
直接对照数据库检查,不依赖程序自身的输出:

调优连接池

database/sql 在 sql.Open 之下管理自己的连接池,sqlc 生成的 Queries 结构体使用您传入的 *sql.DB 已有的连接池。对于 MySQL 后端,有两个设置尤其重要:
SetConnMaxLifetime 应设置为低于 MySQL 的 wait_timeout,该值在此服务器上默认为 28800 秒(8 小时)。如果不设置,MySQL 已在服务器端关闭的连接会作为空闲条目留在 Go 连接池中,直到针对其中某个连接的查询失败。

常见问题

sqlc 会针对真实运行的数据库运行吗?

只有在您显式启用时才会。sqlc generate 静态解析 schema.sql 和 query.sql,不需要正在运行的服务器。sqlc vet 和 sqlc push 可以连接到真实数据库进行额外检查,但本指南中的基本 generate 工作流从不打开连接。

如果 query.sql 中的某个查询有语法错误会怎样?

sqlc generate 会在生成任何内容之前失败,并给出指明文件和行号的解析错误。失败时不会向输出目录写入任何内容,因此有问题的查询永远不会产生过时或不完整的生成代码。

sqlc 可以为 INSERT … ON DUPLICATE KEY UPDATE 生成代码吗?

可以。sqlc 将其解析为普通的 INSERT 语句。根据您需要结果的哪一部分,用 :exec、:execresult、:execrows 或 :execlastid 注解它,与任何其他插入相同。

故障排除

另请参阅