SQLC项目中的schema变更验证工具verify详解

武朵欢Nerissa

于 2025-06-02 09:16:06 发布

阅读量234

点赞数 5

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00670/article/details/148377527

SQLC项目中的schema变更验证工具verify详解

sqlc sqlc-dev/sqlcsqlc-dev/sqlcli: 是一个用于 PostgreSQL 和 SQLite 数据库的跨平台命令行工具，它提供了一个简单易用的界面用于管理 PostgreSQL 和 SQLite 数据库。适合用于管理 PostgreSQL 和 SQLite 数据库，特别是对于需要轻量级、跨平台的数据库管理工具的场景。特点是轻量级、跨平台、支持 PostgreSQL 和 SQLite 数据库。项目地址: https://gitcode.com/gh_mirrors/sq/sqlc

什么是sqlc verify

在数据库应用开发中，schema变更和编写不当的查询语句常常会导致生产环境数据库故障。sqlc项目提供的verify命令（自v1.24.0版本引入）正是为了解决这一问题而设计。它能够在schema变更前，预先验证现有查询在新schema下的兼容性，有效避免潜在的生产事故。

为什么需要verify功能

传统的sqlc generate命令虽然能捕获一些基础问题，sqlc vet配合sqlc/db-prepare规则也能发现更多潜在问题，但这些工具都只能基于当前schema和查询进行分析。而实际开发中，我们经常面临的问题是：当schema变更后，生产环境中正在运行的现有查询可能会失败。

典型案例分析

假设生产环境中有以下两个表：

CREATE TABLE users (
  id UUID PRIMARY KEY
);

CREATE TABLE user_actions (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL,
  action TEXT,
  created_at TIMESTAMP
);

应用中有这样一个查询：

-- name: GetUserActions :many
SELECT * FROM users u
JOIN user_actions ua ON u.id = ua.user_id
ORDER BY created_at;

当开发者提议添加如下schema变更：

ALTER TABLE users ADD COLUMN created_at TIMESTAMP;

此时直接运行sqlc generate会失败，提示column reference "created_at" is ambiguous错误。开发者可能会修改查询为：

-- name: GetUserActions :many
SELECT * FROM users u
JOIN user_actions ua ON u.id = ua.user_id
ORDER BY u.created_at;

虽然这样修改解决了生成问题，但却隐藏着一个生产环境故障隐患：当schema变更应用后，现有的GetUserActions查询将开始失败。正确的做法应该是在应用schema迁移前先部署更新后的查询。

verify的工作原理

sqlc verify通过将当前schema和查询发送到云端服务，在那里针对新的schema变更运行查询，从而捕获现有查询与schema变更之间的不兼容问题。

对于上述案例，运行sqlc verify会明确提示ORDER BY "created_at"存在歧义：

$ sqlc verify
FAIL: app query.sql

=== Failed
=== FAIL: app query.sql GetUserActions
    ERROR: column reference "created_at" is ambiguous (SQLSTATE 42702)