Provides AI agents with full PostgreSQL schema intelligence from offline snapshots without requiring live database connections or credentials.
Also known as boringSQL/dryrun, @boringsql/dryrun
- Stars
- 36
- Tools
- 9
- Downloads, 30 days
- 1,574
- Latest version
- 0.23.0
- Last commit
- Nov 15, 2026
- License
- BSD-2-Clause
What is dryrun MCP?
dryrun provides AI agents with full PostgreSQL schema intelligence from offline snapshots without requiring live database connections or credentials. It exposes 9 tools, such as advise, check_migration, describe_table.
Summary generated from the project's README
About dryrun MCP server
DryRun provides AI agents, IDEs, and CI systems with comprehensive PostgreSQL schema intelligence without requiring live database connections or sensitive credentials. It operates by using an offline snapshot stored in a local database file, which contains structural information like tables, views, indexes, constraints, and even planner statistics. This approach ensures that developers and AI assistants can understand the database architecture while keeping production credentials strictly on the DBA's machine.
The system consists of a CLI tool for extracting and analyzing schema data and an MCP server that exposes this intelligence to AI clients via stdio or SSE. Users can install it via Homebrew or npm, and it integrates with tools like Claude Code, Cursor, and Zed. By using the MCP server, an AI assistant can perform tasks such as schema exploration, query validation, and migration safety checks using tools like explain_query and check_drift, all while working from the local snapshot.
What you can do with it
- 1Validate SQL query correctnessAn AI assistant can check if a specific SQL query correctly references existing columns and follows schema constraints.
- 2Audit schema for best practicesDevelopers can use the tool to find missing primary keys or improper data types within their database structure.
- 3Assess migration safetyAn agent can analyze a DDL statement to determine if it will cause dangerous table locks or require a full table rewrite.
- 4Detect schema driftUsers can compare current schema snapshots against previous versions to identify structural changes.
Written from the project's README. Every use case is checked against a quote from it.
How to install dryrun MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall dryrun MCP in Claude Code
$ claude mcp add dryrun -- npx -y @boringsql/dryrun mcp-serveInstall dryrun MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"dryrun": {
"command": "npx",
"args": [
"-y",
"@boringsql/dryrun",
"mcp-serve"
]
}
}
}Install dryrun MCP in VS Code
.vscode/mcp.json
{
"servers": {
"dryrun": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@boringsql/dryrun",
"mcp-serve"
]
}
}
}Install dryrun MCP in VS Code CLI
$ code --add-mcp '{"name":"dryrun","type":"stdio","command":"npx","args":["-y","@boringsql/dryrun","mcp-serve"]}'Install dryrun MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"dryrun": {
"command": "npx",
"args": [
"-y",
"@boringsql/dryrun",
"mcp-serve"
]
}
}
}Install dryrun MCP in Codex
$ codex mcp add dryrun -- npx -y @boringsql/dryrun mcp-serveInstall dryrun MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.dryrun] command = "npx" args = ["-y", "@boringsql/dryrun", "mcp-serve"]
Install dryrun MCP in Gemini CLI
$ gemini mcp add -s user dryrun npx -- -y @boringsql/dryrun mcp-serveInstall dryrun MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"dryrun": {
"command": "npx",
"args": [
"-y",
"@boringsql/dryrun",
"mcp-serve"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @boringsql/dryrun 0.23.0 in an isolated container with no network and no keys. It answered and listed 9 tools.
dryrun MCP tools 9
Read from the server with tools/listadviseRead-onlyOne-shot review of a single query: validation and index suggestions from the snapshot, plus plan-shape advice and plan warnings when you pass plan_json -- a plan the user pasted or CI captured. Needs no database connection and executes nothing; without plan_json there is simply no plan to read. It returns corrected_sql when every unknown name has one obvious candidate; it never rewrites the query for performance.
check_migrationRead-onlyBefore any ALTER TABLE, CREATE INDEX, DROP, or other DDL reaches a database: the lock level each statement takes, whether it rewrites the table, and rollback_ddl where one applies. Tables created earlier in the same input are recognized as empty, so statements against them are not flagged for scans or rewrites they cannot cause. Where the safe form is mechanical it returns safer_sql -- the rewrite as statements to run in order, each on its own rather than wrapped in one transaction. When at least one statement is unsafe and every unsafe statement has one, migration_sql bundles the whole input as one runnable file -- unsafe statements replaced by safer_sql, safe ones passed through unchanged; it is absent otherwise, since a file that still holds an unsafe statement (including a statement type this tool cannot analyze) would be worse than no file at all. ddl may be a pasted migration file: goose (-- +goose Up/Down), dbmate (-- migrate:up/down) and tern (---- create above / drop below ----) markers are recognized, and direction (default up) picks the half to analyze; migration_sql is re-wrapped to stay runnable by that runner. Needs no database connection and applies nothing. It does not estimate wall-clock duration, and not every unsafe statement has a rewrite: a column type change or a backfill needs a batch size and a deploy order this tool cannot decide for you.
describe_tableRead-onlyBefore writing SQL against a table you have not read in this session, before a JOIN, or before a DELETE that might cascade: one table in full -- its columns and types, constraints, indexes, and planner stats. Needs no database connection; answers from the snapshot, and points at detect when the table has findings. detail=relations gives the incoming and outgoing foreign keys, each with a JOIN clause you can paste and the ON DELETE / ON UPDATE action it carries (declared constraints only, one hop, so a table reached by a cascade may cascade further). detail=stats adds vacuum: dead tuples, trigger points, effective autovacuum knobs and last vacuum/analyze times, for any table over 10k rows whether or not detect flagged it. Ask for the ddl field to get the CREATE TABLE that would rebuild it, with whatever the snapshot cannot reproduce listed beside it. Ask for dependents to see the captured views that read this table directly or through other views before changing or dropping it; depth 1 carries table columns, deeper rows carry via parent views. Structure as of the last capture: no row data, and nothing a later migration changed.
detectRead-onlyWhen a query got slow, before a tuning change, when autovacuum or dead tuples come up, or when asked what is wrong with this database: stale statistics, unused indexes, bloated indexes and tables, per-table scan anomalies, and vacuum health. kind=vacuum_health reports autovacuum_disabled, default_knobs_large_table, high_dead_tuple_ratio, vacuum_threshold_too_high, freeze_age_high and mxid_age_high, each with the dead-tuple counts and last (auto)vacuum and analyze times behind it. Every kind reports offenders only: a table with nothing wrong does not appear, here or in kind=all. For a table with no finding, describe_table detail=stats carries its raw counters and last vacuum/analyze times. Needs no database connection: findings are as fresh as the last capture, and quiet where it carries no node statistics. It reports only -- no VACUUM, no ANALYZE, no settings changed. Caveats for a finding arrive with it in _meta.hint.
find_objectsRead-onlyFirst call against an unfamiliar database, and the way to find where a name lives. With no query it inventories what exists and how big it is in production -- row estimates and table size (the heap: indexes and TOAST are not counted), partition children folded into their parent -- which the repo cannot tell you; kind= inventories views, functions or enums instead. With a query it searches names, table and column comments, index and view definitions, and enum labels, so a value like 'cancelled' finds the enum that carries it, not just an object named after it. Every hit is tagged with the field it matched (matched_on) and exact name matches rank first. Needs no database connection. Case-insensitive substring only -- no regex, no fuzzy matching, and never row data. Function bodies are not in the snapshot, so a name that appears only inside one is not findable here. One line per object: describe_table is what reads a table in full.
lint_schemaRead-onlyWhen reviewing a schema as a whole -- a design review, an inherited database, or the state a migration left behind: naming and convention violations plus an audit of missing keys, unindexed foreign keys, and unsafe defaults. Needs no database connection. Defaults to verbosity='summary', which returns per-rule counts only: pass verbosity='full' for the findings and their ddl_fix (not every finding has one). Whole-schema, not per-query (validate_query, advise); it applies nothing.
list_top_queriesRead-onlyWhen asked what this database spends its time on: captured pg_stat_statements query shapes ranked by exec time, calls, or mean. Needs no database connection; reads the local history (dryrun snapshot capture --streams query, or init's best-effort capture) and is empty when no capture carries query stats. Each entry is tagged with its reporting node and never averaged across nodes: a primary and a replica are different workloads. A node label that rotates between servers reports only the server that answered its newest capture; _meta.hint says so when the captures show it. SQL is qshape-normalized and parameterized, never the literal text or parameter values a user ran. Counters are cumulative since the last reset, not a recent-activity rate. It reports the newest capture per node and differences nothing, so it says what the corpus has cost since that reset, never what it cost this week; snapshot_diff kind=query is what differences them, and _meta.history, when present, says what the local store holds. An empty result carrying unknown: true means no capture holds query stats at all, which is not the same as a database whose statements are all cheap. Before comparing or differencing any two numbers, read _meta.hint: each caveat there is prefixed BLOCKING: (the obvious reading is wrong, e.g. nodes with different counter windows must not be ranked against each other), COMPARABILITY: (not comparable with the node's previous capture) or SCOPE: (narrower than it looks).
snapshot_diffRead-onlyWhen something changed and you need to know what: the schema DDL delta between two snapshots, plus planner sizing, activity, and query-shape drift correlated to the same capture window. Query deltas are per shape over that window, so their mean is comparable across captures -- unlike pg_stat_statements' own since-reset mean. Needs no database connection, but does need two snapshots in the local history. Snapshot-to-snapshot only, never against the live database (check_drift); it reports what moved, not why. Totals are a delta over the interval between the two anchors, not a rate: capture cadence is irregular, so deltas over unequal intervals do not compare. Each per-node query delta reports that interval as `window` in nanoseconds (window_minutes is a different number: how far a planner or activity capture may sit from an anchor to be correlated to it); planner and activity deltas carry no interval, so use the anchors' taken_at for those. If you divide by it: only when incomparable is empty and window is above zero, and never for an entry whose status is reset or truncated -- their delta is a cumulative counter rather than the window's work, which is why this tool leaves them out of its own totals and counts them in not_subtractable. Read caveats. A query delta's caveat_codes qualify its numbers rather than refute them: short_window (under 30 minutes), weekend (most of the window on the project's weekend days: Sat/Sun UTC unless [calendar] in dryrun.toml says otherwise) and one_off_heavy (an entry with at most 3 calls carrying at least 30% of the window's time, tagged per entry in view=full); summary.query_caveat_codes carries them in the default view. plan_shifts (both views) flags queryids whose blocks per call stepped up against the median of the three windows before this one while rows per call did not, the signature of a plan flip; it is a list of suspects ranked by excess blocks, read its `suppressed` reason and `no_baseline` count before treating an empty list as no flips, and note that a pgx/prepared workload can trip it per connection with no global flip. An activity or query delta with incomparable set was refused (one label covered two servers) and carries no rows; it is not a quiet node. _meta.history, when present, says what the local store holds per stream and over what span. A result over ~64 KB is cut (truncated_by=bytes); page it with the offset in _meta.next, since raising limit will not help.
validate_queryRead-onlyBefore proposing or running any SQL: checks it against the snapshot and reports unknown tables, unknown columns on qualified references (t.col), and anti-patterns. When every unknown name has exactly one candidate it also returns corrected_sql -- the same query with those names replaced, re-validated -- so a misspelling comes back as a patch rather than prose. Needs no database connection and never executes the query. Names and shape only: not cost, not plan, not whether any rows match (advise, explain_query).
| advise | One-shot review of a single query: validation and index suggestions from the snapshot, plus plan-shape advice and plan warnings when you pass plan_json -- a plan the user pasted or CI captured. Needs no database connection and executes nothing; without plan_json there is simply no plan to read. It returns corrected_sql when every unknown name has one obvious candidate; it never rewrites the query for performance. | Read-only |
| check_migration | Before any ALTER TABLE, CREATE INDEX, DROP, or other DDL reaches a database: the lock level each statement takes, whether it rewrites the table, and rollback_ddl where one applies. Tables created earlier in the same input are recognized as empty, so statements against them are not flagged for scans or rewrites they cannot cause. Where the safe form is mechanical it returns safer_sql -- the rewrite as statements to run in order, each on its own rather than wrapped in one transaction. When at least one statement is unsafe and every unsafe statement has one, migration_sql bundles the whole input as one runnable file -- unsafe statements replaced by safer_sql, safe ones passed through unchanged; it is absent otherwise, since a file that still holds an unsafe statement (including a statement type this tool cannot analyze) would be worse than no file at all. ddl may be a pasted migration file: goose (-- +goose Up/Down), dbmate (-- migrate:up/down) and tern (---- create above / drop below ----) markers are recognized, and direction (default up) picks the half to analyze; migration_sql is re-wrapped to stay runnable by that runner. Needs no database connection and applies nothing. It does not estimate wall-clock duration, and not every unsafe statement has a rewrite: a column type change or a backfill needs a batch size and a deploy order this tool cannot decide for you. | Read-only |
| describe_table | Before writing SQL against a table you have not read in this session, before a JOIN, or before a DELETE that might cascade: one table in full -- its columns and types, constraints, indexes, and planner stats. Needs no database connection; answers from the snapshot, and points at detect when the table has findings. detail=relations gives the incoming and outgoing foreign keys, each with a JOIN clause you can paste and the ON DELETE / ON UPDATE action it carries (declared constraints only, one hop, so a table reached by a cascade may cascade further). detail=stats adds vacuum: dead tuples, trigger points, effective autovacuum knobs and last vacuum/analyze times, for any table over 10k rows whether or not detect flagged it. Ask for the ddl field to get the CREATE TABLE that would rebuild it, with whatever the snapshot cannot reproduce listed beside it. Ask for dependents to see the captured views that read this table directly or through other views before changing or dropping it; depth 1 carries table columns, deeper rows carry via parent views. Structure as of the last capture: no row data, and nothing a later migration changed. | Read-only |
| detect | When a query got slow, before a tuning change, when autovacuum or dead tuples come up, or when asked what is wrong with this database: stale statistics, unused indexes, bloated indexes and tables, per-table scan anomalies, and vacuum health. kind=vacuum_health reports autovacuum_disabled, default_knobs_large_table, high_dead_tuple_ratio, vacuum_threshold_too_high, freeze_age_high and mxid_age_high, each with the dead-tuple counts and last (auto)vacuum and analyze times behind it. Every kind reports offenders only: a table with nothing wrong does not appear, here or in kind=all. For a table with no finding, describe_table detail=stats carries its raw counters and last vacuum/analyze times. Needs no database connection: findings are as fresh as the last capture, and quiet where it carries no node statistics. It reports only -- no VACUUM, no ANALYZE, no settings changed. Caveats for a finding arrive with it in _meta.hint. | Read-only |
| find_objects | First call against an unfamiliar database, and the way to find where a name lives. With no query it inventories what exists and how big it is in production -- row estimates and table size (the heap: indexes and TOAST are not counted), partition children folded into their parent -- which the repo cannot tell you; kind= inventories views, functions or enums instead. With a query it searches names, table and column comments, index and view definitions, and enum labels, so a value like 'cancelled' finds the enum that carries it, not just an object named after it. Every hit is tagged with the field it matched (matched_on) and exact name matches rank first. Needs no database connection. Case-insensitive substring only -- no regex, no fuzzy matching, and never row data. Function bodies are not in the snapshot, so a name that appears only inside one is not findable here. One line per object: describe_table is what reads a table in full. | Read-only |
| lint_schema | When reviewing a schema as a whole -- a design review, an inherited database, or the state a migration left behind: naming and convention violations plus an audit of missing keys, unindexed foreign keys, and unsafe defaults. Needs no database connection. Defaults to verbosity='summary', which returns per-rule counts only: pass verbosity='full' for the findings and their ddl_fix (not every finding has one). Whole-schema, not per-query (validate_query, advise); it applies nothing. | Read-only |
| list_top_queries | When asked what this database spends its time on: captured pg_stat_statements query shapes ranked by exec time, calls, or mean. Needs no database connection; reads the local history (dryrun snapshot capture --streams query, or init's best-effort capture) and is empty when no capture carries query stats. Each entry is tagged with its reporting node and never averaged across nodes: a primary and a replica are different workloads. A node label that rotates between servers reports only the server that answered its newest capture; _meta.hint says so when the captures show it. SQL is qshape-normalized and parameterized, never the literal text or parameter values a user ran. Counters are cumulative since the last reset, not a recent-activity rate. It reports the newest capture per node and differences nothing, so it says what the corpus has cost since that reset, never what it cost this week; snapshot_diff kind=query is what differences them, and _meta.history, when present, says what the local store holds. An empty result carrying unknown: true means no capture holds query stats at all, which is not the same as a database whose statements are all cheap. Before comparing or differencing any two numbers, read _meta.hint: each caveat there is prefixed BLOCKING: (the obvious reading is wrong, e.g. nodes with different counter windows must not be ranked against each other), COMPARABILITY: (not comparable with the node's previous capture) or SCOPE: (narrower than it looks). | Read-only |
| snapshot_diff | When something changed and you need to know what: the schema DDL delta between two snapshots, plus planner sizing, activity, and query-shape drift correlated to the same capture window. Query deltas are per shape over that window, so their mean is comparable across captures -- unlike pg_stat_statements' own since-reset mean. Needs no database connection, but does need two snapshots in the local history. Snapshot-to-snapshot only, never against the live database (check_drift); it reports what moved, not why. Totals are a delta over the interval between the two anchors, not a rate: capture cadence is irregular, so deltas over unequal intervals do not compare. Each per-node query delta reports that interval as `window` in nanoseconds (window_minutes is a different number: how far a planner or activity capture may sit from an anchor to be correlated to it); planner and activity deltas carry no interval, so use the anchors' taken_at for those. If you divide by it: only when incomparable is empty and window is above zero, and never for an entry whose status is reset or truncated -- their delta is a cumulative counter rather than the window's work, which is why this tool leaves them out of its own totals and counts them in not_subtractable. Read caveats. A query delta's caveat_codes qualify its numbers rather than refute them: short_window (under 30 minutes), weekend (most of the window on the project's weekend days: Sat/Sun UTC unless [calendar] in dryrun.toml says otherwise) and one_off_heavy (an entry with at most 3 calls carrying at least 30% of the window's time, tagged per entry in view=full); summary.query_caveat_codes carries them in the default view. plan_shifts (both views) flags queryids whose blocks per call stepped up against the median of the three windows before this one while rows per call did not, the signature of a plan flip; it is a list of suspects ranked by excess blocks, read its `suppressed` reason and `no_baseline` count before treating an empty list as no flips, and note that a pgx/prepared workload can trip it per connection with no global flip. An activity or query delta with incomparable set was refused (one label covered two servers) and carries no rows; it is not a quiet node. _meta.history, when present, says what the local store holds per stream and over what span. A result over ~64 KB is cut (truncated_by=bytes); page it with the offset in _meta.next, since raising limit will not help. | Read-only |
| validate_query | Before proposing or running any SQL: checks it against the snapshot and reports unknown tables, unknown columns on qualified references (t.col), and anti-patterns. When every unknown name has exactly one candidate it also returns corrected_sql -- the same query with those names replaced, re-validated -- so a misspelling comes back as a patch rather than prose. Needs no database connection and never executes the query. Names and shape only: not cost, not plan, not whether any rows match (advise, explain_query). | Read-only |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubDryRun PostgreSQL MCP
The PostgreSQL MCP server that doesn't need connection to the production.
dryrun gives AI agents, IDEs, and CI full schema awareness. From offline snapshot, not live database connection. Lint your schema, validate queries, check migration safety, and explore foreign key graphs. All without credentials leaving the DBA's machine.
dryrun is part of the boringSQL suite alongside RegreSQL and Fixturize.
The problem
LLM/AI coding assistants are very good in writing code/SQL queries. But they are blind. They don't know your schema, your indexes or your constraints. They might generate a migration that takes an ACCESS EXCLUSIVE lock on your busiest table and send your app down.
Some PostgreSQL MCP server ask you for the database connection. And to perform the administrative tasks you might need SUPERUSER permission. But that's like asking for problem.
We've already seen where this leads: production databases wiped by AI agents, and SQL injection in MCP servers that were supposed to be read-only.
The model doesn't need to query your database. It needs to understand your schema: the structure, constraints, statistics, and version-specific behavior. That knowledge is structural. It changes when you deploy a migration, not between queries.
DryRun features
dryrun is two things: a CLI tool and an MCP server. The CLI extracts and analyzes your schema. The MCP server exposes that analysis to AI assistants. They're separate on purpose.
CLI - extract and analyze
The CLI connects to your PostgreSQL database, introspects the full catalog (tables, views, indexes, constraints, partitions, functions, enums, RLS policies, triggers, extensions, GUCs), and writes a snapshot into .dryrun/history.db. That snapshot is the source of truth for everything else.
Once you have the snapshot, the CLI works offline:
- Lint - 20+ convention rules (naming, types, primary keys, timestamps, partitioning) and 13 structural audit rules (duplicate indexes, FK coverage, circular FKs, vacuum tuning)
- Migration safety - lock type analysis, duration estimates, table rewrite detection, safe alternatives for each DDL statement
- Query validation - SQL parsing via libpg_query, column reference checks against the actual schema, anti-pattern detection
- Snapshot diff - compare schema, planner stats, or activity between snapshots; detect drift against the live database
- Query stats - captures
pg_stat_statementsper node, collapses ORM query variants into shapes, diffs two captures to surface new or slowed queries - Multi-node stats - per-replica statistics, seq_scan hotspots, routing imbalances
MCP server - give your AI assistant a schema brain
The MCP server reads the same snapshot. It exposes 9 tools over stdio or SSE: schema exploration and search, query validation, plan analysis, migration checks, linting, vacuum health, and captured pg_stat_statements top queries. Three more (explain_query, check_drift, columnar_report) join when a live database is connected. Your AI assistant understands your database while it writes SQL.
No database connection needed. The assistant never sees credentials.
Why offline
Schema context belongs in a file, not a live connection. Column types, row estimates, index definitions, FK relationships, and PostgreSQL version can all be exported once and committed to the repo. One person with database access dumps the schema. Everyone else, humans and AI agents alike, gets full schema intelligence without credentials.
Credentials shouldn't leave the DBA's machine. If an MCP server needs DATABASE_URL to do anything useful, every developer who uses it needs production credentials. That's a security problem that has nothing to do with AI.
The server should do analysis, not pass-through. Returning raw \d+ output is marginally better than pasting it into the chat yourself. The value is in interpreting that data: checking whether a migration is safe for your PostgreSQL version, flagging missing FK indexes, and validating column references against the actual schema.
Install
Requires PostgreSQL 14 or newer. Older servers are not refused — dryrun warns and captures what it can — but they are untested, and some streams (planner stats in particular) will be unavailable. The floor tracks the oldest release still supported upstream.
Homebrew:
Homebrew 6.0 requires third-party taps to be trusted before their formulae can load:
brew trust --tap boringsql/boringsql
brew install boringsql/boringsql/dryrun
On Homebrew 5.x and older, skip the brew trust step. If you'd rather not trust the whole tap, trust just the formula with brew trust --formula boringsql/boringsql/dryrun.
npm / npx:
If you already have Node, you can run dryrun without installing anything:
npx @boringsql/dryrun --version
That fetches the prebuilt binary for your platform (darwin-arm64, linux-x64, linux-arm64), caches it, and prints the version. To put dryrun permanently on your PATH:
npm install -g @boringsql/dryrun
dryrun --version
The npm package wraps the same Go binary; every CLI command works identically. Commands like lint need a schema snapshot first — see Quickstart. Prebuilt binaries cover macOS (Apple Silicon + Intel), Linux (x64 + arm64), and Windows x64. On other platforms (Alpine/musl, Windows arm64), use Homebrew or build from source.
From source:
Requires Go 1.26+. If you don't have it, install via go.dev/dl.
git clone https://github.com/boringsql/dryrun.git
cd dryrun
go build -o bin/dryrun ./cmd/dryrun
The binary is at bin/dryrun.
30-second demo
With dryrun installed, lint a ready-made schema snapshot from a clone of this repo, no database and no setup:
git clone https://github.com/boringsql/dryrun.git
cd dryrun/examples/demo
dryrun lint
(Installed via npm or Homebrew but didn't clone the repo? You won't have examples/demo — jump to Quickstart to point dryrun at your own schema. The sample output below is what lint produces.)
[ERROR] public.audit_log: table has no primary key
fix: add a primary key (bigint GENERATED ALWAYS AS IDENTITY recommended)
[WARN ] public.audit_log: gap in range partitions: ends at '2024-07-01' but next starts at '2024-10-01'
fix: inserts into the gap will fail unless a DEFAULT partition exists
[ERROR] public.task_comments: table has no primary key
fix: add a primary key (bigint GENERATED ALWAYS AS IDENTITY recommended)
[WARN ] public.projects.created_at: timestamp column uses timestamp without time zone instead of timestamptz
fix: use timestamptz for timestamp columns
[ERROR] public.tasks.project_id: FK 'tasks_project_id_fkey' on column(s) (project_id) has no covering index
fix: add an index on FK columns to avoid sequential scans on DELETE/UPDATE
[WARN ] public.users.email: column 'email' uses character varying(255), prefer text
fix: VARCHAR(n) adds a hidden CHECK constraint with no performance benefit
[WARN ] public.user_notifications: table is missing 'created_at' column
fix: add: created_at timestamptz NOT NULL DEFAULT now()
26 finding(s): 6 error, 20 warning, 0 info (13 tables checked)
No database needed. Works entirely from the offline snapshot.
The same demo works over MCP. From examples/demo, register the server with your assistant:
claude mcp add dryrun -- npx -y @boringsql/dryrun mcp-serve
Then ask, from that directory: "what tables do I have, and what's wrong with them?"
MCP server
One command wires the server into your AI agent. setup detects Claude Code, Cursor, Codex, and Zed, writes the agent's MCP config, and adds a directive to AGENTS.md/CLAUDE.md so the agent checks the schema before writing SQL:
dryrun setup
To pick the agents yourself, or from a non-interactive shell, pass --agents:
dryrun setup --agents=claude,cursor # or: all
To register the server manually:
# for claude code
claude mcp add dryrun -- dryrun mcp-serve
# for codex
codex mcp add dryrun -- dryrun mcp-serve
If you built from source, use the full path to the binary:
claude mcp add dryrun -- /path/to/dryrun mcp-serve
Or, with no install at all, point the client at npx:
claude mcp add dryrun -- npx -y @boringsql/dryrun mcp-serve
The raw client config for this form is:
{
"mcpServers": {
"dryrun": {
"command": "npx",
"args": ["-y", "@boringsql/dryrun", "mcp-serve"]
}
}
}
The server reads the newest snapshot from .dryrun/history.db in the current project. No database credentials needed; the assistant gets full schema intelligence from the offline snapshot.
Without a snapshot the server still starts, and its tools answer that no schema is loaded. Capture one with dryrun init --db "$DATABASE_URL" or pull one a teammate pushed (dryrun snapshot pull --from-path ./snapshots, see Quickstart), and the server picks it up on the next tool call, without a restart.
For projects with multiple databases, run one dryrun mcp-serve per database and add an entry per server in your client config. Native multi-database serving inside one MCP process is tracked in #7.
See the Tutorial for live database setup, SSE transport, and Claude Desktop configuration.
Quickstart
There are two ways to get started, pick whichever fits your setup.
Option A: You have database access
If you can connect to a PostgreSQL instance (local, dev, or production), one command does everything:
dryrun init --db "$DATABASE_URL"
This creates dryrun.toml (with [project] id and default profile), the .dryrun/ data directory, and captures the database into .dryrun/history.db. Snapshots are keyed by (project_id, database_id); set database_id per profile when a project has multiple databases (e.g. auth, billing). See docs/dryrun-toml.md for the full config reference.
Option B: Someone else has database access
The person with credentials captures once and pushes to a shared directory — one that lives in the repo, or anywhere both sides can reach:
dryrun init --db "$DATABASE_URL"
dryrun snapshot push --to-path ./snapshots
They commit both dryrun.toml and ./snapshots. Everyone else pulls:
dryrun snapshot pull --from-path ./snapshots
snapshot pull loads the snapshot into .dryrun/history.db. No database needed on their machine.
Committing dryrun.toml is not optional: snapshots are keyed by (project_id, database_id), and dryrun init bakes database_id from the live database name. A teammate who runs dryrun init without --db gets a different database_id, and pull then reports 0 copied because it looked under a key the source does not have.
A pushed snapshot carries planner and activity stats alongside the schema, so the offline tools that need sizing and vacuum data work too — which a plain JSON export cannot do. For a registry instead of a directory, see dryrun remote add and snapshot push --remote. To hand a human or an agent readable JSON, dryrun dump-schema still writes it; it is an export, not an input.
Then use it
dryrun lint
All commands work offline from .dryrun/history.db. Each project has its own dryrun.toml and .dryrun/, there is no global state. Add .dryrun/ to your .gitignore.
Snapshots live in .dryrun/history.db, keyed by (project_id, database_id). It is the only schema source: the MCP server, lint and drift all read from it. A .dryrun/schema.json left over from an older dryrun is ignored.
To keep the history outside the project, set DRYRUN_HISTORY_DB to an absolute path: every command uses that file instead of .dryrun/history.db, from any directory. That suits a shared reader — a timer runs snapshot pull into one file, and MCP servers started in any checkout read it. --history-db still wins. Start the timer first: a server that starts before the file exists stays uninitialized until restarted. A relative value is refused — an unexpanded ~ (common in MCP JSON configs) fails loudly instead of creating ./~.
The database runs in SQLite's WAL mode so a scheduled snapshot capture and a long-lived mcp-serve can share it: the capture commits while the server is mid-query, instead of one waiting the other out. WAL adds history.db-wal and history.db-shm sidecars next to it, removed when the last process exits cleanly and left behind by a crash, so ignore them alongside .dryrun/. Two consequences worth knowing: a WAL history.db needs write access to the file and its directory (.dryrun/, or the parent of $DRYRUN_HISTORY_DB) even for read-only commands like lint, so a shared history read by several users needs a group that can write both; and WAL needs shared memory, which network filesystems do not provide — a .dryrun/ on NFS or SMB keeps the rollback journal automatically (correct, just slower under contention).
Multi-node: capture activity from replicas
snapshot capture on the primary writes schema and planner stats. Activity counters (idx_scan, n_dead_tup, last vacuum) live on each replica, so capture those too:
dryrun --profile primary snapshot capture --label primary
dryrun snapshot capture --from "$REPLICA1_URL" --label replica1
dryrun snapshot capture --from "$REPLICA2_URL" --label replica2
With [[node]] blocks in dryrun.toml, dryrun snapshot capture --all does all of them in one go.
The MCP describe_table (node breakdown) and detect kind=anomalies tools then expose per-node idx_scan so you can spot routing imbalances. See docs/multi-node-stats.md.
Multiple databases per project
dryrun snapshot capture keys snapshots by (project_id, database_id). The defaults work — project_id is your folder name, database_id is the actual database name from current_database():
dryrun init --db "$AUTH_DB" # captures auth
dryrun snapshot capture --db "$BILLING_DB" --label primary # billing gets its own stream
dryrun snapshot list --db "$AUTH_DB" # only auth snapshots
For stable refs (and so list / diff can run without retyping URLs), declare profiles in dryrun.toml:
[project]
id = "myapp"
[profiles.auth]
db_url = "${AUTH_DATABASE_URL}"
database_id = "auth"
[profiles.billing]
db_url = "${BILLING_DATABASE_URL}"
database_id = "billing"
Then:
dryrun --profile billing snapshot list
dryrun --profile billing snapshot diff --latest
See docs/dryrun-toml.md for all profile options.
Every DB-related command (init, probe, dump-schema, drift, stats apply, all snapshot subcommands) accepts --profile and falls back to the resolved profile's db_url when --db is not provided. lint is offline: it reads .dryrun/history.db and only touches a live database when you pass --db explicitly.
Note: the MCP server is currently single-database. Using the default profile. Or the option is to run one
dryrun mcp-serveprocess per database. Native multi-database support inside one MCP process is tracked in #7.
Sharing snapshots across a team
DryRun's value increases in team setup. Multiple developers can pull snapshots from any POSIX compliant directory.
To publish the snapshots you need
cd project_name
# capture from the live DB (use cwd name for project name)
dryrun init --db "$DATABASE_URL"
dryrun snapshot capture --db "$DATABASE_URL" --label primary
dryrun snapshot push --to-path ./snapshots --all
Developers can then import the snapshots to the local history
dryrun snapshot pull --from-path ./shared/snapshots --all
Snapshots are content-addressed ({project}/{database}/{ts}-{hash}.json.zst) and idempotent: pushing the same snapshot twice won't change it.
The simplest deployment is a dedicated git repo. Create the snapshots repo and add *.json.zst binary to .gitattributes so git stops trying to diff bundles.
Offline tools (lint, check_migration, drift) work immediately after the pull.
No server, no credentials. Same promise as before.
Push snapshots to an OCI registry
Any OCI registry can hold snapshots: GitHub Container Registry, Google Artifact Registry, Amazon ECR, Docker Hub, Harbor, or a self-hosted one. The registry handles authentication, retention, and access control, so there is no server to run.
Authenticate the same way you would for docker push, register the remote, and push:
docker login ghcr.io
dryrun remote add ghcr --ref ghcr.io/myorg/dryrun --default
dryrun snapshot capture --label primary --push
snapshot capture --push captures and publishes in one step. Consumers pull:
dryrun snapshot pull --remote ghcr
push and pull both move only the latest take by default, so cold pulls (fresh CI, empty history.db) and shared stores stay cheap regardless of how much history either side holds. Use --full to sync the entire history, or --since 7d (also 2w, 24h, or a UTC date like 2026-01-01) for a window. Either way the copy is incremental by content hash, so an owner that pushes on a cadence only uploads the new observations each run.
A remote that keeps its bundles stores one payload per schema hash, so it doesn't record a reverted migration as new. A fresh reader still lands on the current schema when newer stats point to it; a reader already on the superseded schema stays there until the hash changes. A writer that pushes to an empty location each run doesn't have this limit (details). pull warns if the source's newest capture is over 48 hours old.
--ref is the registry base. Each database gets its own repository under it, <ref>/<project_id>/<database_id>, so myapp's auth database lands at ghcr.io/myorg/dryrun/myapp/auth. Snapshots map to OCI artifacts addressed by content hash, so pushing the same one twice changes nothing and shared blobs deduplicate on the registry. For Google Artifact Registry, run gcloud auth configure-docker us-docker.pkg.dev in place of docker login; the rest is identical.
Authentication. By default dryrun reuses your Docker credentials (~/.docker/config.json and credential helpers), so any registry you can docker login to works with no extra config. Two overrides on remote add cover the rest:
--token-env VARreads a static bearer token from an environment variable, for registries that issue short-lived tokens (e.g.--token-env GAR_TOKENfed bygcloud auth print-access-token).--auth gcpuses Google Application Default Credentials directly, so Google Artifact Registry / Container Registry work aftergcloud auth login(or a service-account key viaGOOGLE_APPLICATION_CREDENTIALS) withoutconfigure-docker. The ADC token is refreshed automatically.
See docs/dryrun-toml.md for per-profile remotes and sharing one stream across projects.
More
- Tutorial for offline, online, and multi-node workflows with full tool reference
- Multi-node statistics for cluster-wide stats collection, aggregation rules, and replica imbalance detection
- Query stats for
pg_stat_statementscapture, shape grouping, and diffing - Anonymized snapshots for producing a snapshot you can hand to someone else: the PII mapping, masked capture, and what to check before sending
- Configuration reference for
dryrun.tomlprofiles, conventions, remotes, and lint rules - CLI stability for which commands are stable versus experimental
- Security overview for the CLI/MCP split and masking
- boringSQL, the blog and project home
- dryrun project page, overview and docs
- Don't let AI touch your production database, why most Postgres MCPs are unsafe and what
dryrundoes differently - RegreSQL, SQL regression testing and
dryrun's companion tool - Fixturize, subset and mask production data for dev/test
License
dryrun MCP questions
How do I add dryrun MCP to Claude Code?
Run claude mcp add dryrun -- npx -y @boringsql/dryrun mcp-serve in your terminal. Add --scope user to make it available in every project.
How do I add dryrun MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does dryrun MCP provide?
It exposes 9 tools, including advise, check_migration, describe_table, detect, find_objects.
Does the MCP server require a live database connection?
No, the server works entirely from an offline snapshot, meaning the assistant never sees credentials or needs a connection to the production database.
How do I share schema intelligence with my team without giving them database access?
One person with database access can capture a snapshot and push it to a shared directory in the repository; others can then pull that snapshot to use the tools offline.