dbml.dbdiagram.io

DBML's official home is dbml.dbdiagram.io, the documentation site for the Database Markup Language used by dbdiagram.io. Use it when you need the syntax reference, a quick example schema, or a pointer to the visual editor; the site itself is a documentation and resource hub, not a hosted database tool.

What the Site Is For

DBML (Database Markup Language) is a text format for describing database structures — tables, columns, indexes, and relationships — in a readable, version-controllable way. The dbml.dbdiagram.io site exists to explain that format and connect it to the tooling around it.

Practically, the site serves three purposes:

• Syntax reference — how to write table definitions, column types, settings, and relationship statements.
• Examples — sample schemas you can read and adapt rather than starting from a blank file.
• Tool entry points — links toward dbdiagram.io, where a DBML file can be rendered as an entity-relationship diagram.

If your question is "what is DBML," the site's introductory material answers it. If your question is "how do I write a table definition," the syntax pages are the place to look.

Finding the Syntax Reference

Start from the site's navigation rather than guessing URLs. Documentation sites of this kind typically organize content into an introduction, a syntax or language section, and a database-specific notes section.

When you land on the syntax pages, expect coverage of the core building blocks:

A minimal table definition follows the pattern of a Table keyword, a name, and a brace-delimited body of columns — for example, a users table with an integer primary key and a variable-length name column. The exact syntax for each setting is what the reference pages document, so treat any example you copy as a starting point and confirm details against the current reference.

Examples and the Playground

Example schemas are the fastest way to learn DBML because they show settings and relationships in context. Look for a samples or examples section on the site, and for links to the dbdiagram.io editor, which functions as a live playground: you paste or type DBML on one side and see the diagram update.

A useful exercise when you find an example:

1. Copy the example into the editor.
2. Change a column type or add a setting such as not null.
3. Confirm the diagram reflects the change.
4. Add a ref between two tables and check that the relationship line appears.

This verifies your understanding of the syntax against actual rendering behavior rather than against the text alone.

Common Sticking Points

• Confusing the documentation site with the editor. dbml.dbdiagram.io explains the language; diagram rendering happens in dbdiagram.io. If you are looking for a place to type DBML and see output, follow the tool links rather than staying on the docs pages.
• Assuming database-specific types are universal. DBML supports notes on how types map to particular databases; check those sections before assuming a type behaves identically across engines.
• Copying examples without checking settings. Examples often omit constraints for brevity. Add primary keys, nullability, and relationships deliberately.
• Expecting export or pricing details on the docs site. The documentation covers the language; account, export, and plan details belong to the dbdiagram.io product pages.

A Reasonable Path

If you are new: read the introduction, then the table and column syntax, then relationships. Build one small schema in the editor and iterate. If you already know the basics: go straight to the settings and relationship reference, and use the examples to confirm edge cases such as composite indexes or many-to-many patterns expressed through a join table.

DBML at dbml.dbdiagram.io is the web-based tool for DBML (Database Markup Language), a plain-text syntax for defining database schemas. You use it to write or paste DBML definitions in the browser and turn them into a working schema model, typically as a step toward a database diagram. It is a focused language/tooling resource tied to dbdiagram.io's diagram workflow, not a general-purpose website.

What the tool is for

DBML is a human-readable way to describe tables, columns, relationships, indexes, and notes. Instead of clicking through a visual editor, you type a compact definition. The dbml.dbdiagram.io tool is the browser-based entry point for that syntax: you provide the DBML text, and the tool interprets it as a schema definition.

This makes it useful when you want to:

• Draft a schema quickly in text form before building a diagram
• Keep a schema definition under version control alongside application code
• Share a precise, readable schema with teammates instead of a screenshot
• Move from a written definition to a visual database diagram in dbdiagram.io

How it fits with dbdiagram.io

The hostname places the tool within the dbdiagram.io family. The practical relationship is a pipeline: DBML is the input language, and database diagrams are a common output. You define the schema in DBML, and the diagram workflow renders that structure visually.

What DBML definitions typically contain

A DBML file is organized around table blocks. Within each block you list columns with their types and constraints, and you express relationships between tables. For example, a minimal definition looks like this:

Table users {
  id integer [primary key]
  email varchar [unique, not null]
  created_at timestamp
}

Table orders {
  id integer [primary key]
  user_id integer
  total decimal
}

Ref: orders.user_id > users.id

The Ref line declares a foreign-key-style relationship. The bracketed settings such as [primary key] and [not null] carry column constraints. This is the kind of input the tool is built to accept.

When to use it, and when not to

Use it when your priority is a precise, text-first schema that can be reviewed, diffed, and reused, and when you intend to produce a diagram from that definition.

Look elsewhere when you need a full database administration console, live query execution, or a GUI-only modeling experience. The tool's scope is schema definition and diagram-oriented modeling, not database operations.

Practical starting point

1. Open dbml.dbdiagram.io in a browser.
2. Write or paste a DBML definition using Table blocks and Ref relationships.
3. Check that the definition is accepted and the structure reads as intended.
4. Carry the definition into the dbdiagram.io diagram workflow to visualize it.

The main thing to confirm on first use is that your table and reference syntax is accepted; once it is, the same definition can serve as both documentation and diagram source.

To define a table in DBML, write a Table block with the table name followed by a pair of curly braces, then list one column per line inside the braces as name type [settings]. Mark a primary key with [pk] on the column line, and express relationships either with inline [ref: > other_table.column] on a column or with a separate Ref: statement. This syntax works in the DBML editor at dbml.dbdiagram.io, where the diagram is generated as you type.

The basic table block

A table definition has three parts: the Table keyword, the table name, and a braced body containing columns.

Table users {
  id integer
  username varchar
  created_at timestamp
}

Rules that matter in practice:

• The table name follows Table directly. Use double quotes if the name contains spaces or reserved words: Table "order items" { ... }.
• Each column line is column_name column_type. The type is free-form text, so varchar, varchar(255), int, and uuid are all accepted; DBML does not validate types against a specific database.
• Settings go in square brackets after the type, separated by commas: [pk], [not null], [unique], [default: value], [note: 'text'].
• Indentation is cosmetic. Braces and line breaks are what delimit the block.

A more complete example:

Table users {
  id integer [pk, increment]
  email varchar(255) [not null, unique]
  display_name varchar [note: 'shown in the UI']
  is_active boolean [default: true]
  created_at timestamp [default: `now()`]
}

Note that increment and `now()` are passed through as written; they are annotations for readers and for export, not something the editor evaluates.

Primary keys, composite keys, and indexes

A single-column primary key is just [pk] on that column. For a composite key, put [pk] on each participating column — DBML treats multiple pk columns in one table as a composite primary key.

Table memberships {
  user_id integer [pk]
  group_id integer [pk]
  role varchar
}

Indexes are declared as table-level settings inside the same brackets, after the column list:

Table posts {
  id integer [pk]
  author_id integer
  slug varchar
  published_at timestamp

  indexes {
    slug [unique]
    (author_id, published_at)
  }
}

The indexes block is optional and sits inside the table braces. A parenthesized list creates a composite index; [unique] or [name: 'idx_name'] can be attached to an entry.

Expressing references

There are two equivalent ways to declare a relationship. Inline is shorter for one-off foreign keys:

Table posts {
  id integer [pk]
  author_id integer [ref: > users.id]
  title varchar
}

The separate form is easier to read when a table has many relationships or when you want to name them:

Table posts {
  id integer [pk]
  author_id integer
  title varchar
}

Ref: posts.author_id > users.id
Ref name: "post_author" {
  posts.author_id > users.id
}

The operator encodes cardinality, read from the left side to the right:

So posts.author_id > users.id reads as "many posts belong to one user." Getting the direction backwards is the most common mistake — it changes the arrowhead in the generated diagram, not just the text.

Checking your definition and finding the docs

The editor at dbml.dbdiagram.io renders the diagram live, so the fastest verification is to paste the definition and confirm that every table appears with the expected columns and that each relationship draws an arrow between the correct tables. If a table is missing, look for an unbalanced brace or a column line placed outside the braces; if a reference is missing, check that both table and column names match exactly, since references are resolved by name and are case-sensitive in practice.

For syntax beyond what is covered here — enums, table groups, notes, table partials, and database-specific type annotations — the site's own documentation and example files are the authoritative reference, and the editor's sample schema is a working definition you can copy and modify rather than write from scratch.

DBML is a concise, text-based schema notation for describing tables and relationships, not a database engine. Choose it when you want a readable, version-controllable schema definition that can be shared for review or turned into a diagram; keep SQL for executable DDL and use a visual designer when you need to manipulate a model graphically. The three approaches serve different stages of the same workflow rather than competing for the same job.

What each approach is actually for

Where DBML fits best

DBML's advantage is that a schema reads almost like a list. A table definition names the table, then lists columns with types and settings, and relationships are declared separately. That makes it fast to scan in a pull request or a design doc, and it keeps the schema in a form that diffs cleanly when a column is added or a relationship changes.

Use DBML when:

• You are drafting a schema and want feedback before committing to migrations.
• You want a single source that can feed a diagram (dbdiagram.io renders DBML into an entity-relationship view).
• Your team reviews schema changes as text in version control.

Where SQL is the better choice

SQL DDL is the only option here that actually creates objects in a database. It carries constraints, indexes, and dialect-specific details that a notation may not express, and it is what your migration tooling runs. If the task is "apply this change to the database," write SQL. DBML can describe the intent, but it does not replace the executable statement.

A practical pattern is to design in DBML, agree on the shape, then write the SQL migration that implements it. The notation stays as documentation; the SQL stays as the source of truth for the deployed schema.

Where a visual designer wins

A graphical designer is better when the model is still being explored or when you need to walk a non-technical stakeholder through relationships. Dragging tables and seeing lines form is faster than editing text for that kind of session. The trade-off is reviewability: graphical models are awkward to diff and comment on line by line, and the file format often ties you to one tool.

DBML sits between these poles. It is text like SQL but visual-friendly like a designer, because the same definition can be rendered as a diagram. Many teams use it as the shared artifact and treat the visual tool as a view onto it.

How to decide

• Need to deploy schema changes? Write SQL. DBML does not execute.
• Need to discuss and review a schema? Use DBML — it is shorter and diffs better than SQL.
• Need to explore relationships visually with others? Use a visual designer, or render your DBML as a diagram.
• Need all three? Draft in DBML, review the rendered diagram, then implement in SQL. This is the common complementary workflow rather than a choice of one over the others.

The key distinction to hold onto: DBML is a schema notation, SQL is an executable language, and a visual designer is an interface. Picking the wrong one for the task — trying to run DBML or review a binary model file in a pull request — is where friction appears.