Skip to main content

DBML - Database Markup Language

Open source

GitHub Repo stars


DBML (Database Markup Language) is an open-source DSL language designed to define and document database schemas and structures. It is designed to be simple, consistent and highly-readable.

It also comes with command-line tool and open-source module to help you convert between DBML and SQL.

Table users {
id integer
username varchar
role varchar
created_at timestamp

Table posts {
id integer [primary key]
title varchar
body text [note: 'Content of the post']
user_id integer
status post_status
created_at timestamp

Enum post_status {
private [note: 'visible via URL only']

Ref: posts.user_id > // many-to-one

See the above dbml doc visualized on dbdiagram

For full DBML syntax documentation, refer to the Syntax section.

Note: DBML is not to be confused with Microsoft's DBML file extension (XML format).


DBML is born to solve the frustrations of developers working on large, complex software projects:

  • Difficulty building up a mental "big picture" of an entire project's database structure
  • Trouble understanding tables and what their fields mean, and which feature are they related to;
  • The existing ER diagram and/or SQL DDL code is poorly written and hard to read (and usually outdated).

Our recommended best practices is to have a database.dbml file in your root repository (similar to other config and/or boilerplate files, eg. packages.json or

|_ ...
|_ database.dbml

Is this similar to SQL DDL?

Not quite. Despite its name (data "definition" language), DDL is designed mainly to help physically create, modify or remove tables, not to define them. In other words, DDL is imperative, while DBML is declarative. This makes DBML so much easier to write, read and maintain.

DDL is also database specific (Oracle, PostgreSQL, etc), while DBML is database-agnostic and designed for the high-level database architecting instead of low-level database creation.

What can I do now?

DBML comes with:

  1. A free database visualiser at
  2. A free database documentation builder at
  3. A command-line tool to help to convert SQL to DBML files and vice versa.
  4. An open-source JS library (NPM package) for you to programmatically convert between DBML and SQL DDL.

dbdiagram is a free tool to help you visualize database diagrams from DBML code.


dbdocs is a free tool to help you build database documents from DBML code.

Command-line Tool (CLI)

A simple command-line tool to help you convert between SQL (DDL) and DBML. Refer to CLI docs for more info.


DBML History

DBML was born out from, a simple database diagram visualizer. At the time (Aug 2018) we were looking for a simple tool to design database structure but couldn't come up with one we liked. So we decided to build one.

After 1 year and over 100k diagrams created by 60k internet users later, we realized the syntax we designed for users to draw diagram is very received and one of the key values of the tool. That's how DBML is born. Our aim is to make DBML a good and simple way for developers to design and document database structures.

DBML Statistics

  • 110k DBML docs created via (as of July 2019)
  • 59.5k users using DBML (as of July 2019)

Who's behind DBML?

DBML is created and maintained by Holistics, an analytics platform company.


Community Contributions