{"id":45544267,"url":"https://github.com/jayvenn21/dbscope","last_synced_at":"2026-05-03T21:03:52.223Z","repository":{"id":340066791,"uuid":"1164362009","full_name":"jayvenn21/dbscope","owner":"jayvenn21","description":"Universal relational schema intelligence CLI — analyze risk, blast radius, and structural health before changing your database.","archived":false,"fork":false,"pushed_at":"2026-02-23T03:52:16.000Z","size":20389,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-23T09:19:01.153Z","etag":null,"topics":["analysis","ci","cli","clickhouse","database","database-tools","devops","devtools","infrastructure","mysql","postgres","rust","schema","sqlite","static-analysis"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jayvenn21.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-23T01:48:05.000Z","updated_at":"2026-02-23T03:52:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jayvenn21/dbscope","commit_stats":null,"previous_names":["jayvenn21/dbscope"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jayvenn21/dbscope","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayvenn21%2Fdbscope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayvenn21%2Fdbscope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayvenn21%2Fdbscope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayvenn21%2Fdbscope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jayvenn21","download_url":"https://codeload.github.com/jayvenn21/dbscope/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayvenn21%2Fdbscope/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32584654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analysis","ci","cli","clickhouse","database","database-tools","devops","devtools","infrastructure","mysql","postgres","rust","schema","sqlite","static-analysis"],"created_at":"2026-02-23T04:39:29.474Z","updated_at":"2026-05-03T21:03:52.217Z","avatar_url":"https://github.com/jayvenn21.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003edbscope\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Understand your database before you touch it.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/jayvenn21/dbscope/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/jayvenn21/dbscope\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://crates.io/crates/dbscope\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/dbscope\" alt=\"crates.io\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/postgres-supported-blue\" alt=\"Postgres\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/mysql-supported-blue\" alt=\"MySQL\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/sqlite-supported-blue\" alt=\"SQLite\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/read--only-safe-success\" alt=\"Read Only\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/risk-deterministic-purple\" alt=\"Risk Model\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT%2FApache--2.0-lightgrey\" alt=\"License\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Read-only schema intelligence for SQL databases.\u003cbr\u003e\n  Graph-based risk scoring · Blast radius analysis · CI gating · Migration preview\u003cbr\u003e\n  Deterministic. Offline. No telemetry.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#the-problem\"\u003eProblem\u003c/a\u003e ·\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e ·\n  \u003ca href=\"#commands\"\u003eCommands\u003c/a\u003e ·\n  \u003ca href=\"#risk-model\"\u003eRisk Model\u003c/a\u003e ·\n  \u003ca href=\"#how-dbscope-is-different\"\u003eHow It's Different\u003c/a\u003e ·\n  \u003ca href=\"#reports\"\u003eReports\u003c/a\u003e ·\n  \u003ca href=\"#ci-integration\"\u003eCI\u003c/a\u003e ·\n  \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e ·\n  \u003ca href=\"docs/cloud.md\"\u003eCloud\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## The Problem\n\nSchema 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.\n\nMigration linters (squawk, Atlas, pgfence) tell you if your SQL is dangerous. **dbscope tells you which tables you shouldn't touch in the first place.**\n\nIt 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.\n\n**Supports:** PostgreSQL · MySQL · SQLite · ClickHouse\n\n---\n\n## Example\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"dbscope.gif\" width=\"850\" alt=\"Terminal demo: analyze, impact, ci\"\u003e\n\u003c/p\u003e\n\n---\n\n## Quick Start\n\n```bash\n# Install from source\ncargo install --path .\n\n# Or build locally\ncargo build --release\n\n# Set your connection URI\nexport DBSCOPE_SCHEMA_URI=\"postgres://user:pass@localhost:5432/mydb\"\n\n# Analyze your schema\ndbscope analyze\n\n# Check blast radius of a specific table\ndbscope impact public.users\n\n# Get a plain-language summary\ndbscope summarize\n```\n\n**Reports:** `dbscope-report.html`, `dbscope-report.json`, `dbscope-report.md`, `dbscope-graph.dot`\n\nUse `-o DIR` to set output directory.\n\n---\n\n## How dbscope Is Different\n\n| | Migration linters (squawk, Atlas, pgfence) | **dbscope** |\n|---|---|---|\n| **What it analyzes** | SQL migration files | Your live database schema |\n| **How it works** | Pattern-matches dangerous DDL | Builds a relational graph, computes structural risk |\n| **Risk model** | \"This DDL acquires ACCESS EXCLUSIVE lock\" | \"This table has 0.82 risk because of FK depth, cycle membership, and centrality\" |\n| **Blast radius** | Which queries this migration blocks | Which tables, indexes, and queries are affected if you change this table |\n| **Operational data** | Table size estimates | Real `pg_stat_user_tables` (row counts, insert/update/delete rates) |\n| **CI gating** | Fail if DDL is risky | Fail if schema structure exceeds policy thresholds |\n| **Multi-database** | PostgreSQL only (most) | PostgreSQL, MySQL, SQLite, ClickHouse |\n\n**Use both.** dbscope for schema intelligence, squawk/Atlas for migration linting. They're complementary.\n\n---\n\n## Commands\n\nAll commands accept `--schema URI` or the `DBSCOPE_SCHEMA_URI` environment variable.\n\n### analyze\n\nExtract schema, build graph, compute metrics, generate reports.\n\n```bash\ndbscope analyze --schema \u003cURI\u003e\ndbscope analyze --schema \u003cURI\u003e -o \u003cDIR\u003e\ndbscope analyze --schema \u003cURI\u003e --query-log \u003cFILE\u003e\n```\n\n| Option | Description |\n|--------|-------------|\n| `--schema` | Connection URI. Required unless `DBSCOPE_SCHEMA_URI` is set. |\n| `-o`, `--output` | Output directory for reports (default: current directory). |\n| `--query-log` | One SQL per line - enables cold/hot tables, index suggestions. |\n\n### impact\n\nBlast radius for a table or column: downstream/upstream FKs, index coupling, affected queries, risk breakdown.\n\n**Target formats:** `users`, `users.email`, `public.users`, `public.users.email`\n\n```bash\ndbscope impact \u003cTARGET\u003e --schema \u003cURI\u003e\ndbscope impact \u003cTARGET\u003e --schema \u003cURI\u003e --query-log \u003cFILE\u003e\n```\n\n### plan\n\nSafe refactor plan for dropping a table: lists FKs to drop first, then the DROP TABLE step. Read-only - apply changes manually.\n\n```bash\ndbscope plan drop public.users --schema \u003cURI\u003e\n```\n\n### preview\n\nSimulate a migration and report structural delta, risk delta, blast radius, and policy result.\n\n```bash\ndbscope preview \u003cMIGRATION.sql\u003e --schema \u003cURI\u003e\ndbscope preview \u003cMIGRATION.sql\u003e --schema \u003cURI\u003e --query-log \u003cFILE\u003e --policy dbscope.policy.yaml\n```\n\nOutput: tables removed, FKs removed, new cycles, risk delta, % of schema graph impacted, observed queries broken, then Policy PASS/FAIL.\n\n| Option | Description |\n|--------|-------------|\n| `--query-log` | Count queries that reference removed tables. |\n| `--policy` | YAML policy file. Exit 1 on violation. |\n\n### ci\n\nCI gate: exit 1 if schema risk exceeds threshold or policy. Optional `--migration` to simulate DDL first.\n\n```bash\ndbscope ci --schema \u003cURI\u003e\ndbscope ci --schema \u003cURI\u003e --threshold 0.5 --migration \u003cFILE\u003e\ndbscope ci --schema \u003cURI\u003e --policy dbscope.policy.yaml\n```\n\n| Option | Description |\n|--------|-------------|\n| `--threshold` | Fail if any table risk \u003e this (0-1). Default: 0.5. Ignored if `--policy` is set. |\n| `--migration` | DDL file to simulate before checking risk. |\n| `--policy` | YAML policy: `max_table_risk`, `no_cycles`, `no_orphans`, `max_blast_radius_percent`. |\n\n### summarize\n\nTable/column/FK counts, risk overview, orphans, cycles. With `--query-log`: cold/hot tables, index suggestions.\n\n```bash\ndbscope summarize --schema \u003cURI\u003e\ndbscope summarize --schema \u003cURI\u003e --query-log \u003cFILE\u003e\n```\n\n### explain\n\nExplain a risk score or index recommendation in plain language.\n\n**KIND:** `risk` or `index-suggestion`\n\n```bash\ndbscope explain risk \u003cTABLE\u003e --schema \u003cURI\u003e\ndbscope explain index-suggestion \u003cTABLE\u003e \u003cCOLUMN\u003e --schema \u003cURI\u003e --query-log \u003cFILE\u003e\n```\n\n---\n\n## CI Integration\n\n### GitHub Actions\n\n```yaml\n- name: Schema health check\n  run: |\n    cargo install dbscope\n    dbscope ci --schema ${{ secrets.DATABASE_URL }} --policy dbscope.policy.yaml\n```\n\n### Policy File\n\nCopy `dbscope.policy.example.yaml` to `dbscope.policy.yaml`:\n\n```yaml\nmax_table_risk: 0.5\nno_cycles: false\nno_orphans: false\nmax_blast_radius_percent: 50\n```\n\n### Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | All checks passed |\n| `1` | Risk or policy violation detected |\n| `2` | Connection or parse error |\n\n---\n\n## Risk Model\n\nAll scores are deterministic - same schema + same query log = same scores. Full specification: **[docs/risk_model.md](docs/risk_model.md)**.\n\n### Table Risk (structural)\n\n```\nrisk = depth_contrib (max 0.4) + cycle_contrib (0.3 if in FK cycle) + centrality_contrib (max 0.3)\n```\n\n- **FK depth:** Max path length following outgoing and incoming FK edges.\n- **Cycle:** 0.3 if the table participates in a circular FK dependency.\n- **Centrality:** Number of direct FK neighbors (in-degree + out-degree).\n\n### Operational Weighting (Postgres)\n\nWhen connected to Postgres, risk is adjusted by live activity data from `pg_stat_user_tables`:\n\n```\neffective_risk = structural_risk × operational_weight (0.2-1.0)\n```\n\n### Impact (blast radius)\n\n```\nimpact = 0.4 × FK_reach + 0.3 × index_coupling + 0.3 × query_usage_weight\n```\n\n| Score | Level | Meaning |\n|-------|-------|---------|\n| 0.75-1.0 | **Critical** | Very central, deep in FK chains, and/or in a cycle |\n| 0.50-0.75 | **High** | Significant centrality or depth |\n| 0.25-0.50 | **Moderate** | Some dependency depth or centrality |\n| 0-0.25 | **Low** | Few dependencies, shallow in graph |\n\n---\n\n## Reports\n\nEvery `analyze` run generates four report formats:\n\n- **Markdown** - Human-readable summary\n- **HTML** - Static report with risk visualization\n- **JSON** - Machine-readable for pipelines and dashboards\n- **Graphviz** - Dependency graph (render with `dot -Tpng dbscope-graph.dot -o graph.png`)\n\nAll reports are generated offline. No external services.\n\n---\n\n## Architecture\n\ndbscope 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.\n\n```\nConnector → RawSchema → DatabaseGraph → Analysis → Reports\n   │                         │                │\n   ├─ PostgresConnector      ├─ petgraph       ├─ risk metrics\n   ├─ MysqlConnector         ├─ cycle detect   ├─ impact/blast radius\n   ├─ SqliteConnector        ├─ centrality     ├─ usage analysis\n   └─ ClickhouseConnector    └─ FK depth       └─ index suggestions\n```\n\n**Performance:** Sub-ms in-memory for typical schemas. End-to-end cost is dominated by DB metadata extraction. Run `cargo bench` for benchmarks.\n\nFull architecture doc: **[docs/architecture.md](docs/architecture.md)**\n\n---\n\n## Philosophy\n\n- **Read-only** - dbscope never modifies your database\n- **Deterministic** - Same input, same output, every time\n- **Explainable** - Every score has a documented formula\n- **CLI-first** - Works in your terminal and CI pipeline\n- **Offline** - No external services, no network calls\n- **No telemetry** - Nothing leaves your machine\n\n---\n\n## Documentation\n\n- **[Risk Model](docs/risk_model.md)** - Full scoring specification\n- **[Architecture](docs/architecture.md)** - Universal model, connectors, pipeline\n- **[Cloud](docs/cloud.md)** - dbscope Cloud product vision\n- **[Positioning](docs/positioning.md)** - How dbscope compares to migration linters\n- **[Contributing](CONTRIBUTING.md)** - Guidelines for contributors\n- **[Changelog](CHANGELOG.md)** - Release history\n- **[Security](SECURITY.md)** - Vulnerability reporting\n\n---\n\n## License\n\nMIT OR Apache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjayvenn21%2Fdbscope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjayvenn21%2Fdbscope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjayvenn21%2Fdbscope/lists"}