dbscope

Understand your database before you touch it.

Read-only schema intelligence for SQL databases.
Graph-based risk scoring · Blast radius analysis · CI gating · Migration preview
Deterministic. Offline. No telemetry.

Problem · Install · Example · Commands · Risk Model · How It's Different · CI · Architecture

The Problem

Schema migrations cause production outages. Circular foreign key dependencies hide in plain sight. Orphan tables accumulate silently. Teams drop tables without understanding the blast radius. Nobody has a complete picture of their schema's structural health.

Migration linters (squawk, Atlas, pgfence) tell you if your SQL is dangerous. dbscope tells you which tables you shouldn't touch in the first place.

It connects to your database (read-only), builds a relational graph of every table, column, index, constraint, and foreign key, computes deterministic risk scores, and generates offline reports. Same schema, same query log, same scores - every time.

Supports: PostgreSQL · MySQL · SQLite · ClickHouse

Install

cargo install dbscope

Or with Homebrew:

brew install jayvenn21/tap/dbscope

Or build from source:

git clone https://github.com/jayvenn21/dbscope.git
cd dbscope
cargo build --release

Example

No database needed. Run the built-in demo to see what dbscope does:

$ dbscope demo

  Schema
    tables    17  (2 orphans: feature_flags, schema_migrations)
    columns   75
    indexes   13
    FKs       17  (self-ref: categories.parent_id)
    queries   23 analyzed

  Risk
    0 critical  0 high  0 medium  3 orphans

  Top Risk
    public.products                0.10 (Low)
    public.users                   0.10 (Low)
    public.orders                  0.10 (Low)
    public.reviews                 0.06 (Low)
    public.categories              0.05 (Low)

  Missing Indexes
    public.reviews.product_id  3 WHERE hits
    public.inventory.product_id  2 WHERE hits

  Cold Tables
    public.addresses
    public.wishlist_items
    public.coupons

  Reports
    ./dbscope-report.html  open in browser
    ./dbscope-report.json  machine-readable
    ./dbscope-graph.dot    render with: dot -Tsvg ... -o graph.svg

Point it at a real database:

export DBSCOPE_SCHEMA_URI="postgres://user:pass@localhost:5432/mydb"

dbscope analyze                          # full schema analysis + reports
dbscope impact public.users              # blast radius of a single table
dbscope impact public.users.email        # blast radius of a single column
dbscope ci --threshold 0.5              # fail if any table risk > 0.5
dbscope summarize                        # plain-language overview
dbscope plan drop public.legacy_orders   # safe drop plan with FK ordering

Reports: dbscope-report.html, dbscope-report.json, dbscope-report.md, dbscope-graph.dot - use -o DIR to set output directory.

How dbscope Is Different

	Migration linters (squawk, Atlas, pgfence)	dbscope
What it analyzes	SQL migration files	Your live database schema
How it works	Pattern-matches dangerous DDL	Builds a relational graph, computes structural risk
Risk model	"This DDL acquires ACCESS EXCLUSIVE lock"	"This table has 0.82 risk because of FK depth, cycle membership, and centrality"
Blast radius	Which queries this migration blocks	Which tables, indexes, and queries are affected if you change this table
Operational data	Table size estimates	Real `pg_stat_user_tables` (row counts, insert/update/delete rates)
CI gating	Fail if DDL is risky	Fail if schema structure exceeds policy thresholds
Multi-database	PostgreSQL only (most)	PostgreSQL, MySQL, SQLite, ClickHouse

Use both. dbscope for schema intelligence, squawk/Atlas for migration linting. They're complementary.

Commands

All commands accept --schema URI or the DBSCOPE_SCHEMA_URI environment variable.

analyze

Extract schema, build graph, compute metrics, generate reports.

dbscope analyze --schema <URI>
dbscope analyze --schema <URI> -o <DIR>
dbscope analyze --schema <URI> --query-log <FILE>

Option	Description
`--schema`	Connection URI. Required unless `DBSCOPE_SCHEMA_URI` is set.
`-o`, `--output`	Output directory for reports (default: current directory).
`--query-log`	One SQL per line - enables cold/hot tables, index suggestions.

impact

Blast radius for a table or column: downstream/upstream FKs, index coupling, affected queries, risk breakdown.

Target formats: users, users.email, public.users, public.users.email

dbscope impact <TARGET> --schema <URI>
dbscope impact <TARGET> --schema <URI> --query-log <FILE>

plan

Safe refactor plan for dropping a table: lists FKs to drop first, then the DROP TABLE step. Read-only - apply changes manually.

dbscope plan drop public.users --schema <URI>

preview

Simulate a migration and report structural delta, risk delta, blast radius, and policy result.

dbscope preview <MIGRATION.sql> --schema <URI>
dbscope preview <MIGRATION.sql> --schema <URI> --query-log <FILE> --policy dbscope.policy.yaml

Output: tables removed, FKs removed, new cycles, risk delta, % of schema graph impacted, observed queries broken, then Policy PASS/FAIL.

Option	Description
`--query-log`	Count queries that reference removed tables.
`--policy`	YAML policy file. Exit 1 on violation.

ci

CI gate: exit 1 if schema risk exceeds threshold or policy. Optional --migration to simulate DDL first.

dbscope ci --schema <URI>
dbscope ci --schema <URI> --threshold 0.5 --migration <FILE>
dbscope ci --schema <URI> --policy dbscope.policy.yaml

Option	Description
`--threshold`	Fail if any table risk > this (0–1). Default: 0.5. Ignored if `--policy` is set.
`--migration`	DDL file to simulate before checking risk.
`--policy`	YAML policy: `max_table_risk`, `no_cycles`, `no_orphans`, `max_blast_radius_percent`.

summarize

Table/column/FK counts, risk overview, orphans, cycles. With --query-log: cold/hot tables, index suggestions.

dbscope summarize --schema <URI>
dbscope summarize --schema <URI> --query-log <FILE>

explain

Explain a risk score or index recommendation in plain language.

KIND: risk or index-suggestion

dbscope explain risk <TABLE> --schema <URI>
dbscope explain index-suggestion <TABLE> <COLUMN> --schema <URI> --query-log <FILE>

demo

Run a demo analysis on an embedded e-commerce schema - no database required. Great for trying dbscope without a connection.

dbscope demo
dbscope demo -o demo-reports/

snapshot

Save the current schema to a JSON file for offline auditing or diffing later.

dbscope snapshot --schema <URI>
dbscope snapshot --schema <URI> -o schema-2026-05-05.json

diff

Compare two schema snapshots, or compare a snapshot against a live database. Shows structural delta: tables added/removed, columns changed, FKs modified.

dbscope diff before.json after.json
dbscope diff before.json postgres://user:pass@localhost/mydb

lint

Detect schema anti-patterns: missing primary keys, wide tables, missing FK indexes, naming inconsistencies.

dbscope lint --schema <URI>
dbscope lint --schema <URI> --json

deps

Show the full FK dependency tree for a table - upstream (what it references) and downstream (what references it).

dbscope deps users --schema <URI>
dbscope deps public.orders --schema <URI> --json

mcp

Run dbscope as an MCP (Model Context Protocol) server over stdio. Exposes schema analysis as tools for AI assistants like Claude, Cursor, and Copilot.

dbscope mcp

completions

Generate shell completions for your shell.

dbscope completions bash >> ~/.bashrc
dbscope completions zsh >> ~/.zshrc
dbscope completions fish > ~/.config/fish/completions/dbscope.fish

CI Integration

GitHub Actions

- name: Schema health check
  run: |
    cargo install dbscope
    dbscope ci --schema ${{ secrets.DATABASE_URL }} --policy dbscope.policy.yaml

Policy File

Copy dbscope.policy.example.yaml to dbscope.policy.yaml:

max_table_risk: 0.5
no_cycles: false
no_orphans: false
max_blast_radius_percent: 50

Exit Codes

Code	Meaning
`0`	All checks passed
`1`	Risk or policy violation detected
`2`	Connection or parse error

Risk Model

All scores are deterministic - same schema + same query log = same scores. Full specification: docs/risk_model.md.

Table Risk (structural)

risk = depth_contrib (max 0.4) + cycle_contrib (0.3 if in FK cycle) + centrality_contrib (max 0.3)

FK depth: Max path length following outgoing and incoming FK edges.
Cycle: 0.3 if the table participates in a circular FK dependency.
Centrality: Number of direct FK neighbors (in-degree + out-degree).

Operational Weighting (Postgres)

When connected to Postgres, risk is adjusted by live activity data from pg_stat_user_tables:

effective_risk = structural_risk × operational_weight (0.2–1.0)

Impact (blast radius)

impact = 0.4 × FK_reach + 0.3 × index_coupling + 0.3 × query_usage_weight

Score	Level	Meaning
0.75–1.0	Critical	Very central, deep in FK chains, and/or in a cycle
0.50–0.75	High	Significant centrality or depth
0.25–0.50	Moderate	Some dependency depth or centrality
0–0.25	Low	Few dependencies, shallow in graph

Reports

Every analyze run generates four report formats:

Markdown - Human-readable summary
HTML - Static report with risk visualization
JSON - Machine-readable for pipelines and dashboards
Graphviz - Dependency graph (render with dot -Tpng dbscope-graph.dot -o graph.png)

All reports are generated offline. No external services.

Architecture

dbscope builds a canonical relational graph from database metadata. Connectors normalize each engine's catalog into a universal RawSchema model. All analysis runs on this graph - the core never branches on database type.

Connector → RawSchema → DatabaseGraph → Analysis → Reports
   │                         │                │
   ├─ PostgresConnector      ├─ petgraph       ├─ risk metrics
   ├─ MysqlConnector         ├─ cycle detect   ├─ impact/blast radius
   ├─ SqliteConnector        ├─ centrality     ├─ usage analysis
   └─ ClickhouseConnector    └─ FK depth       └─ index suggestions

Performance: Sub-ms in-memory for typical schemas. End-to-end cost is dominated by DB metadata extraction. Run cargo bench for benchmarks.

Full architecture doc: docs/architecture.md

Philosophy

Read-only - dbscope never modifies your database
Deterministic - Same input, same output, every time
Explainable - Every score has a documented formula
CLI-first - Works in your terminal and CI pipeline
Offline - No external services, no network calls
No telemetry - Nothing leaves your machine

Documentation

Risk Model - Full scoring specification
Architecture - Universal model, connectors, pipeline
Positioning - How dbscope compares to migration linters
Contributing - Guidelines for contributors
Changelog - Release history
Security - Vulnerability reporting

License

MIT OR Apache-2.0

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.github		.github
action		action
benches		benches
docs		docs
homebrew		homebrew
src		src
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
dbscope.policy.example.yaml		dbscope.policy.example.yaml

Folders and files

Latest commit

History

Repository files navigation

dbscope

The Problem

Install

Example

How dbscope Is Different

Commands

analyze

impact

plan

preview

ci

summarize

explain

demo

snapshot

diff

lint

deps

mcp

completions

CI Integration

GitHub Actions

Policy File

Exit Codes

Risk Model

Table Risk (structural)

Operational Weighting (Postgres)

Impact (blast radius)

Reports

Architecture

Philosophy

Documentation

License

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages