DBML

Updated
View as text
Open in Confluence
Open in ChatGPT Open in Claude

DBML reads like a simplified DDL: tables, columns, types, defaults, indexes and references. Because it is close to real schema syntax, it is easy to keep honest.

It is the right choice when the diagram should be the schema documentation rather than an impression of it.

#What it is good at

  • Database documentation with types and constraints.

  • Reviewing a schema change before the migration is written.

  • Handing a schema to a team without giving them database access.

#What it draws

Diagram

Syntax starts with

Table

Table users { id uuid [pk] }

Reference

user_id uuid [ref: > users.id]

Enum

Enum status { active inactive }

Index

Indexes { (user_id, created_at) }

Note

Note: 'One row per person'

#A worked example

Tables, an enum, a reference and an index:

DBML

The source, which you can paste into a new diagram and edit:

Enum order_status {
  pending
  paid
  shipped
  cancelled
}

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

Table orders {
  id uuid [pk]
  customer_id uuid [ref: > customers.id]
  status order_status [not null, default: 'pending']
  total numeric(10,2)
  placed_at timestamp

  Indexes {
    (customer_id, placed_at)
  }

  Note: 'One row per placed order'
}

#A few things that catch people out

  • Reference direction matters: > is many-to-one, < is one-to-many, - is one-to-one.

  • Notes on tables and columns travel with the diagram, which beats a separate wiki paragraph.

  • DBML documents a schema; it does not migrate one. Keep it beside the migrations.

Learn one properly. Borrow the rest when you need them.