Recipes

erdscope recipes

A practical guide organized by what you want to do, not by feature. Every recipe comes with copy-paste commands and follow-up ideas.

Try the live demo — no install User manual
$ pip install erdscope && erdscope demo
RECIPE 1 An ER diagram from a live database in 5 minutes You inherited an undocumented database. See the big picture first. RECIPE 2 An ER diagram from code, no database needed Model diagrams straight from Rails / Django / Prisma / SQLAlchemy / Laravel code. RECIPE 3 Feed your schema to an AI Let an AI implement and review with real schema context, token-efficiently. RECIPE 4 Wire it into CI/CD Auto-refresh schema docs, and stop unexpected changes with a drift gate.

More recipes are planned: database × code reconciliation, Excel table-definition workbooks, dbdiagram.io round-trips, and more.

Recipe 1 — An ER diagram from a live database in 5 minutes #

Scene: you inherited a system with no documentation. Dozens of tables, and no idea which connects to which. You want the big picture first.

Hand erdscope a connection URL and it reads tables, columns, and foreign keys, then generates one self-contained interactive HTML file. No server, no account — just open the file.

# MySQL (driver: pip install pymysql — falls back to the mysql CLI if absent)
erdscope "mysql://readonly_user:PASS@127.0.0.1:3306/myapp_production" -o schema.html

# PostgreSQL (driver: pip install psycopg)
erdscope "postgresql://readonly_user:PASS@localhost/myapp" -o schema.html

# SQLite needs no driver (standard library)
erdscope sqlite:///path/to/app.db -o schema.html
Connect safely erdscope only reads schema information and never writes, but when pointing at a production database, create a read-only user with SELECT privileges only: GRANT SELECT ON myapp_production.* TO 'readonly_user'@'%';
The interactive ER diagram erdscope generates

The generated viewer (click for the live demo). Click a table for column details; double-click to focus on its neighborhood.

What to look at

Recipe 2 — An ER diagram from code, no database needed #

Scene: you have no database credentials. Or you are reviewing a PR and want to see what its model changes do to the relationships — as a diagram.

erdscope statically parses application code (it never executes it). Point it at a Rails / Django / Prisma / SQLAlchemy / Laravel project and it auto-detects the framework, then reads models and associations.

# Just pass the project path (Rails / Django / Prisma / SQLAlchemy / Laravel auto-detected)
erdscope --models path/to/your-app -o schema.html

A code-only diagram is the logical model — the associations your application declares (belongs_to, ForeignKey, Prisma's @relation, Eloquent's hasMany) become the edges. Useful for spotting missing migrations, or associations that exist in code with no FK in the database.

What to look at

Recipe 3 — Feed your schema to an AI #

Scene: you want ChatGPT / Claude to "implement this with the actual database in mind" — but pasting a SQL dump wastes tokens, and ER-diagram images get misread.

--emit-digest condenses the whole schema into token-efficient Markdown: columns, types, PKs/FKs, and associations — plus the design notes from your config file, the intent no machine could ever infer.

# Condense the schema into a Markdown digest (use - for stdout)
erdscope "mysql://readonly_user:PASS@localhost/myapp" --emit-digest schema.md

The output looks like this (from the bundled sample database):

# demo_shop — schema digest

## Tables (13)

### addresses
- id: integer, pk
- user_id: integer, fk→users
- kind: string
- line1: string
- city: string
- country: string
Rel: belongs_to users as user fk=user_id

### categories
- id: integer, pk
- parent_id: integer, fk→categories
- name: string
Rel: belongs_to categories as parent fk=parent_id
…

Ways to use it

Hand over intent, too Write notes in the config file — "soft deletes use deleted_at", "this column is scheduled for removal" — and they are included in the digest verbatim. The AI answers from declared intent instead of guessing.

Recipe 4 — Wire it into CI/CD: auto-refreshed docs and a drift gate #

Scene: ER diagrams and table definitions start rotting the moment they are written, and manual updates always get forgotten. Let a machine keep the docs fresh — and let CI stop schema changes nobody signed off on.

Auto-refresh your schema docs

erdscope is built for CI — the output is one self-contained file, so you can drop it straight onto GitHub Pages or an internal portal. The --emit-digest Markdown works as a build-time component too: generate it during the build and embed it as the "data model" chapter of your product manual.

# Generate the HTML and the Markdown digest as build artifacts
erdscope "$DB_URL" -o site/schema.html --no-open --emit-digest site/schema.md

The drift gate

Commit a baseline snapshot to the repository and compare the live database against it in CI. Exit codes: 0 = identical / 1 = differences / 2 = error — a drift fails the job on its own.

# Create the baseline and commit it (update it when a schema change is intended)
erdscope "$DB_URL" --emit-json schema.lock.json --no-open

# In CI: exit 1 when the database strays from the baseline (differences are human-readable)
erdscope "$DB_URL" --diff schema.lock.json

A minimal GitHub Actions template:

name: schema-docs
on:
  push: { branches: [main] }
  schedule:
    - cron: '0 6 * * 1'   # weekly freshness check
jobs:
  schema:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install erdscope pymysql
      - name: Generate schema docs (HTML + digest)
        run: erdscope "$DB_URL" -o site/schema.html --no-open --emit-digest site/schema.md
        env:
          DB_URL: ${{ secrets.READONLY_DB_URL }}
      - name: Schema drift gate
        run: erdscope "$DB_URL" --diff schema.lock.json
        env:
          DB_URL: ${{ secrets.READONLY_DB_URL }}
      # add a step here publishing site/ to Pages / as an artifact
Keep credentials in secrets The connection URL CI uses should be a read-only user (same as Recipe 1). Always store it as a secret and keep it out of logs.

Details that matter

If you get stuck #

Everything else: the manual's troubleshooting / FAQ. Still stuck? Tell us on GitHub Issues.