[Database markup language](https://www.dbml.org/) (DBML) is a [[domain-specific language]] for describing database design.
DBML comes with
1. A free database visualizer [[dbdiagram]] to create an [[entity-relationship diagram]].
2. A free database documentation builder [[dbdocs]]
3. A a [[command line application]] for converting from DBML to [[data definition language]] (DDL) for your database, get it [here](https://www.dbml.org/js-module/#api).
4. An [open-source JS library](https://dbml.dbdiagram.io/js-module/) ([[npm]] package) for you to programmatically convert between DBML and DDL.
Install the [[VS Code]] extension `vscode-dbml` (by Matt Meyers) for syntax highlighting in VS Code.
A community contributed CLI renderer is available to render DBML files to SVG images if you'd prefer to host diagrams yourself (however note these do not benefit from the interactivity available with dbdocs).
Use the [[project organization for databases]] template to store `.dbml` files in your project. Storing up-to-date `.dbml` files in your project helps maintain good documentation by using [[diagrams and documentation as code]].
# syntax
[Read the documentation](https://dbml.dbdiagram.io/docs) for a full overview of the DBML syntax. Below I cover the primary syntax for a basic database.
## define a project
Define a project to describe the type of database and add a note. This is used by
dbdocs.io.
```dbml
Project project_name {
database_type: 'PostgreSQL'
Note: 'Description of the project'
}
```
## create a table
```dbml
Table table_name {
id int [pk]
column column_type [column_settings]
}
```
The `column_type` options will be determined by the database type you are building towards.
Column settings include `[pk, unique, null, not null, default: some_value, incremement, note: 'some note']`.
You can alias long table names
```dbml
Table long_table_name as L {
}
```
## define relationships
Relationships can be defined inline with the `Table` declaration or separately.
```dbml
// inline
Table table_name {
column column_type [ref: > other_table.column]
}
// short form
Ref table_name.column > other_table.column
```
There are 4 types of relationships
- `<`: one-to-many
- `>`: many-to-one
- `-`: one-to-one
- `<>`: many-to-many
For more on defining many-to-many relationships, see [here](https://community.dbdiagram.io/t/tutorial-many-to-many-relationships/412).
## column types
Use column types that match with your intended application.
- [[Google Sheets column types]]
- [[Postgres data types]]