ERD as code: database diagrams you write instead of draw

ERD as code means you do not draw an entity relationship diagram. You write the schema as text, tables, columns, and relationships, and a tool draws the diagram from it. Change the text and the picture changes. The text is the source; the diagram is a view of it.

It is the same idea as infrastructure as code, applied to the one diagram every backend team has and almost no team keeps current.

What it looks like

Here is a complete schema in DBML, the most widely used language for this:

shop.dbml
Enum order_status {
  pending
  paid
  shipped
}

Table customers {
  id integer [pk, increment]
  email varchar(255) [not null, unique]
  created_at timestamp [default: `now()`]
}

Table orders {
  id integer [pk, increment]
  customer_id integer [not null, ref: > customers.id]
  status order_status [not null, default: 'pending']
  placed_at timestamp
}

That is two tables, an enum, and a one-to-many relationship. In a live editor the diagram redraws as you type: add a column and it appears in the table’s box; add a ref and a line is drawn to the table it points at. Nothing is dragged into place to make the picture true. Paste it into the DBML editor to see it drawn.

Why teams move from drawing to writing

The diagram cannot drift from the schema

A drawn diagram is a second copy of the schema, maintained by hand, by whoever remembers. When the diagram is generated from the text, there is one copy. It can be out of date with the database, but it can never be out of date with itself.

Changes become reviewable

Nobody can review “I moved some boxes and added a table”. Anyone can review this:

orders, proposed
Table orders {
    id integer [pk, increment]
    customer_id integer [not null, ref: > customers.id]
    status order_status [not null, default: 'pending']
    placed_at timestamp
+   cancelled_at timestamp
+   cancel_reason varchar(200)
  }

Two added lines, visible at a glance, with the unchanged columns around them for context. That is what makes a real schema review possible.

Text goes where code goes

A text schema can live in the repository, be diffed between releases, be searched, be generated by a script, and be read by an AI agent. A canvas file can do none of those.

It is faster

Typing user_id integer [ref: > users.id] takes a few seconds. Doing the same through a form, a type dropdown, and a line dragged between two boxes takes longer every time, and a schema is a few hundred of those.

It converts

Text in a defined language can be turned into other text. The same DBML becomes SQL for PostgreSQL, MySQL, or SQL Server, or a Prisma schema, and SQL you already have can be read back with a SQL to DBML converter.

The formats

  • SQL DDL. The database’s own language, and the only one it runs. It is precise and verbose, tied to one dialect, and mixes the design with storage details that make it hard to read as a design.
  • Mermaid erDiagram. Renders natively in GitHub and many docs tools, which makes it a good fit for a small diagram inside a README. It describes a picture more than a schema: there is little room for defaults, indexes, or constraints.
  • DBML. Designed for exactly this job. Readable like Mermaid, but it carries the things a schema needs: types, keys, defaults, indexes, enums, notes, and referential actions. It converts to and from SQL. The syntax fits on one page, and DBML vs SQL covers how the two relate.
  • ORM schema files. A schema.prisma or a Rails schema.rb is already a schema as code. It describes the database as one application sees it, and can be read into a diagram when that is the source you have.

Where it falls short

  • Layout. Text says what the tables are, not where they sit, and automatic layout of a large schema is never quite how a person would arrange it. The practical answer is to keep the two separate: the schema in text, the positions saved by the tool, so tidying the picture never edits the design.
  • People who do not write code. A product manager will not edit DBML. They do not need to: they need to read the diagram and comment on it.
  • One big file. A schema in a single text file gets long, and two people cannot comfortably work in it at once. Look for a tool that lets you split it across files with references resolving between them.

As a team

ERD as code started as a way for one person to sketch quickly. It pays off most with several: the schema is split by area, each person edits their own file, everyone watches the same diagram update, and changes arrive as proposals that read like the diff above. DB Planner is built around that: DBML documents on a live shared board, with comments, proposals, and version history. The walkthrough is in building an ER diagram with your team, and the alternatives are compared in collaborative database design tools.