dryrun

# DryRun 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](https://boringsql.com) suite alongside [RegreSQL](https://github.com/boringsql/regresql) and [Fixturize](https://github.com/boringSQL/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](https://fortune.com/2025/07/23/ai-coding-tool-replit-wiped-database-called-it-a-catastrophic-failure/), and [SQL injection in MCP servers](https://securitylabs.datadoghq.com/articles/mcp-vulnerability-case-study-SQL-injection-in-the-postgresql-mcp-server/) 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](docs/query-stats.md)** - captures `pg_stat_statements` per node, collapses ORM query variants into shapes, diffs two captures to surface new or slowed queries
- **[Multi-node stats](docs/multi-node-stats.md)** - 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 14 tools over stdio or SSE: schema exploration, 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

**Homebrew:**

Homebrew 6.0 requires third-party taps to be trusted before their formulae can load:

```sh
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:

```sh
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:

```sh
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](#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](https://go.dev/dl/).

```sh
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:

```sh
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](#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:

```sh
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:

```sh
dryrun setup
```

To pick the agents yourself, or from a non-interactive shell, pass `--agents`:

```sh
dryrun setup --agents=claude,cursor   # or: all
```

To register the server manually:

```sh
# 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:

```sh
claude mcp add dryrun -- /path/to/dryrun mcp-serve
```

Or, with no install at all, point the client at `npx`:

```sh
claude mcp add dryrun -- npx -y @boringsql/dryrun mcp-serve
```

The raw client config for this form is:

```json
{
  "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](#quickstart)), then call the `reload_schema` tool from the assistant. The new schema is picked up without restarting the server.

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](https://github.com/boringSQL/dryrun/issues/7).

See the [Tutorial](TUTORIAL.md) 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:

```sh
dryrun init --db "$DATABASE_URL"
```

This creates `dryrun.toml` (with `[project]