How to build an ER diagram with your team in real time
Published
Most ER diagrams are made by one person and shown to everyone else as a screenshot. The screenshot is out of date by the next standup, the comments on it are in a chat thread nobody can find, and two people who both “just fixed the diagram” now have two diagrams.
A collaborative ER diagram is one diagram that the whole team opens, that changes in front of everyone when anyone changes it, and that carries its own discussion. This is how to set one up and how to work in it without stepping on each other. The steps use DB Planner; the principles hold in any of the collaborative database design tools.
1. Put the schema on a shared board
Start from what you have. If the database exists, export its structure and import the SQL; PostgreSQL, MySQL, and SQL Server dumps are read into DBML and laid out as a diagram. If the schema lives in an ORM, import the Prisma, Rails, Django, TypeORM, or EF Core file instead. If nothing exists yet, write the first few tables in the DBML editor and watch them appear.
The diagram is drawn from the schema text, so there is never a second step where someone redraws boxes to match. That one property is what makes a shared diagram stay shared.
2. Bring the team in, with the right roles
Create an organization, invite people by email, and give each of them access to the project as an editor or a viewer. Be generous with viewer. The people who build against a schema outnumber the people who design it, and a viewer can still comment and propose changes; they just cannot edit the documents directly.
Organizations are part of Pro, and each teammate is a $5 seat, so three people pay $15 a month. See pricing.
3. Know what is live
Once two people have the project open, each sees, as it happens:
- Who is here. Avatars in the bar for everyone on the board.
- Cursors. Each person’s pointer, in their colour.
- Tables being moved. A table someone drags moves on your screen while they drag it, not when they let go.
- Drawing. Marker strokes, arrows, shapes, and selection boxes appear as they are made, so you can circle a table while you talk about it.
- Sticky notes and pasted images, for decisions and reference material beside the tables.
- Carets in the editor. Where other people are in a document, so you can see that someone is already in the file you were about to change.
The layout is shared too. Each move is saved per table, so if you rearrange the billing tables while a colleague rearranges the auth tables, both arrangements are kept.
4. Split the schema into files, one area each
Here is the part worth knowing before your first working session. The board merges changes table by table, but the text of a single document does not merge keystroke by keystroke: if two people type in the same document at the same moment, the last save wins. The carets show you when that is about to happen, and the fix is structural, not careful timing.
Split the schema into documents by area, accounts.dbml, billing.dbml, catalog.dbml, and let each person work in their own.
References resolve across every document in the project, with nothing to import:
Table invoices {
id integer [pk]
account_id integer [not null, ref: > accounts.id]
total_cents integer [not null]
issued_at timestamp
}accounts is declared in another file, and the line between the two tables is
drawn all the same. Two people can now change billing and accounts at once without either
being able to overwrite the other. It also happens to be how large schemas stay readable.
5. Discuss on the diagram, not about it
Select a table and start a comment thread on it. The table shows a badge with its open threads, and the Review tab lists every thread in the project. A question like “why is this nullable?” now lives on the column’s table until someone resolves it, instead of scrolling away in chat.
6. Propose changes that someone else approves
For anything beyond a small fix, do not edit the document. Open a proposal: your version of the affected documents, shown as changes against the current ones. A teammate reviews it and merges it. Two rules keep this honest:
- Nobody approves their own proposal.
- If a document changed after the proposal was written, the merge is refused instead of overwriting the newer work, and you update the proposal first.
This is the same shape as a pull request, and where the project is linked to a GitHub repository a proposal can be opened as one. For what the reviewer should look for, use the schema review checklist.
7. Keep the history
Every document keeps its versions. When a design goes wrong, you can see what it looked like before, what changed between two versions, and the migration that the difference implies. Shared editing without history is how a team loses an afternoon to “who removed that column?”.
8. Let the people outside the team look
Product managers, analysts, and the contractor who needs to see three tables do not need a seat. Send them a read-only link. The options, from a private link to published documentation, are in how to share an ER diagram.
Working sessions that go well
- One person types per file. Everyone else points, draws, and comments.
- Collapse what you are not discussing. A board of sixty tables is a map; a meeting needs six of them.
- Write the decision down where it was made. A sticky note beside the table, or a note on the column, in the schema text itself.
- End with proposals, not edits. What the meeting agreed becomes a change someone reviews with a clear head tomorrow.
An AI agent can join the same board over MCP and appears in the presence list like anyone else; it can read the schema, comment, and propose, and a person merges. That workflow is in letting an AI agent design your database.