mcpField
S
sql-lint

sql-lint

github.com/mizchi测试与质量41648 次安装1 周前更新
代码仓库

关于 sql-lint

面向使用命名 SQL 查询目录的项目，提供轻量 lint 技能，用于检查基础格式与常见问题。内置零依赖 catalog-lint，也可选用针对 SQL 风格检查配置好的 sqlfluff。

主要功能

  1. 01检查重复或格式错误的查询名
  2. 02检测缺少分号和空查询体
  3. 03标记 SELECT * 与宽泛 LIKE
  4. 04提供零依赖 Node 脚本
  5. 05支持可选 sqlfluff 风格检查

适用场景

  1. 01在提交前检查 SQL 查询目录
  2. 02将基础检查加入 CI
  3. 03在迁移阶段执行 SQL 风格检查

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mizchi/skills --skill sql-lint

安装后在 Claude Code 中输入/sql-lint确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.sqlfluff
README.md
scripts/
catalog-lint.mjs

详细介绍

SQL Lint

当项目有 SQL 目录（使用 -- name: X :type 注释或任何命名查询约定），并希望执行基本规范检查但不想采用重量级 SQL 检查器时，请使用此工具。

两层检查

此技能提供两种检查器，在成本和覆盖范围之间各有取舍。

第 1 层：catalog-lint（内置，无依赖）

scripts/catalog-lint.mjs 是一个不依赖任何依赖项的 Node 20+ 脚本。它可以检测：

  • duplicate-name：两个查询具有相同的 -- name: X 标头。某些代码生成器会静默覆盖；另一些则会出错。
  • missing-semicolon：查询缺少结尾的 ;。sqlc 会在构建时拒绝此类查询，而 catalog-lint 会在格式检查时发现它们。
  • empty-body：标头后没有 SQL 正文。
  • malformed-name：-- name: 行不符合 name: X :type 格式。
  • select-star：SELECT *（总是会过量获取数据）。
  • double-wildcard-like：LIKE '%...%'（存在全表扫描风险）。

运行（这是默认的第一步——先从这里开始，再考虑使用 sqlfluff）：

# `scripts/` is relative to THIS skill's directory. From elsewhere, use the
# absolute path, e.g. node "$CLAUDE_SKILLS_DIR/sql-lint/scripts/catalog-lint.mjs".
node scripts/catalog-lint.mjs your-project/db/queries.sql
echo "exit=$?"   # 0 = clean, 1 = findings — the exit code IS the pass/fail signal

检查通过时退出码为 0；发现问题时退出码为 1。输出格式为 file:line: [rule] message，可由编辑器的诊断边栏解析。注意：对于 select-star 和 double-wildcard-like，报告的行是查询的 -- name: 标头，而不是有问题的 SQL 行。

第 2 层：sqlfluff（可选，按需启用）

要进行全面的样式检查——关键字大小写、缩进、别名名称等——请使用 sqlfluff。此技能提供了针对 SQLite/D1 和 sqlc 目录调整过的 .sqlfluff：

uvx sqlfluff lint --config .sqlfluff your-project/db/queries.sql

uvx（来自 astral.sh/uv）会在临时虚拟环境中运行 sqlfluff，不会永久安装任何内容。如果缺少 uv，可改用 pip install sqlfluff 或 pipx install sqlfluff。

提供的配置禁用了几条 sqlfluff 规则：

  • AM04（SELECT *）由 catalog-lint 负责检查，且能提供更准确的上下文。
  • CP02（列名大小写）对于 obj.field_name 这类 JSON 路径引用会产生太多误报。
  • L009（末尾换行符）由 git 强制执行。

何时调用

  • 每次提交涉及查询目录时（pre-commit / pre-push 钩子）。
  • 每完成一个迁移里程碑，运行一次 sqlfluff，进行全面的样式检查。

宿主代码中的内联 SQL

此技能不会检查 MoonBit / Rust / Go / 等语言中的内联 SQL。此类场景适合使用 ast-grep，但需要针对每种语言提供 tree-sitter 支持。对于没有 tree-sitter 语法的宿主语言（例如 MoonBit），可以使用文本 grep 基线文件（.linters/inline-sql-baseline.json）：统计每个文件中的 .prepare( 次数，并拒绝数量增加。

配套的 sql-security 技能介绍了同样的方法来防止 SQL 注入。

CI 集成

sql-lint:
    node scripts/catalog-lint.mjs db/queries.sql

在 CI 中运行完整的 sqlfluff 检查时，应单独设置 sql-lint-style 步骤，这样轻量的 catalog-lint 就能快速失败。

引擎扩展性

catalog-lint.mjs 与引擎无关——这些规则检查 SQL 注释、分号和基本模式。要适配 MySQL / Postgres，请修改 .sqlfluff 中的 dialect = sqlite 行。

要求

  • scripts/catalog-lint.mjs 需要 Node 20 或更高版本。
  • （可选）运行 sqlfluff 需要 uv / pipx / pip。

文件

  • scripts/catalog-lint.mjs — 无依赖的目录检查器。
  • .sqlfluff — 按需启用的 sqlfluff 配置（SQLite 方言；用于其他引擎时请修改 dialect = ...）。

评论

支持 Markdown