SQLPrism

An MCP server that indexes SQL codebases into a queryable knowledge graph backed by DuckDB. Instead of grepping through files, ask structural questions: what touches this table, where is this column transformed, what's the blast radius of this PR.

Built for SQL-heavy data projects — works with raw SQL, SQLMesh, and dbt.

Why Not Just Grep?

Grep finds strings. This tool understands SQL structure.

On a 200-model SQLMesh project, a column impact query returns 75 structured results in ~5,000 tokens. The grep equivalent would need 40-60 files opened, ~100,000+ tokens, and still wouldn't tell you whether a column appears in a WHERE filter or a SELECT.

Setup

1. Install

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

2. Configure

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

For dbt and SQLMesh projects, use reindex-dbt and reindex-sqlmesh respectively. See the CLI guide for full options.

Prerequisite: dbt and SQLMesh are not dependencies of sqlprism. The renderers shell out to dbt compile / sqlmesh inside the target project's own virtualenv (via uv run by default). Install the renderer in that project — for example uv add dbt-core dbt-<adapter> or uv add sqlmesh — before running reindex-dbt / reindex-sqlmesh. If the renderer is missing, sqlprism will raise a clear error pointing at the project directory.

3. Connect your MCP client

Claude Code:

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

Claude Desktop / Cursor / Continue.dev (.mcp.json):

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

Replace /path/to/sqlprism with the absolute path to your clone.

4. Reindex on Save

The graph stays fresh automatically when you set up on-save hooks. There are two modes depending on your editor.

Claude Code

Add a PostToolUse hook so the index updates whenever Claude writes or edits a file. Save this as .claude/settings.json in your project root:

{
  "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"
          }
        ]
      }
    ]
  }
}

This extracts the file path from the hook's stdin JSON, checks it's a .sql file, and calls the CLI to reindex it. Run /hooks in Claude Code to verify the hook is active.

Other MCP clients (Cursor, Continue.dev)

The reindex_files MCP tool accepts absolute file paths and reindexes only the affected models. Plain SQL reindexes in ~50ms; dbt/SQLMesh models compile + reindex in ~2-5s. Calls are debounced per repo (500ms for SQL, 2s for rendered models) so rapid saves batch into a single operation.

Configure your client to call reindex_files with the saved file's path on save.

Editors without MCP (Vim, Neovim, Emacs, VS Code tasks)

The reindex-file CLI command works standalone — no running server needed:

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

Vim / Neovim:

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 (using the Run on Save extension, .vscode/settings.json):

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

Configuration

sqlprism init creates a default config at sqlprism.yml in the working directory. YAML is the default format; JSON is also supported (--format json). Existing sqlprism.json files are auto-discovered for backwards compatibility. Override the config path with --config PATH on any command.

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 Dialect Support

Powered by sqlglot, the indexer supports 33 SQL dialects out of the box:

Athena, BigQuery, ClickHouse, Databricks, 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.

Pass the dialect name as a lowercase string (e.g. "starrocks", "bigquery", "athena"). Dialect-specific quoting and identifier case normalization are handled automatically.

CLI Commands

Full reference: CLI guide

MCP Tools

Full reference: MCP tools guide

When running as an MCP server (sqlprism serve), the following tools are exposed:

Architecture

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

The SQL parser extracts:

• Nodes: tables, views, CTEs, queries (with schema metadata and dialect-aware case normalization)
• Edges: table references, CTE references, JOINs (with context like "FROM clause", "JOIN clause")
• Column usage: per-column tracking with usage type (select, where, join_on, group_by, order_by, having, partition_by, window_order), transforms (CAST, COALESCE, SUM, etc.), output aliases, and WHERE filter expressions
• Column lineage: end-to-end tracing through CTEs and subqueries back to source tables, with SELECT * expansion when schema catalog is available

Full architecture docs: Architecture overview | DuckDB schema

DuckPGQ Graph Analytics

SQLPrism optionally integrates with DuckPGQ for advanced graph analytics. When installed, these tools become available: find_path, find_critical_models, find_subgraphs, find_bottlenecks (clustering enrichment). DuckPGQ is installed automatically on first use — no manual setup needed.

Development

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

Code Coverage

License

Apache License 2.0 — see LICENSE.