VillageSQL is a drop-in replacement for MySQL with extensions.
All examples on this page work on VillageSQL. Install Now →
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:
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 注解它,与任何其他插入相同。
故障排除
另请参阅
- MySQL 与 ORM——sqlc 所替代的运行时构建查询的方法
- MySQL 中的 Schema 迁移——表进入生产环境后安全地为
schema.sql的变更做版本管理 - MySQL 连接池——超出
database/sql默认值的连接池大小设置和持久连接