SQLC项目中的查询校验工具：深入理解sqlc vet

SQLC项目中的查询校验工具：深入理解sqlc vet

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

什么是sqlc vet

SQLC项目提供了一个强大的查询校验工具sqlc vet，它允许开发者对SQL查询进行静态分析和规则检查。这个功能自v1.19.0版本引入，为SQL查询的质量控制提供了专业级的解决方案。

核心功能解析

sqlc vet的核心功能是通过自定义规则对SQL查询进行静态检查。这些规则使用CEL(Common Expression Language)表达式定义，能够访问查询的元数据和执行计划信息。

规则定义基础

在SQLC配置文件中，规则由三部分组成：

1. 名称(name)：规则的唯一标识符
2. 消息(message)：当规则触发时显示的错误信息
3. 规则(rule)：使用CEL语言编写的表达式

规则可以访问两种主要数据结构：

• Config：包含SQLC配置信息
• Query：包含查询的SQL文本、名称、命令类型和参数

基础规则示例

以下是一些实用的基础规则示例：

rules:
  - name: no-delete
    message: "删除操作存在风险，请谨慎使用"
    rule: "query.sql.contains('DELETE')"
  
  - name: limit-params
    message: "参数数量不应超过3个"
    rule: "query.params.size() > 3"
  
  - name: require-select
    message: "只允许使用SELECT查询"
    rule: "!query.sql.contains('SELECT')"

高级功能：利用EXPLAIN分析

自v1.20.0版本起，sqlc vet支持通过数据库的EXPLAIN命令获取查询执行计划，这为编写更复杂的校验规则提供了可能。

执行计划分析原理

SQLC会根据配置的数据库引擎自动执行相应的EXPLAIN命令：

• PostgreSQL：执行EXPLAIN (ANALYZE false, VERBOSE, COSTS, SETTINGS, BUFFERS, FORMAT JSON)
• MySQL：执行EXPLAIN FORMAT=JSON

执行结果会被解析为结构化的数据，可以在CEL表达式中通过postgresql.explain或mysql.explain变量访问。

执行计划规则示例

rules:
  - name: postgresql-cost-check
    message: "查询成本过高，请优化"
    rule: "postgresql.explain.plan.total_cost > 5.0"
  
  - name: mysql-index-check
    message: "查询未使用索引"
    rule: "has(mysql.explain.query_block.table.key) && mysql.explain.query_block.table.key == ''"

内置规则：sqlc/db-prepare

SQLC提供了一个开箱即用的内置规则sqlc/db-prepare，它会尝试在实际数据库中预处理所有查询，确保语法正确性。

sql:
  - schema: "schema.sql"
    queries: "query.sql"
    database:
      uri: "postgresql://user:pass@localhost/db"
    rules:
      - sqlc/db-prepare

规则管理技巧

选择性禁用规则

对于特定查询，可以使用注释临时禁用某些规则检查：

/* name: GetUser :one */
/* @sqlc-vet-disable no-delete cost-check */
SELECT * FROM users WHERE id = ?;

调试技巧

设置环境变量SQLCDEBUG=dumpexplain=1可以输出完整的EXPLAIN结果，便于调试复杂规则。

最佳实践建议

1. 渐进式引入：从简单规则开始，逐步增加复杂度
2. 团队协作：将规则文件纳入版本控制，确保团队一致性
3. CI集成：在持续集成流程中加入sqlc vet检查
4. 性能考量：复杂规则可能增加检查时间，合理平衡严格性和效率

通过合理使用sqlc vet，开发者可以在早期发现SQL查询中的潜在问题，显著提高应用的数据层质量和性能。

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