If you have ever tried to explain a database to someone who didn't build it, you know the pain. You open a file full of CREATE TABLE statements and watch their eyes glaze over. Or you dig up an entity-relationship diagram someone drew eighteen months ago, and it turns out half of it no longer matches reality. DBML is the thing that finally made this problem feel solvable to me, and I think it deserves a lot more attention than it gets.
So what is it? DBML stands for Database Markup Language. It's a small, plain-text language for describing a database: your tables, their columns, the indexes, and how everything relates to everything else. You don't run it against a database. You write it, and other tools read it and turn it into diagrams, documentation or actual SQL. Here's roughly what it looks like:
Table users {
id integer [primary key]
email varchar [unique, not null]
}
Table posts {
id integer [primary key]
title varchar
author_id integer [ref: > users.id]
}
Read that and you've basically understood the whole idea. Two tables, a few columns, and that little ref: > users.id saying many posts belong to one user. There's no ceremony and no wall of syntax to wade through.
The background is pretty interesting, because DBML didn't come out of a standards committee. It came out of Holistics, a company that makes business intelligence software and spends its days working with other people's data models. They built dbdiagram.io, a web tool where you type on the left and a diagram redraws itself on the right, and DBML was the language powering that. It caught on among developers who just wanted to sketch a schema quickly, and the team then open-sourced the language and its parser so it wasn't tied to a single product. Since then a little ecosystem has grown around it: a command-line tool that converts between DBML and SQL in both directions, a JavaScript library for parsing it, and dbdocs.io for publishing your schema as a browsable documentation site.
Now, why do I think it's great? Mostly because it's readable by everyone. A backend engineer, a data analyst and a product manager can all look at the same DBML file and follow it, which means modeling mistakes get caught in conversation instead of in production. The relationship symbols are a big part of that. One character tells you whether something is one-to-many, many-to-one or many-to-many, and once you've seen them a couple of times you stop thinking about them.
I also love that it's just text. A text file lives happily in Git, so a schema change shows up in a pull request as a few readable lines, and someone can say "should this really be nullable?" before a single migration gets written. Compare that with a diagram exported as an image, where nobody can tell what changed between versions. Notes are built in too, so you can describe why a column exists right next to the column itself, which is the one kind of documentation that actually has a chance of staying up to date.
Then there's the fact that it doesn't care which database you use. You describe the model once and export it for PostgreSQL, MySQL or whatever else you're working with. And because the CLI can go the other way, you can point it at an existing database and get DBML out the other end, which is a surprisingly painless way to finally document that old project nobody has touched in years.
It's worth being honest about what it isn't. DBML is not a replacement for SQL, and it's not a migration tool. It describes the shape of your data, not how to get from the old shape to the new one, and it doesn't cover things like views, triggers or stored procedures. The SQL it generates is a good first draft, but you'll still want to look it over before it goes anywhere near production. Honestly, I think that's fine. It does one job, the job of making a schema easy to see, write and share, and it does it really well.
If you're curious, the best way to get a feel for it is to spend five minutes on dbdiagram.io. Paste in a schema, tweak a relationship, watch the diagram move. That's usually all it takes to see why I like it so much.
Top comments (0)