[Proposal] Support splitting DBML to multiple files

[huydo862003]

We are in the process of evaluating options to support splitting DBML file to multiple files. We want to make a proposal and would like your input.

Use cases

• Organization: A single DBML file can grow very large, making it difficult to navigate, maintain, and collaborate on. Multi-file DBML enables a clearer separation of domains and ownership boundaries, making it easier to work on large schemas.
• Reusability: Common definitions, such as enums and table partials, can be shared across projects instead of being duplicated.

Proposed design for multi-file DBML

Split your DBML schema across multiple files - keep things organized, import only what you need.

Importing with use

Pick exactly what you need:

use {
  enum user_status
  tablepartial with_timestamps
} from './common/main'

Or grab everything from a file:

use * from './common/main'

Avoiding name conflicts with aliases

use { table my_table as aliased_table } from './common'

Handy when two files define something with the same name.

File paths

Use relative paths without the .dbml extension:

use * from './common'    // refers to ./common.dbml

How it works

• Each .dbml file is isolated by default, nothing leaks in or out unless you explicitly say so.
• Think of each file as its own little namespace.
• use is how you bring things in.

What can be imported?

Type	Supported	Notes
enum	✅
table	✅	Brings along records and refs automatically
tablepartial	✅
schema	✅	Imports all elements under that schema
tablegroup	✅	Imports all tables in the group
ref	❌	Refs are resolved automatically when both tables are in scope
records	❌	Import the table instead — records come with it

Circular imports are fine

DBML is declarative, there's no execution order, so files can freely reference each other without any issues.

// users.dbml
use { table orders } from './orders'
Table users { ... }
Ref: users.id < orders.user_id
 
// orders.dbml
use { table users } from './users'
Table orders { ... }

Imports are not transitive

If a.dbml imports b.dbml, and b.dbml imports c.dbml, c.dbml's items are NOT available in a.dbml:

// c.dbml
Table C {}
 
// b.dbml
use * from './c'
 
// a.dbml
use * from './b'
 
Records C() {}  // ❌ error: C is not in scope

This is intentional - keeps imports explicit and predictable, same behaviour as import in JavaScript.

If you desire this behavior, then you can consider "re-export" as detailed in the following section.

Re-exporting with reuse

reuse = use + re-export.

It lets a file act as a barrel: importing from sub-files and re-exposing them to anyone who imports it.

// a.dbml
reuse { table my_table } from './common'
 
// Now my_table can be imported from a.dbml by other files

The problem it solves: Say you started with one big common.dbml and later split it into multiple files. Without reuse, every consumer would need to update their imports manually. With reuse:

// common/index.dbml
reuse * from './users'
reuse * from './orders'
reuse * from './products'
 
// main.dbml
use * from './common/index'   // nothing changes here

Consumers never need to know how your files are organized internally, just point them at the barrel file.

Vision: large project workflow

For large projects, split by domain and compose everything in a single entry point:

project/
├── ecom.dbml
├── review_system.dbml
├── user_profile.dbml
├── note_enrichment.dbml
├── partial_template.dbml
└── project.dbml

// project.dbml — single entry point, composes everything
use * from './ecom'
use * from './review_system'
use * from './user_profile'
use * from './note_enrichment'
use * from './partial_template'

// note_enrichment.dbml - imports only what it needs from other domains
use { table users } from './user_profile'
use { table products } from './ecom'
 
Table notes {
  id integer [pk]
  user_id integer
  product_id integer
  content text
}
 
Ref: notes.user_id > users.id
Ref: notes.product_id > products.id

dbdocs build ./project.dbml   # builds everything

Each domain file is self-contained and only imports what it needs. In this case, project.dbml is the single entry point: it composes everything without declaring anything itself.

How this design fits the use cases

• Organization: A large project can now be split into multiple files.
• Reusability: Common definition can be placed in a common file.

Tagging @nyimbi, @0xErwin1, @asule90, @lucianokrebss, @lloydhumphreys

[0xErwin1]

I like the overall direction. File isolation plus explicit use makes sense, and it addresses the organization/reuse problem well.

One thing that feels unnecessarily verbose to me is requiring .dbml in the import path. If use only targets DBML modules, then:

use {
  enum user_status
  tablepartial with_timestamps
} from './common'

feels cleaner than:

} from './common.dbml'

I’d suggest allowing extensionless imports by default and resolving them to .dbml automatically. Supporting both forms would probably be the best DX:

from './common'
from './common.dbml'

with one of them documented as the preferred style.

Also, I think aliasing may become important quickly for larger projects, especially when importing enums/tables with overlapping names.

[huydo862003]

Hi @0xErwin1, thanks for your input.

Regarding aliasing, we will definitely support this when this feature gains more traction. We also likely opt for a rolling release for now. Of course, aliasing is probably a should-have enhancement.

Regarding the extensions, I think it's a fair suggestion though. 🤔 We were just not sure if we would allow importing other types of files in the future (like json). Maybe .dbml can be a default.

[cnagel-wti]

I like the proposed use / reuse model, but for some large projects I do not actually want to maintain a barrel file. I would like an optional way to import a directory as a unit and let the tool scan its .dbml files, or even allow a command such as dbdocs ./app/db/schema to treat that folder as the schema entry point.

I realize this is less explicit than the current proposal, so I would see it as optional behavior rather than the default. But for domain-organized projects it would reduce boilerplate and make refactoring easier when the folder itself is the intended boundary.

If this were considered, a few details would need to be defined clearly: whether scanning is recursive, how files are ordered, how duplicate names are handled, and whether a folder import behaves more like use or reuse.

[huydo862003]

Thanks for your suggestions. We will consider it once the first version of DBML module system gains traction!

[huydo862003]

Hi 0xErwin1, cnagel-wti, DBML now supports multiple files in version 8.0.0. For now, only dbml-cli and the dbml-playground supports it.

You can check this doc page for more details: https://dbml.dbdiagram.io/syntax/module-system

[Daanpennings]

Hi @huydo862003, any idea when it will be implemented in the web environment? We would really like to use this functionality, but we're only working in our team workspace on dbdiagram.io.

[huydo862003]

@Daanpennings Hi, the dbx team plans to implement this from next week going forward. I think it could take 2-3 months for it to ship to the web though 🥲