Tutorial

Keep an ER diagram of your database, updated on every push

mcdview.dev · 6 min read

Paste a SQL schema, get an interactive entity-relationship diagram on a stable link. Wire it into CI and the diagram regenerates itself every time the schema changes: no diagram to draw, ever again.

ER diagram of the Chinook database — The Chinook schema as one explorable page. Links anchor to the edge of each table, so relationships read cleanly.

The problem with hand-drawn diagrams

A database diagram is out of date the moment someone adds a column. You draw it once for the onboarding doc, and three migrations later it lies. Keeping it honest by hand is a chore nobody signs up for.

mcdview takes the opposite route: the schema file is the source of truth. Point the tool at your schema.sql and it generates the diagram: a single self-contained HTML page, no runtime, no database connection.

What the diagram does

It is not a static picture. Every table and relationship is interactive:

Isolating a table in mcdview — Click a table and the rest fades, so you can focus on it and its relations.

One table isolated — Click a table to isolate it and its relations.

Hub tables highlighted — Spot the hub tables everything depends on.

Dependency cycles — Surface dependency cycles at a glance.

You can export the same model as an SVG, a Mermaid erDiagram, or a Markdown data dictionary, useful when you want the diagram inside a repo or a wiki.

The good part

Put it in CI: the diagram updates itself

Here is the idea. Your schema lives in the repo. On every push that touches it, CI sends the file to mcdview.dev, which regenerates the diagram behind the same stable link. Bookmark that link once; it is always current.

GitHub Actions

Add the published action. On a push to schema.sql, it updates your diagram:

name: er-diagram
on:
  push:
    branches: [main]
    paths: [db/schema.sql]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: Gheop/mcdview-action@v1
        with:
          file: db/schema.sql
          key: ${{ secrets.MCDVIEW_KEY }}   # updates the same link
          fail-on: ok                     # fail the job if the model does not parse

On Rails? Point paths and file at db/schema.rb (or a PostgreSQL db/structure.sql) instead: mcdview reads them natively, same flow, no conversion step. That file's own git history then becomes your schema's time-lapse.

GitLab CI

Same thing as a CI/CD Catalog component:

include:
  - component: gitlab.com/Gheop/mcdview/mcdview@~latest
    inputs:
      file: db/schema.sql
      key: $MCDVIEW_KEY
      fail-on: ok

zero-key Do not want to manage a secret? Use oidc: true instead of a key. The pipeline proves its own identity to mcdview.dev with a signed token, and the diagram is bound to that project: nothing to store.

include:
  - component: gitlab.com/Gheop/mcdview/mcdview@~latest
    inputs:
      file: db/schema.sql
      oidc: true

Get a badge for your README

The job returns a clickable badge. Drop it in your README and it links straight to the live diagram:

[![mcdview](https://mcdview.dev/badge/<token>.svg)](https://mcdview.dev/v/<token>)

Here is a live one, click it: (it tracks the Chinook demo).

The same run can also fetch the Mermaid source, an SVG, a PNG, a QR code and a plain-text fact sheet into your repo. Pick what you need with fetch: mermaid,svg,badge,facts.

Bonus: every push is a version

Because CI pushes on every change, your diagram builds a full history for free. Compare any two versions to see what a migration did, or replay the whole thing as a time-lapse. More in reading your schema's history.

Diff between two versions — Diff between two schema versions: added tables in green.

What makes it different

Three things you rarely get in one tool:

One file, no account. Paste a schema, get a link. The page is a single static HTML file: nothing runs when you open it, no database is contacted, nothing to sign up for.
It lives in CI. A GitHub Action or GitLab component regenerates the diagram on every push, behind the same stable link, with a README badge. Zero-key with OIDC.
It remembers. Every push is a version: scrub the time-lapse, diff any two states, see what a migration changed.

On top of that: isolate a table, spot the hub tables and cycles, switch light or dark, and export to SVG, Mermaid or a Markdown data dictionary.

Try it in 30 seconds

No sign-up. Paste a schema, get a link. Then wire the CI step above and forget about it.

Open mcdview.dev →

Supports PostgreSQL, MySQL, SQLite dumps, a PostgreSQL structure.sql, a Rails schema.rb, pgModeler .dbm, DBML and Prisma, all read natively. The generated page is static HTML, safe to host, nothing runs on view.