使用说明

SQLPrism

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

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

为什么不只是Grep？

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

功能	Grep	SQLPrism
查找表引用	是	是
CTE到CTE数据流	否--手动读取文件	是--在图中跟踪边
带转换的列沿袭（CAST、COALESCE、SUM）	否	是--从AST解析
使用类型（WHERE vs SELECT vs JOIN vs GROUP BY）	脆弱正则表达式	精确——从AST解析
多跳影响分析	手动跟踪	自动图遍历
PR爆炸半径	用git diff DIY	一个电话
跨CTE列跟踪	基本上不可能	内置

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

对于数据构建工具和 SQLMesh 项目，使用 reindex-dbt 和 reindex-sqlmesh 分别。请参阅 CLI指南完整的选项。

先决条件： dbt和SQLMesh是不 sqlprism的依赖关系。渲染器向 dbt compile / sqlmesh 在目标项目自己的virtualenv中（通过 uv run 默认情况下）。在该项目中安装渲染器——例如 uv add dbt-core dbt-<adapter> 或 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

字段	描述
`db_path`	DuckDB数据库文件的路径。默认为 `~/.sqlprism/graph.duckdb`.
`sql_dialect`	全局默认SQL方言。 `null` 用于自动检测。
`repos`	纯SQL存储库。值是路径字符串或具有以下值的对象 `path`, `dialect`, `dialect_overrides`.
`dialect`	按回购方言覆盖（例如。 `"starrocks"`, `"athena"`, `"bigquery"`).
`dialect_overrides`	使用前缀匹配或glob模式覆盖每个目录。
`sqlmesh_repos`	SQLMesh 项目。在解析之前渲染模型。
`dbt_repos`	数据构建工具项目。在解析之前编译模型。

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指南

命令	描述
`sqlprism init`	创建默认配置文件。
`sqlprism reindex`	对普通SQL存储库进行增量重新索引。
`sqlprism reindex-file`	快速保存特定文件的重新索引。
`sqlprism reindex-dbt`	编制并索引a 数据构建工具项目。
`sqlprism reindex-sqlmesh`	渲染和索引a SQLMesh 项目。
`sqlprism serve`	启动MCP服务器（stdio或HTTP）。
`sqlprism conventions init`	生成 `sqlprism.conventions.yml` 根据推断的惯例。
`sqlprism conventions refresh`	重新索引后重新运行约定推理。
`sqlprism conventions diff`	显示自上次以来发生了什么变化 `--init`.
`sqlprism status`	显示索引状态。
`sqlprism query search`	按名称模式查找实体。
`sqlprism query references`	查找入站/出站依赖关系。
`sqlprism query column-usage`	查找不同模型中的列使用情况。
`sqlprism query trace`	多跳依赖关系跟踪。
`sqlprism query lineage`	端到端列沿袭链。

MCP工具

完整参考： MCP工具指南

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

工具	说明
`search`	按带分页的名称模式查找实体。
`find_references`	带有代码段的入站/出站依赖关系。
`find_column_usage`	列用法——类型、转换、别名。
`trace_dependencies`	多跳上游/下游链。
`trace_column_lineage`	通过CTE进行端到端的列沿袭。
`get_schema`	包含列、类型和依赖关系的表/视图架构。
`get_context`	一个调用是模型的全面上下文转储。
`find_path`	两个模型之间的最短路径（DuckPGQ）。
`find_critical_models`	按PageRank重要性对模型进行排名（DuckPGQ）。
`detect_cycles`	在图中查找循环依赖关系。
`find_subgraphs`	识别断开连接的集群和孤立模型（DuckPGQ）。
`find_bottlenecks`	具有风险分类的高扇出模型。
`check_impact`	更改前的列级影响分析。
`pr_impact`	自基础提交以来的结构差异+爆炸半径。
`reindex`	SQL存储库的后台增量重新索引。
`reindex_files`	通过每回购一次的减持，快速实现重新索引。
`reindex_dbt`	后台dbt编译+索引。
`reindex_sqlmesh`	后台SQLMesh渲染+索引。
`get_conventions`	推断项目约定——命名、引用、列。
`find_similar_models`	查找与您正在构建的模型相似的现有模型。
`suggest_placement`	根据参考建议放置新模型的位置。
`search_by_tag`	通过语义标签（业务领域概念）查找模型。
`list_tags`	列出所有带有模型计数和置信度的语义标签。
`index_status`	索引统计、跨仓库边和名称冲突。

建筑

src/sqlprism/
  types.py              <- ParseResult, NodeResult, EdgeResult, ColumnUsageResult, parse_repo_config
  languages/
    __init__.py         <- SQL_EXTENSIONS, is_sql_file()
    sql.py              <- sqlglot: tables, views, CTEs, column lineage, transforms
    sqlmesh.py          <- SQLMesh renderer (full project + selective render_models)
    dbt.py              <- dbt renderer (full project + selective render_models via --select)
    utils.py            <- Shared helpers (find_venv_dir, parse_dotenv, build_env, enrich_nodes)
  core/
    graph.py            <- DuckDB storage layer (MVCC), queries, snippets, repo_type tracking
    indexer.py          <- Orchestrator: scan -> 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*扩展

完整的架构文档：体系结构概述 | DuckDB架构

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——请参阅许可证.

使用说明

SQLPrism

为什么不只是Grep？

设置

1.安装

2.配置

3.连接您的MCP客户端

4.保存时重新索引

克劳德代码

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

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

配置

SQL方言支持

CLI命令

MCP工具

建筑

DuckPGQ图形分析

发展

代码覆盖率

许可证

相关 MCP

知识图谱记忆服务器

AI持久记忆服务器

知识图谱存储服务

百度优选

自主代理操作系统

知识图谱记忆系统