Docs & Code Guide

A living diagram from schema.prisma: regenerate the data model view on every migration merge

Prisma teams start closer to a living ERD than almost anyone: the entire data model sits in one declarative file, schema.prisma, with models, relations, and enums spelled out. No introspection, no DDL parsing, no exports. The remaining work is turning that file into a view worth embedding, and rebuilding the view at the moment it can go stale, which for Prisma is precisely when a migration merges.

Try it free
8 min readFor product teams whose data model lives in schema.prisma

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

218/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

schema.prisma is already the graph

Each model block is a node; each @relation, with its fields and references, is a typed edge; enums and composite keys are right there in the text. Because the file is the single source Prisma itself compiles, a diagram generated from it cannot disagree with the ORM's view of the world. Datadef's AI import accepts the pasted schema directly as a prompt, and the data model diagram generator owns that first-generation path.

One subtlety the file hides: implicit many-to-many relations. Two models with list fields pointing at each other get a join table in the database, named like _UserToTeam, that appears nowhere in schema.prisma. A good ERD either draws the join table explicitly or marks the edge as many-to-many; silently omitting it confuses everyone who later reads the actual database.

prisma-erd-generator: the in-repo alternative, honestly

There is a community package that solves part of this problem inside the repo, and it deserves a straight description. prisma-erd-generator hooks into prisma generate as a generator block: every generate run emits an ERD, Mermaid-based, SVG by default, with mermaid-cli and its headless browser as dependencies. For a small schema and a committed docs image, it is genuinely convenient, free, and zero new services.

Its limits are the limits of full-auto rendering. It draws every model with generated layout, so a forty-model schema becomes spaghetti with no way to curate zones, hide noise models, or annotate the tricky relations; the output is a static file you must regenerate and commit; and nothing about it helps the diagram live outside the repo. If your whole need is "an ERD image in the docs folder", use it. The living-diagram approach earns its keep when the diagram needs curation, annotations, and a wiki embed that updates itself.

// schema.prisma, the in-repo alternative:
generator erd {
  provider = "prisma-erd-generator"
  output   = "../docs/erd.svg"
}
// runs on: npx prisma generate (requires mermaid-cli)

Migrations are the change signal

Prisma gives schema changes a precise footprint: every prisma migrate dev run lands a new folder under prisma/migrations with a timestamped name and a migration.sql inside. A CI trigger filtered to that path fires exactly when the data model changes and never otherwise, which is the cleanest change signal in this whole guide series.

When you need to know what changed rather than just that something changed, prisma migrate diff compares schemas and databases in any combination, live database against schema file included, and emits the difference as SQL with --script. That output is a ready-made summary for the agent updating the diagram, and for the human reviewing the update.

The loop, and the README embed

On a merge touching prisma/migrations, one CI step hands schema.prisma to an agent connected to Datadef's MCP server (registry io.datadef/mcp): update the ERD, add the new model to its zone, redraw the changed relations, keep annotations. The connection needs an API key, available on paid plans. Datadef does not watch the repository; the trigger is your CI path filter, and the regeneration is that one invoked step.

Prisma projects usually want the ERD in the repo README, and GitHub strips iframes from READMEs, so the image URL form is the right embed: a Markdown image pointing at the diagram's public URL, which re-renders within minutes whenever the diagram changes. The GitHub specifics live in embed diagrams in a GitHub README.

What schema.prisma cannot say

The embed URL exists only for projects shared public, and a data model is often the most sensitive diagram a company has; for a private schema, the prisma-erd-generator committed-file approach may genuinely be the better fit, staleness and all. The diagram also shows the Prisma layer's view: database objects Prisma does not manage, views, triggers, tables owned by another service, are invisible to schema.prisma, and the database-side ERD workflow is the complement when those matter. Raw SQL migration streams without Prisma have their own page in a living diagram from SQL DDL.

Draw the invisible join tables

Implicit many-to-many relations create join tables that schema.prisma never names. Make the ERD show them, or the diagram and the database will disagree in the first incident.

FAQ

How do I generate an ERD from schema.prisma?

The schema file is already the full graph: models are nodes, @relation fields are edges, enums are attached types. Paste it into an AI diagram generator or hand it to an MCP-connected agent to get a curated ERD, or add the prisma-erd-generator package to emit a Mermaid-based SVG on every prisma generate for a committed in-repo image.

Is prisma-erd-generator enough?

For a small schema and an image committed to the docs folder, often yes: it runs on prisma generate, costs nothing, and needs no services beyond mermaid-cli. It draws every model with generated layout though, with no curation, zones, or annotations, and the output is a static file. Large schemas and wiki embeds that update themselves are where a curated living diagram takes over.

How do I keep the Prisma ERD up to date?

Use the migrations folder as the trigger: every schema change lands a timestamped folder under prisma/migrations, so a CI job filtered to that path fires exactly on data model changes. That job has an MCP-connected agent re-read schema.prisma and update the diagram. Nothing watches the repo by itself; the loop is that one invoked step.

Do implicit many-to-many relations show up in the diagram?

Only if you draw them. Prisma creates a join table like _UserToTeam in the database for implicit many-to-many relations, but schema.prisma never names it. An honest ERD either renders the join table explicitly or clearly marks the edge as many-to-many, so the diagram matches what someone finds when they query the database.

Can the ERD live in the GitHub README and stay current?

Yes, via the image URL form: GitHub strips iframes from READMEs, but a Markdown image pointing at a public Datadef embed URL renders normally and re-renders within minutes of any diagram change. The project must be shared public for the URL to exist, which is the trade-off to weigh for a sensitive data model.