Dryrun

Install

Homebrew:

brew install boringsql/boringsql/dryrun

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.

Quickstart

There are two ways to get started, pick whichever fits your setup.

30-second demo

Point dryrun at any schema JSON file (see examples/demo for a ready-made one):

cd examples/demo
dryrun lint

[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()

22 violation(s): 6 error, 16 warning, 0 info (13 tables checked)

No database needed. Works entirely from the JSON file.

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 introspects the database into .dryrun/schema.json. 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 exports the schema once:

dryrun dump-schema --source "$DATABASE_URL" --pretty --name "production" -o schema.json

They commit schema.json to the repo (or share it however you like). Everyone else initializes and imports:

dryrun init
dryrun import schema.json

dryrun init creates dryrun.toml and .dryrun/. dryrun import loads the snapshot. No database needed on their machine.

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 single JSON snapshot. 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
• Schema diff - compare snapshots over time, detect drift between live database and saved state
• Multi-node stats - per-replica statistics, seq_scan hotspots, routing imbalances