dryrun

The Offline-First PostgreSQL MCP That Won't Ruin Your Production

Capture your schema and statistics into a portable snapshot. Lint it, diff it, validate queries against it, and hand it to your AI assistant. No production credentials on developer machines.

Get dryrun GitHub Repository

How It Works

# Initialize and introspect the database (once)
dryrun init --db "$DATABASE_URL"

# Capture a snapshot: schema, planner statistics, activity counters
dryrun snapshot take

# What changed since the last capture?
dryrun snapshot diff --latest

# Lint conventions, PK types, uncovered foreign keys, partition gaps
dryrun lint

# Share the history; everyone else works offline
dryrun snapshot push --to-path ./snapshots --all
dryrun snapshot pull --from-path ./snapshots --all

# Serve as MCP server for Claude or other AI assistants
dryrun mcp-serve

Features

Portable Snapshots

One command introspects the full catalog: tables, columns, indexes, constraints, partitions, functions, enums, RLS policies, triggers, extensions, GUCs, and per-table planner statistics. Snapshots are content-addressed and keyed by project and database, so pushing the same capture twice changes nothing.

History and Diffing

Captures accumulate in a local history db. Diff any two of them across schema, planner statistics, or activity counters, scoped to a schema or a single table. Drift detection compares a saved snapshot against a live database when you want a connection.

Detection Over Statistics

Stale statistics, unused indexes, bloated tables and indexes, and per-node activity anomalies, read from captured counters rather than guessed. Results carry pre-validated follow-up calls, so an agent can narrow from a summary to one table without inventing arguments.

Schema Linting

19 convention rules covering naming, primary key types, varchar versus text, missing timestamps, FK index coverage, and partition health, plus structural audit rules for duplicate indexes and circular foreign keys. Configurable severity, per-rule disabling, custom naming patterns.

Query and Plan Analysis

Parses SQL via libpg_query against your captured schema to catch non-existent columns and anti-patterns. Feed it an EXPLAIN plan and it analyzes the plan against the schema, with index suggestions. No execution required.

Migration Guardrail

Run DDL through a lock and rewrite check before you apply it. ALTER TABLE, CREATE INDEX, and RENAME operations come back with a lock type, how long it holds, a safety rating, and a safer alternative, plus rollback DDL and version-specific behavior where they apply. The ALTER that quietly rewrites a table gets caught in review.

Multi-Node Stats

Activity counters live on each replica, so capture them separately and label them. Per-node idx_scan then exposes routing imbalances and seq_scan hotspots that a primary-only capture cannot see.

MCP Server for AI

14 tools give Claude and other assistants schema awareness from the snapshot alone, over stdio or SSE. The assistant never sees a connection string.

Installation

Homebrew

brew trust --tap boringsql/boringsql && brew install boringsql/boringsql/dryrun

npx (no install)

npx @boringsql/dryrun --version

npm (global)

npm install -g @boringsql/dryrun

From source (Go 1.26+)

go build -o bin/dryrun ./cmd/dryrun

The `brew trust` step is required on Homebrew 6.0 and later; skip it on 5.x. Prebuilt binaries cover macOS (Apple Silicon and Intel), Linux (x64 and arm64), and Windows x64. On Alpine/musl or Windows arm64, build from source.

Why dryrun?

AI coding assistants write SQL blind. They don't know your schema, your indexes, or your constraints, so they generate migrations that take ACCESS EXCLUSIVE locks on busy tables, add varchar(255) columns when you use text, or create indexes that already exist.

Most PostgreSQL MCP servers answer this by asking for a database connection, and the administrative tools push you toward a superuser role. That trades one problem for a worse one. We have already seen where it leads: production databases wiped by agents, and SQL injection in MCP servers that were supposed to be read-only.

The model does not need to query your database. It needs to understand it. That knowledge is structural: it changes when you deploy a migration, not between queries. So capture it once, put it in a file, and hand the file around.

Capture once, work offline

dryrun is a CLI and an MCP server, deliberately separate. The CLI is the only part that ever touches PostgreSQL. It introspects the catalog and writes a snapshot. Everything after that reads the snapshot.

One person with database access captures. Everyone else, humans and agents alike, gets full schema intelligence without a connection string. CI runners included.

# The person with credentials
dryrun init --db "$DATABASE_URL"
dryrun snapshot take
dryrun snapshot push --to-path ./snapshots --all

# Everyone else
dryrun snapshot pull --from-path ./snapshots --all
dryrun lint

Snapshots are content-addressed, so pushing the same capture twice is a no-op and a shared history deduplicates. A shared directory works, as does a dedicated git repo. So does any OCI registry, and that is usually the better choice: GitHub Container Registry, Google Artifact Registry, Amazon ECR, or a self-hosted one already handles authentication, retention, and access control, so there is no server to run.

dryrun remote add ghcr --ref ghcr.io/myorg/dryrun --default
dryrun snapshot take --push

Consumers pull only the latest capture by default, so a cold CI runner stays cheap no matter how much history the registry holds.

One capture is a fact, a series is a trend

The snapshot carries planner statistics and activity counters, not just DDL. Once you have more than one, you can answer offline the questions that usually need a monitoring stack.

snapshot diff compares any two captures across schema, planner statistics, or activity, scoped to a schema or a single table. detect reads the captured counters for stale statistics, indexes that no longer take scans, tables and indexes accumulating bloat, and per-node activity anomalies. When you do want a live connection, drift tells you whether the database still matches the snapshot you have been working against.

A single \d+ dump gives you none of this.

Use Cases

AI-assisted database development

Install dryrun as an MCP server and your assistant gains schema awareness. It stops hallucinating column names, suggests indexes, and reads the same statistics you do.

claude mcp add dryrun -- dryrun mcp-serve

With no install at all, point the client at npx instead:

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

The server auto-discovers the project's snapshot, so there is nothing further to configure.

Reviewing a schema you inherited

lint gives you the convention and structural problems in one pass: tables without primary keys, foreign keys with no covering index, timestamp where you meant timestamptz, serial where you meant identity, gaps in range partitions. detect adds the statistical layer: which indexes are not being used, what is bloated, where statistics have gone stale.

Pre-deploy migration review

Run the DDL through the lock and rewrite check before it reaches a review, and again in CI. It flags the operations that behave differently than they read: a column type change that rewrites the table, a constraint added without NOT VALID, an index built without CONCURRENTLY, a SET NOT NULL that scans every row. Each one comes back with the lock it takes and a safer way to do it.

Schema governance across teams

Enforce naming conventions, require timestamps, ban varchar in favor of text, and flag tables without primary keys. One dryrun.toml keeps the whole team aligned, and the rules run without a database, so they run in CI.