sqlike-mcp

sqlike：MCP 服务和 CLI

在 SQL 运行前检查它，并确认重写后返回的结果是否一致。

sqlike 会读取查询并指出其中的问题：有效性错误、反模式、可自动应用的重写，以及索引建议。它还会比较两个查询，并报告第二个查询返回的结果是否仍然相同。分析过程完全不涉及模型，因此相同的查询始终会得到相同的答案。

此代码仓库包含客户端：一个 MCP 服务、一个 CLI，以及它们共用的库。它们会在本地对 SQL 进行词法分析，因此标识符和字面量会在离开你的设备前被屏蔽，只会转发经过词法分析的查询。分析引擎不在此代码仓库中。它在服务端运行，且为闭源。

方言： Postgres、MySQL、MariaDB、SQLite、SQL Server 和 DuckDB。每条规则都带有在对应引擎上测得的判定结果，因此你看到的严重程度反映的是该数据库的实际行为，而不是从 Postgres 继承而来。DuckDB 是列式数据库：它没有通用二级索引，因此十项索引建议在此被四项列式建议取代。

为什么

如今，许多 SQL 都由 AI 编写，而 AI 写出的 SQL 往往看起来不错，实际运行却不正确。LEFT JOIN 变成了 INNER，数据行悄然消失。漏掉了 WHERE，于是 UPDATE 命中了所有行。两个表用错误的键进行了联接。这些问题从页面上看不出来，也只有在造成后果后才会显现。

sqlike 就是两者之间的检查环节。它会从包含 172 条规则的目录中标记不安全的模式，每条规则在发布前都经过真实数据库验证；它还会判断重写是否保留结果。第二项检查追求可靠而非完备：它会认证能够证明的重写；无法证明时，则会回答 Undecided，而不是猜测。Undecided 绝不代表等价。

由于没有内容是生成的，因此不存在重试循环、按 token 计费，也不会因相同输入的不同运行而产生差异。等价性检查采用规范化而非求解，因此大约只需一毫秒就能给出答案，而当前最先进的学术证明器则需要数百毫秒。相关结果已通过正面对比测试，其中也包括证明器胜出的查询。

安装 MCP 服务

将其添加到任意 MCP 客户端（Claude Code、Claude Desktop、Cursor 等）：

{
  "mcpServers": {
    "sqlike": { "command": "npx", "args": ["-y", "@sqlike/mcp"] }
  }
}

也可以通过 Smithery 安装。如果你有密钥并希望获得更高的速率限制，请设置 SQLIKE_API_KEY。不设置密钥也能使用匿名层级，无需注册。

工具

analyze

对单个查询进行静态分析：检查有效性、反模式、建议的改写，以及模式和索引建议。返回 JSON 分析封装。

Argument	Type	Description
sql	string	要分析的查询。必填。
schema	string	可选的 DDL（CREATE TABLE / CREATE INDEX），用于执行感知列和类型的检查。
stats	string	可选的表到行数的 JSON 映射，例如 {"orders": 2000000}。严重程度和索引建议会根据数据量调整。
explain	string	可选的查询计划（Postgres EXPLAIN (ANALYZE, FORMAT JSON)、MySQL EXPLAIN FORMAT=JSON、SQLite EXPLAIN QUERY PLAN 的 .mode json 行、SQL Server SHOWPLAN_XML、DuckDB EXPLAIN (FORMAT JSON)）。根据规划器的实际操作，确认或排除索引相关发现。
dialect	string	postgres（默认）、mysql、mariadb、sqlite、mssql 或 duckdb。
allow_raw	boolean	仅在查询解析失败、因而无法进行分词时使用：发送原始 SQL 以获取解析诊断。默认值为 false。

diff

检查两个查询是否等价，这是 LLM 无法可靠判断自身改写是否等价的问题。返回判定结果（Equivalent、EquivalentWithNotes、Differs 或 Undecided）、置信度，以及针对各项属性（列、行、基数、顺序）的报告，让你了解具体发生了什么变化，而不只是得到一个简单的是或否。

Argument	Type	Description
sql_a	string	原始查询。必填。
sql_b	string	要与 sql_a 进行比对的改写后查询。必填。
schema	string	可选的 DDL，供两个查询解析（共用一个模式）。
dialect	string	postgres（默认）、mysql、mariadb、sqlite、mssql、duckdb。

CLI

可在终端或 CI 作业中执行相同的检查。无需安装即可运行，也可以将其添加到路径中：

npx -y @sqlike/cli --help
npm i -g @sqlike/cli
brew install orifisher2/sqlike/sqlike

# analyze a query — the hosted API is the default, so no flags are needed
sqlike check query.sql

# several files at once, with a schema
sqlike check migrations/*.sql --schema schema.sql

# reading from stdin, machine-readable output (one JSON record per file)
cat query.sql | sqlike check - --schema schema.sql --json

# check that a rewrite is equivalent
sqlike diff before.sql after.sql

使用 --remote 或 SQLIKE_URL 指定其他地址，并使用 --key 或 SQLIKE_API_KEY 进行身份验证。

如果你有查询的 EXPLAIN 输出，可使用 --explain plan.json 传入；实际访问路径将用于确认或排除索引相关发现。查询计划与查询和模式一样，会在离开本机前进行分词。

退出代码是一份契约，因此每个代码都只表示一种确切含义：

	check	diff
0	检查通过，或没有达到 --fail-on 阈值的发现	等价
1	存在警告，且 --fail-on warn 要求报告警告时	不同
2	存在阻断性缺陷：SQL 无效，或有高严重程度的正确性问题	未能判定
3	运行问题——无法访问、受到速率限制或无法解析	同上
4	用法错误（标志无效）	同上

check 默认使用 --fail-on block，因此建议性发现只会报告，不会导致构建失败。使用 --fail-on warn 可启用严格模式；使用 never 则只报告、不失败。3 永远不是对 SQL 的判定——流水线可以区分“此查询有问题”和“调用未能完成”。

在 CI 中和提交时

在编写 SQL 的地方进行检查。两者运行的检查与 CLI 相同，并且都会先在本地进行词法分析。

GitHub Actions。 检查结果会内联显示在拉取请求的差异中。工作流使用 GitHub 自带的 OIDC 令牌，以你的仓库所有者身份进行身份验证——无需注册，也无需存储或泄露 API 密钥。

permissions:
  id-token: write        # authenticate as this repo's owner
  pull-requests: read    # check only the files this PR changes
  contents: read         # mode: diff, to read the earlier version of a file
steps:
  - uses: actions/checkout@v5
  - uses: orifisher2/[email protected]
    with:
      dialect: postgres
      schema: db/schema.sql

设置 mode: diff 后，它会在每个拉取请求中回答一个不同的问题：此次改写是否改变了查询的返回结果？ 只比较修改过的文件，而“无法证明任一结论”的判定不会导致构建失败。

来自 fork 的拉取请求会匿名运行。 GitHub 不会向由 fork 触发的工作流颁发 OIDC 令牌，因此贡献者的拉取请求无法以你的仓库身份进行身份验证——它会改用基于 IP 的匿名速率限制。这不会导致故障，也无需进行任何配置；你自己的分支仍会正常进行身份验证。Action 会明确说明这一点，而不会建议设置无法解决问题的权限。

在拉取请求之外，没有一组已更改的文件，因此 changed-only 不适用，所有匹配的文件都会接受检查。发生这种情况时，Action 会发出警告，因为在大型仓库中，这足以触发速率限制。

pre-commit。 在提交落地前运行相同的检查：

repos:
  - repo: https://github.com/orifisher2/sqlike
    rev: cli-v0.4.2
    hooks:
      - id: sqlike
        args: [--dialect, postgres]

如果 sqlike 无法连接，钩子会说明情况并放行提交；它只会在发现实际缺陷时阻止提交。

以隐私为设计原则

词法分析在此处进行，也就是在你的计算机上、发出任何请求之前。sqlike 永远不会看到真实的表名、列名或值，因此无内容可泄露，也无内容可用于训练。AI 助手需要真实数据才能帮到你；sqlike 不需要。

如果查询无法解析，就无法进行词法分析；客户端会拒绝发送，而不是传输原始 SQL。如需仍然发送，必须明确选择启用（工具使用 allow_raw，CLI 使用 --allow-raw）。

关于此设计涵盖和不涵盖的内容，请参阅 THREAT-MODEL.md。

本仓库包含的内容

• crates/mcp：sqlike-mcp，MCP 服务。发布到 npm 时为 @sqlike/mcp。
• crates/cli：sqlike，命令行客户端。发布到 npm 时为 @sqlike/cli。
• crates/client：共享的转发器，不包含引擎：进行词法分析、调用 API、还原词法分析结果。
• crates/core-parse：SQL 解析器、阶段模型、词法分析器和结果类型。
• packages/：npm 打包目录，内含适用于各个平台的预构建二进制文件。
• skills/：Agent 技能，让编码 Agent 知道何时应主动使用 sqlike。

了解更多

请访问 sqlike.com 体验。等价性检查器依据标准学术基准公开评测，并与最先进的证明器进行正面对比，详见 sqlike.com/benchmark。

说明

本仓库由上游单体仓库生成；上游单体仓库是唯一事实来源。请在此处提交问题。代码更改在上游进行，然后镜像回此处。

许可证

Apache-2.0。参见 LICENSE。

crates/sqlparser 是 sqlparser-rs 的随附副本，同样采用 Apache-2.0 许可证。其 NOTICE 文件记录了上游版本，并列出了此后更改过的所有文件。