SQL migrations → SVG
SQL migrations.
Readable ER diagrams.
Turn migration SQL into an ER diagram with automatically grouped tables and compact layouts. Run it locally or in CI, without connecting to a database.
Currently uses a PostgreSQL dialect parser. Compatible SQL from other databases may work; complete support for other dialects is not verified. Check SQL compatibility →
# migration directory output diagram
migration-erd ./db/migrations ./docs/schema.svgA measured example
Give related tables room to belong.
Clusters are laid out individually, placed using their rendered dimensions, then connected across groups. Geometry checks decide whether to keep the refined result.
Same fictional input, D2 0.7.1, ELK, default options; no hand-placed tables or layout YAML. This compares our native baseline with our refinement, not with another product. Thumbnails fit their panels. 551 columns and 69 FKs are retained. Distinct crossing locations increase from 3 to 12: compactness is a tradeoff, not a promise of fewer crossings. Full measurements · Reproduce with the dummy SQL.
Built for the schema already in your repository.
01 / READ THE HISTORY
Migration-aware input
Process forward table and index changes, sql-migrate/goose Up sections and supported PostgreSQL DO blocks. SQL is parsed locally, never executed.
02 / KEEP THE DETAIL
More than table boxes
Show column types, composite and self-referencing foreign keys, and index descriptions below tables. Supply missing relationships with a small YAML file.
03 / FIT THE WORKFLOW
A small codegen step
Produce one SVG by default. Errors return a failing exit code and preserve the previous diagram. Embed the runtime under tools/ or install the CLI package.
Get started
A directory in. A diagram out.
Install pipx with Python 3.11+, and put D2 0.7.1 on PATH. Then install the versioned wheel:
pipx install https://github.com/fightingBald/database-migration-erd/releases/download/v0.2.1/migration_erd-0.2.1-py3-none-any.whl
migration-erd ./migrations ./schema.svgOpen schema.svg in a browser. D2 is a separate renderer dependency. D2 source export is explicit; terminal diagnostics do not create log files by default. Source installation and configuration →
Choose by workflow
Where Database Migration ERD fits.
Different inputs call for different tools. This is a workflow comparison, not a performance ranking.
| Tool | Typical starting point | Good fit |
|---|---|---|
| Database Migration ERD | SQL migration files, read with a PostgreSQL dialect parser | Locally generated SVGs with automatic groups and measured layout refinement, embedded in codegen or documentation builds. |
| SchemaSpy | A database accessed through JDBC | Rich database documentation, schema exploration and reports across database engines. |
| tbls | A database connection or supported schema data, including offline JSON | CI-friendly database documentation, diagrams, linting and schema diffs across supported data sources. |
| DBML / dbdiagram | A DBML model or imported SQL structure | Schema modeling and conversion between SQL and DBML, with a visual design workflow. |
Database Migration ERD consumes existing SQL migrations; it does not generate or apply migration scripts. A migration tool such as Alembic serves a different purpose. Python migration files are not an input format.
Take it into your project.
Before you plug it in.
Does it connect to a database or upload my SQL?
The generator reads local migration files and invokes the local D2 renderer. It does not connect to your database or upload SQL. Installing dependencies requires network access; optional TALA has its own licensing requirements.
Which databases and migration formats are supported?
Input is SQL files, including sql-migrate and goose Up sections, not Python or other ORM migration source code. The parser currently uses the PostgreSQL dialect. Compatible SQL from other databases may work, but complete MySQL, SQLite and SQL Server migration support is not verified. There is no dialect selector.
It models supported table, column, constraint and index changes. It skips ERD-neutral setup commands and routine definitions. Arbitrary procedural code, search_path resolution, partition semantics and routine side effects are not modeled. Unsupported structural statements produce diagnostics. Read the SQL support contract.
What happens if a migration cannot be parsed?
The command returns a nonzero exit code and preserves the requested SVG. Where possible it writes a separately marked INCOMPLETE partial preview. CI should stop rather than publish that preview.
Can I choose groups or use tables without FK constraints?
Groups are inferred from names and relationships. YAML can override group membership, titles and colours; a separate FK configuration can describe relationships missing from SQL. Tables without relationships are still included.