sqlprism (Darkcofy)

SQLPrism

一个MCP服务器，将SQL代码库索引到由DuckDB支持的可查询知识图中。与其翻阅文件，不如问结构性问题： *这张表上有什么，这列在哪里转换，这个PR的爆炸半径是多少。*

为SQL密集型数据项目构建——使用原始SQL， SQLMesh，以及 数据构建工具.

为什么不只是Grep？

Grep找到了字符串。此工具了解SQL结构。

200型号 SQLMesh 项目，列影响查询返回 75个结构化结果，约5000个代币。grep等价物需要 打开40-60个文件，~10000+个令牌，但仍然无法告诉您列是出现在WHERE筛选器中还是SELECT中。

设置

1.安装

git clone https://github.com/darkcofy/sqlprism.git && cd sqlprism
uv sync

2.配置

uv run sqlprism init                    # creates sqlprism.yml in the current directory
# edit sqlprism.yml to add your repos (see Configuration below)
uv run sqlprism reindex                 # index plain SQL repos

先决条件： dbt和SQLMesh是 不 sqlprism的依赖关系。渲染器向 dbt compile / sqlmesh 在目标项目自己的virtualenv中（通过 uv run 默认情况下）。在该项目中安装渲染器——例如 uv add dbt-core dbt- 或 uv add sqlmesh --跑步前 reindex-dbt / reindex-sqlmesh。如果缺少渲染器，sqlprism将在指向项目目录时引发明显错误。

3.连接您的MCP客户端

克劳德代码：

claude mcp add sqlprism -- uv run --directory /path/to/sqlprism sqlprism serve

克劳德桌面/光标/继续开发 (.mcp.json):

{
  "mcpServers": {
    "sqlprism": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/sqlprism", "sqlprism", "serve"]
    }
  }
}

替换 /path/to/sqlprism 带有克隆的绝对路径。

4.保存时重新索引

当您设置保存挂钩时，图形会自动保持新鲜。根据您的编辑器，有两种模式。

克劳德代码

添加a PostTool使用挂钩 因此，每当Claude写入或编辑文件时，索引都会更新。将此另存为 .claude/settings.json 在项目根目录中：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(cat | jq -r '.tool_input.file_path // empty'); [ -n \"$FILE\" ] && [[ \"$FILE\" =~ \\.sql$ ]] && sqlprism reindex-file \"$FILE\" || true"
          }
        ]
      }
    ]
  }
}

这将从钩子的stdin JSON中提取文件路径，检查它是否是 .sql 文件，并调用CLI对其重新索引。运行 /hooks 在Claude Code中验证钩子是否处于活动状态。

其他MCP客户端（游标、Continue.dev）

这 reindex_files MCP工具接受绝对文件路径，并仅对受影响的模型重新建立索引。纯SQL在~50ms内重新索引； 数据构建工具/SQLMesh 模型在2-5s内编译+重新索引。每个仓库都会取消调用（SQL为500ms，渲染模型为2s），因此可以快速将批处理保存到单个操作中。

配置您的客户端以调用 reindex_files 保存时保存文件的路径。

不带MCP的编辑器（Vim、Neovim、Emacs、VS代码任务）

这 reindex-file CLI命令可以独立工作，不需要运行服务器：

sqlprism reindex-file /path/to/model.sql

Vim/Neov：

autocmd BufWritePost *.sql silent !sqlprism reindex-file %:p

Emacs：

(add-hook 'after-save-hook
  (lambda ()
    (when (string-match-p "\\.sql\\'" buffer-file-name)
      (start-process "sqlprism" nil "sqlprism" "reindex-file" buffer-file-name))))

VS Code （使用 运行保存 扩展， .vscode/settings.json):

{
  "emeraldwalk.runonsave": {
    "commands": [
      {
        "match": "\\.sql$",
        "cmd": "sqlprism reindex-file ${file}"
      }
    ]
  }
}

配置

sqlprism init 在以下位置创建默认配置 sqlprism.yml 在工作目录中。YAML是默认格式；JSON也支持(--format json).现有的 sqlprism.json 文件是自动发现的，以实现向后兼容性。用以下内容覆盖配置路径 --config PATH 任何命令。

db_path: ~/.sqlprism/graph.duckdb
sql_dialect: null
repos:
  my-queries: /path/to/sql/repo
  multi-dialect-repo:
    path: /path/to/repo
    dialect: starrocks
    dialect_overrides:
      athena/: athena
      postgres/: postgres
sqlmesh_repos:
  my-sqlmesh-project:
    project_path: /path/to/sqlmesh/folder
    env_file: /path/to/.env
    dialect: athena
    variables:
      GRACE_PERIOD: 7
dbt_repos:
  my-dbt-project:
    project_path: /path/to/dbt/project
    env_file: /path/to/.env
    target: dev
    dialect: starrocks
    dbt_command: uv run dbt

SQL方言支持

由...驱动 SQL胶水，索引器支持 33种SQL方言 开箱即用：

Athena、BigQuery、ClickHouse、ViewModel、Doris、Dremio、Drill、Druid、DuckDB、Dune、Exasol、Fabric、Hive、Materialize、MySQL、Oracle、Postgres、Presto、PRQL、Redshift、RisingWave、SingleStore、Snowflake、Spark、Spark2、SQLite、StarRocks、Tableau、Teradata、Trino、TSQL。

将方言名称作为小写字符串传递（例如。 "starrocks", "bigquery", "athena").方言特定的引用和标识符大小写规范化是自动处理的。

CLI命令

完整参考： CLI指南

MCP工具

完整参考： MCP工具指南

作为MCP服务器运行时(sqlprism serve)，暴露了以下工具：

建筑

src/sqlprism/
  types.py               checksum -> parse -> store; file-level reindex with repo-type dispatch
    mcp_tools.py        <- FastMCP tool definitions (non-blocking reindex, per-repo debounce)
    conventions.py      <- Convention inference engine: layers, naming, references, tags, overrides
  cli.py                <- Click CLI: serve, reindex, reindex-file, reindex-sqlmesh, reindex-dbt, conventions, status, init

SQL解析器提取：

• 节点：表、视图、CTE、查询（具有模式元数据和方言感知案例规范化）
• 边缘：表引用、CTE引用、JOIN（上下文类似于“FROM子句”、“JOIN子句”）
• 列使用情况：按列跟踪，使用类型（select、where、join_on、group_by、order_by、has、partition_by、window_order）、转换（CAST、COALESCE、SUM等）、输出别名和where筛选器表达式
• 列沿袭：通过CTE和子查询进行端到端跟踪，返回源表，当模式目录可用时进行SELECT\*扩展

DuckPGQ图形分析

SQLPrism可选地与 DuckPGQ 用于高级图形分析。安装后，这些工具可用： find_path, find_critical_models, find_subgraphs, find_bottlenecks （聚类富集）。DuckPGQ在首次使用时会自动安装，无需手动设置。

发展

uv sync
uv run pytest                          # run tests (630+ tests)
uv run pytest --cov=sqlprism           # run with coverage report
uv run pytest --cov=sqlprism --cov-report=html:coverage_html  # HTML report

代码覆盖率

许可证

Apache许可证2.0——请参阅 许可证.