How to draw a database diagram with DBML
- 1Start from the blog sample or a blank editor.
- 2Declare tables as Table name { column type [settings] }.
- 3Connect them with Ref lines such as Ref: posts.user_id > users.id.
- 4Drag tables into place; positions are autosaved with your DBML.
- 5Export SQL for your database, DBML, a Mermaid erDiagram, PNG or SVG.
DBML syntax basics
DBML (Database Markup Language) is an open, plain-text language for describing a schema. A table is a name and a block of columns, one per line, with settings in square brackets: Table users { id integer [pk, increment] email varchar(255) [not null, unique] created_at timestamp [default: `now()`] }.
Relationships are written as Ref: posts.user_id > users.id, where > means many-to-one, < means one-to-many, - means one-to-one and <> means many-to-many. You can also put the reference on the column itself: user_id integer [ref: > users.id]. Composite keys use parentheses, as in Ref: a.(x, y) > b.(x, y).
Enums are declared with enum post_status { draft published archived } and used as a column type. Add documentation with Note: 'text' inside a table or note: 'text' in a column's settings, and use // for comments that are not part of the schema.
Why design a schema in DBML
DBML is shorter than SQL and not tied to one database, so it is quick to sketch a model, discuss it in a pull request and keep it in your repository next to the code. Differences such as SERIAL versus AUTO_INCREMENT versus IDENTITY are handled when you export SQL for a specific database.
If you have used dbdiagram.io, DBML will look familiar: it is the open language that tool is built around, and plain DBML usually works in both. This editor is a separate, independent tool. It keeps everything in your browser and has no accounts, share links or team features.
Naming conventions for tables and keys
Pick one style and keep it: lowercase snake_case works in every database without quoting, because PostgreSQL folds unquoted names to lowercase and MySQL table names can be case-sensitive on Linux. Decide once whether table names are plural (users) or singular (user).
Name foreign keys after the table they point at plus _id, such as user_id or order_id, so relationships are obvious even without the diagram. Avoid reserved words like user, order and group as table names; they work only when quoted, which is easy to forget in queries.
Use consistent suffixes for common columns: created_at and updated_at for timestamps, is_ or has_ prefixes for booleans, and the same type for a key and every foreign key that references it, for example bigint on both sides.