Where an ER diagram actually helps

An ER diagram is useful in a narrow, practical sense: it makes the shape of a schema visible at a glance. A directory of CREATE TABLE files contains the same information, but reading it means holding several files in your head at once. The situations below are the ones where the picture saves real time. They are ordinary engineering moments, not special occasions.

Documenting a legacy database you inherited

The dump arrives without a README. A pg_dump or mysqldump export can run to tens of thousands of lines, and the foreign keys are usually appended at the end as ALTER TABLE statements, far from the tables they belong to. Paste the file and the parser rebuilds the edges regardless of where the constraints were declared.

Reading the resulting diagram exposes things the schema hides in plain text. A column named customer_id with no foreign key becomes obvious, because the table has no matching edge. That is either deliberate denormalization or a constraint someone forgot, and it deserves a question either way. The same applies to nullable columns in a join table, or a table that nothing references and nothing queries.

For onboarding, publish the read-only link and put it in the repository README. A new developer can pan and zoom without installing a client or creating an account. Regenerating the diagram after a schema change costs one paste, which is cheap enough that the documentation has a chance of staying current.

Designing a schema before writing migrations

On a greenfield project the first migration sets the tone for everything after it. If you can describe the application in plain English, the describe-your-app feature proposes a normalized schema with primary keys, join tables and column types. Treat that proposal as a first draft. Normalization is a design decision with trade-offs, not a rule to apply blindly, and the normalization guide covers where 3NF helps and where it costs you.

From there the work is visual. Add the tables the draft missed, rename columns, draw relationships with explicit cardinalities, and undo freely when an idea does not survive contact with the rest of the model. Work autosaves, and named restore points mark the milestones worth returning to. Most design mistakes are cheaper to find here than in a migration that has already run in staging.

When the shape is settled, export runnable DDL for PostgreSQL, MySQL, SQLite or SQL Server. One caveat: that export creates a schema from scratch. It is not a migration, and it does not replace one. Use it as the target definition, then write the ordered migration that gets an existing database there, including backfills and a rollback path.

Reviewing a schema change in a pull request

A migration diff of forty ALTER TABLE statements is difficult to review. Each statement is local: add a nullable column, drop a constraint, change a type. The consequences are global, and they live in the relationships between statements.

Import the schema before the change and after it as two diagrams, then compare the pictures. Several questions become immediate: did a one-to-many relation quietly become many-to-many, is the new foreign key optional or required, did the join table gain a column, did a unique constraint disappear. None of this replaces reading the SQL, but it tells you where to read.

Attach the exported SVG or PNG to the pull request, or add the read-only link to its description. Reviewers who are not backend specialists can then follow the discussion. The diagram will not show the data migration, lock duration or deployment order, so those still belong in prose.

Teaching databases and SQL

In a classroom, DDL is abstract. Students read NOT NULL and UNIQUE as vocabulary words, then forget which constraint does what. Change a column in the editor and the effect appears immediately: a key badge, a new edge, a cardinality that flips. The constraint stops being syntax and becomes a property of the model.

Junction tables are the usual stumbling block. Showing two foreign keys plus a composite primary key collapse into a single many-to-many relation gives students a concrete reason the table exists, even though the conceptual model hides it. From there, reading a diagram and drawing one become two sides of the same exercise.

A workable assignment: have students describe a library, a hotel or a shop in English, compare the proposed schemas in class, then normalize one of them by hand. Read-only links can be shared with the whole room, and nobody needs to install anything or sign up. The limit is worth stating to students as well: the diagram describes structure, not the rows or the query results.

Explaining a system to non-engineers

Clients, product managers and support staff do not need CREATE TABLE syntax. They need a map: which things exist, how they connect, and which connections are optional. A diagram answers those questions in a few seconds, where a schema dump answers them only for someone fluent in DDL.

Support conversations improve with a concrete picture. Why can this supplier not be deleted? Because orders reference it, and the edge shows that. Why can one order have several discount codes? Because the relationship is many-to-many, and the join table is where the rules live. Product discussions benefit too: seeing that a subscription belongs to a workspace, not to a user, prevents a surprising number of wrong assumptions.

Keep the diagram for the audience small. Import only the tables under discussion rather than the full production schema, then export an SVG for slides or share the read-only link, which needs no account on the other side and can be revoked when the conversation ends.

Migrating between databases or ORMs

Schemas rarely stay in one format. A database may begin as MySQL and move to PostgreSQL; a backend may move from raw SQL to Prisma; documentation may live in DBML. Import the schema you have and export the form you need. The same internal model drives every export, so tables, keys, nullability and relations carry across rather than being retyped.

For a database migration, import the source dump and export DDL for the target dialect. For documentation, export DBML or SVG. For an ORM, export the first-draft Prisma schema and review it before committing it.

Be precise about what translation can promise. It maps structure and column types; it does not resolve everything. Sequences and auto-increment behavior, enum representations, default expressions, identifier case sensitivity and vendor-specific types all need a check against the target database. Treat the exported file as a reviewed starting point, not as a finished migration.

When a diagram is not the right tool

A diagram describes structure. Runtime behavior is elsewhere. Triggers, stored procedures, scheduled jobs and application-level invariants do not appear as edges. A foreign key says a referenced row must exist; it says nothing about retries, cascades or what happens when two transactions touch the same row.

Data volume is invisible too. Two schemas with identical shapes can behave very differently at ten million rows. Row counts, distributions and growth rates are not part of the model, and neither are the query patterns that decide whether a design holds up.

Performance tuning needs different instruments: query plans, EXPLAIN output, slow query logs, and the index definitions. Indexes are not part of the ER model here, so a diagram can show you where tables join but not whether the join is indexed. Use it to understand the schema, then measure the database.

Start with a schema you already have

The fastest way to judge the tool is to paste a real schema. Import SQL from SQL to ER diagram, borrow a complete schema from the examples library, or start from a template for a common domain. Everything is free and needs no account, and SQL parsing happens in your browser.