erdscope 0.11.0

Database, application code, or config — turn whatever you have into one explorable schema.

Live demo · Recipes · User manual · 日本語 README

erdscope generates a self-contained, interactive ER diagram and, when you want it, an Excel table-definition workbook. Start with a database, model code, a config file, or any combination of them. The result is one portable HTML file you can explore, share, and keep with your project.

pip install erdscope
erdscope demo

That is the whole quickstart. A sample shop diagram opens in your browser—no database, account, or project setup required.

Who this helps

• Onboarding onto an existing database. Point erdscope at a live MySQL/PostgreSQL/SQLite connection with a read-only account and get an explorable diagram of what's actually deployed, instead of a stale hand-drawn ERD or none at all.
• Reviewing models with no database access. Point --models at a Rails, Prisma, Django, SQLAlchemy, or Laravel project and get the same kind of diagram from static analysis alone — useful for code review or working against a codebase you don't have DB credentials for.
• Handing a schema to a client or auditor. The output is one self-contained HTML file — nothing to install or host on their end. Add notes: for the design rationale and export an Excel workbook alongside it for anyone who wants it in a spreadsheet.

Why trust it with your schema

• Runs entirely locally and sends nothing over the network beyond the database connection you give it — no telemetry, no external service involved.
• A read-only database account is enough: erdscope only ever reads schema metadata, never writes.
• The generated HTML is self-contained — no CDN dependency, nothing fetched once it's open in a browser.
• Merging DB structure, code-level associations, and your own documentation into one file is what sets erdscope apart from tools that only do one of the three.

Bring whatever schema you have

Use just one source, or combine them. Physical database facts, application-level associations, and your explicit documentation are merged into one consistent view.

The examples below use CLI arguments when that makes the input obvious. For repeatable usage, put the same settings and model sources in .erdscope.json, .erdscope.yml, or another file selected with --config. A config can also define a complete schema by itself. Explicit CLI arguments override the corresponding config values.

Pick your starting point

Explore a live database

erdscope postgres://readonly@127.0.0.1:5432/myapp -o schema.html

MySQL uses the same shape. SQLite needs no driver and works with Python's standard library:

erdscope sqlite:///path/to/app.db -o schema.html

Review application models without a database

# Rails, Prisma, Django, SQLAlchemy, or Laravel project — auto-detected
erdscope --models ./my-app -o schema.html

Sketch or document a schema from config alone

erdscope --config examples/schema-only.json -o schema.html

examples/schema-only.json is a complete, zero-database example with tables, relations, notes, and a domain group. Config can also patch or remove items supplied by another source. See the config guide.

Combine database facts, application context, and documentation

erdscope mysql://readonly@127.0.0.1:3306/myapp \
  --config .erdscope.yml \
  -o schema.html

# .erdscope.yml
models:
  - ./app/models
groups:
  - { id: sales, title: Sales, tables: [orders, order_items] }
notes:
  - id: order-retention
    target: { type: table, table: orders }
    text: Orders are retained for seven years after account closure.

This is where the layered input model shines: use the database for columns and real foreign keys, code for associations such as polymorphic or through relations, and config for corrections, domain groups, operational notes, and ADR links.

Hand off both a diagram and table definitions

erdscope sqlite:///path/to/app.db \
  -o schema.html \
  --excel table-definitions.xlsx

The HTML is self-contained and the workbook can be styled with an Excel template—useful for reviews, audits, onboarding, and documentation deliverables.

What you can do in the viewer

• Search tables, columns, comments, and attached notes.
• Focus on dependencies or dependents and control traversal depth.
• Hide tables, rearrange the layout, and move domain groups together.
• Inspect DB FKs, schema FKs, declared associations, and inferred relations.
• Save named views and share a link to the current view.
• Export the current canvas as PNG or SVG, or print it cleanly.
• Switch to dark mode; everything runs locally in the generated HTML.

Try these interactions in the live demo, or use the illustrated viewer guide.

Installation

pip install erdscope

The core CLI, SQLite reader, HTML generator, and Excel writer use only the Python standard library. Install an optional driver when you want a direct server connection:

pip install 'erdscope[mysql]'     # PyMySQL
pip install 'erdscope[postgres]'  # psycopg
pip install 'erdscope[yaml]'      # PyYAML for .yml/.yaml config
pip install 'erdscope[all]'

Prefer a single file? Download erd.py and run it with Python 3.9+:

python3 erd.py demo

Config and CLI overrides

Config is the convenient home for recurring inputs and settings. It is auto-discovered as .erdscope.json, .erdscope.yml, or .erdscope.yaml in the current directory, or you can select a file with --config. When the same setting is supplied both ways, the explicit CLI argument wins.

For every option and config key, see the CLI and config reference.

Supported inputs

erdscope is tested against MySQL 8.4, PostgreSQL 16, CPython's bundled SQLite, Rails 7.x/8.x projects, Prisma 5/6 schemas, Django 4.2/5.x models, SQLAlchemy declarative models (classic and 2.0 styles), and Laravel Eloquent models. Details and parser boundaries are listed in the compatibility guide.

Project resources

• Live demo — explore a generated shop schema.
• Recipes — task-oriented guides with copy-paste commands (日本語).
• User manual — complete setup, viewer, config, export, and troubleshooting guide.
• Examples — ready-to-run SQLite and config-only inputs.
• Changelog — features and behavior by release.
• Issues — bug reports and feature requests.

Development

Source lives under src/erdscope/; the distributable erd.py is generated from it.

python3 -m unittest discover -s tests -v
python3 tools/build_single_file.py --check

See the engineering quickstart before changing providers, merge behavior, the viewer, or generated artifacts.

License

MIT