DBML Editor

ERD Builder Pro includes a built-in DBML (Database Markup Language) editor that lets you define database schemas using concise text syntax — and automatically syncs it with your visual diagram in real-time.

What is DBML?

DBML (Database Markup Language) is an open-source markup language designed to define database structures declaratively. Unlike SQL which focuses on command execution, DBML is designed to be human-readable and writable.

DBML Syntax Example

Table users {
  id integer [pk, increment]
  username varchar [not null]
  email varchar [unique]
  created_at timestamp
}

Table posts {
  id integer [pk, increment]
  user_id integer [ref: > users.id]
  title varchar
  body text
  published_at timestamp
}

Enum status {
  draft
  published
  archived
}

Ref: posts.user_id > users.id

How to Access the DBML Editor

1. Open the ERD Builder page.
2. Click the DBML Editor button on the toolbar (the </> icon) in the top-right corner of the canvas.
3. The editor panel will appear on the right side of the screen.
4. Type or edit DBML syntax — the diagram will update automatically.

[!NOTE] The ERD diagram and DBML editor are bidirectional (two-way sync). Changes on the canvas update the DBML text, and vice versa.

Supported Syntax

Table & Columns

Define a table with a Table block and a list of columns inside:

Table products {
  id integer [pk]
  name varchar [not null]
  price decimal
  description text
  is_active boolean [default: true]
}

Column settings supported inside square brackets []:

Setting	Description	Example
pk	Primary Key	[pk]
not null	Cannot be empty	[not null]
unique	Unique value	[unique]
increment	Auto-increment	[increment]
default	Default value	[default: 'active']
note	Column annotation	[note: 'User display name']

Relationships (Ref)

Define relationships between tables using the Ref block:

Ref: orders.customer_id > customers.id
Ref: order_items.order_id > orders.id
Ref: profiles.user_id - users.id  // one-to-one

Relationship operators:

Operator	Meaning
>	One-to-many (FK → PK)
<	Many-to-one (PK → FK)
-	One-to-one

Enum

Define enumeration types as standalone blocks:

Enum priority {
  low
  medium
  high
  critical
}

Then use the enum name as a column type:

Table tasks {
  id integer [pk]
  priority priority  // uses the 'priority' enum type
}

Inline Enum (AI-Generated)

DBML generated by AI may use inline enum syntax:

Table users {
  role enum('admin', 'editor', 'viewer')
}

The editor will automatically extract these enums into separate Enum blocks during processing.

TableGroup

Group related tables visually:

TableGroup user_management {
  users
  profiles
  settings
}

Note & Indexes

// Note on a table
Table orders {
  id integer [pk]
  total decimal [note: 'Total amount including tax']
}

// Indexes
Table products {
  id integer [pk]
  name varchar
  indexes {
    (name) [index]
    (price) [index]
  }
}

Editor Features

Autocomplete

The DBML editor provides autocomplete suggestions as you type:

Context	Suggestions
Line start	Table, Ref, Enum, TableGroup, Note, Indexes
Inside Table block	Column data types (varchar, integer, timestamp, etc.)
Inside [...]	Column settings (pk, not null, unique, etc.)
After Table.	Column names of that table
In Ref block	Table and column names

Linting & Validation

The editor automatically validates your DBML syntax:

• Invalid data type: Red underline if an unrecognized data type is used.
• Relationship references: Checks whether tables and columns in Ref blocks actually exist.
• Brace balance: Shows an error if a Table block is not properly closed.

Cursor Navigation

Position your cursor on a Table table_name { line — the canvas will automatically select and display that table.

Help Dialog

Click the help button (?) on the editor panel to view a complete DBML syntax reference.

How to Use DBML

Create a Diagram from DBML

1. Open the DBML editor.
2. Type your table, relationship, and enum definitions.
3. The diagram will update automatically (with ~1.5 second delay).
4. Table positions will be preserved if they already exist on the canvas.

Import from SQL

You can also paste CREATE TABLE SQL into the DBML editor — the system will convert it automatically. Use the SQL or DBML panel depending on your source data format.

Copy to Clipboard

Click the copy icon on the DBML panel to copy all DBML text to the clipboard — ready to paste into a .dbml file or share with your team.

AI Integration

The AI Assistant can generate DBML schemas based on your descriptions. When AI responds with a DBML block, click the Database button to apply the schema directly to your diagram.

AI: "Create a database schema for an e-commerce system..."
→ AI generates a DBML block
→ Click the "Database" button on the AI reply
→ ERD diagram is updated

Data Persistence

• DBML text is stored in the database alongside the diagram (dbml_source).
• Every editor change is saved automatically (debounced 800ms).
• When you return to the same diagram, the last DBML text is restored.

Preserved Elements (Roundtrip)

Several DBML elements that are not generated by the editor are preserved during bidirectional sync:

Element	Preserved	Generated
Table + Columns	✅	✅
Ref	✅	✅
Enum (standalone blocks)	✅	✅
TableGroup	✅	❌
Note	✅	❌
Indexes	✅	❌
headerColor	✅	❌
default values	✅	❌

[!NOTE] "Preserved" means these elements remain in the DBML text even though they are not regenerated from the canvas. This allows you to manually add Note, TableGroup, or Indexes and they won't be lost when the canvas is updated.

Limitations

• Data types: Only PostgreSQL data types are supported. Some MySQL-specific types may not be recognized.
• Project block: The DBML Project block is not supported.
• Default & Unique: default and unique values are preserved on import but not regenerated when the canvas is updated.
• Sync delay: Changes from editor to canvas take ~1.5 seconds (debounce) before being applied.
• SQL as intermediary: DBML is processed through SQL as an intermediate format. All conversions follow PostgreSQL dialect.