Guide / 01 · PostgreSQL documentation

Generate an ER diagram from migrations, without a database.

Your repository already describes how the schema was built. Database Migration ERD reads that SQL history and turns the supported structure into a diagram.

This workflow is useful when you want documentation in a pull request, a local overview of an unfamiliar schema, or a CI-generated image without provisioning a database. Everything is processed locally; no database credentials are needed.

Start with the complete SQL history

This guide uses PostgreSQL-compatible SQL. The current parser uses that dialect; accepting common SQL from another database does not imply full support for its migration syntax. Check the SQL compatibility notes first.

Install the CLI and D2 using the installation instructions. Then point the tool at your migration directory and the output SVG:

migration-erd ./db/migrations ./docs/schema.svg

Open the SVG in a browser. Types and index descriptions are visible by default. The command does not leave a D2 sidecar or a directory of candidate diagrams.

Versioned V<number>__description.sql files use numeric order; other SQL files use path order. sql-migrate and goose Up sections are supported, and .down.sql files are skipped. Include the migrations needed to create the tables before altering or referencing them.

Try the published 64-table example

The release contains a fictional schema with 551 columns, 69 foreign keys and six name-based families. Run these commands in an empty working directory:

mkdir -p migrations
curl --fail --location \
  https://github.com/fightingBald/database-migration-erd/releases/download/v0.2.0/dummy-64.sql \
  --output migrations/V1__dummy.sql
migration-erd ./migrations ./schema.svg

No layout configuration is needed. The published comparison shows the same input rendered as a native D2 baseline and through the tool's default refinement. This particular canvas is 40.1% smaller and its longest connection is 22.1% shorter. Results depend on the schema; the refinement also permits a bounded increase in crossings.

How related tables stay together

Table names and FK relationships suggest groups. D2 and ELK lay out tables, then the tool evaluates candidate arrangements using actual SVG dimensions. For eligible stretched diagrams, it lays out groups independently, packs their rectangles and routes cross-group connections around tables and other groups.

Validation checks table membership, fields, index captions, foreign-key endpoints, overlap and clipping. A candidate must meet the quality thresholds before replacing the native result. You can override groups and colours with --layout-config, or add missing relationships with --fk-config.

Choose the right source of truth

This is static parsing, not a PostgreSQL execution engine. Straight-line supported DDL in dollar-quoted DO blocks can be modeled; arbitrary loops, dynamic structural SQL, search_path semantics and routine side effects cannot. Views are outside the table-and-FK diagram. Routine definitions and supported administrative commands are skipped.

If your schema is mostly created through procedural code, use a reviewed ordinary-DDL snapshot or a tool that inspects the resulting database. If your migrations are Python or another programming language, provide SQL rather than those source files. See the supported SQL and diagnostics before integrating.

When parsing fails, the command exits nonzero and preserves the requested SVG. A separate INCOMPLETE preview may help diagnosis. It should never be treated as the authoritative schema.

Next: automatically update database diagrams in CI and Docusaurus →