Skip to main content

Modules (multi-file)

Entry point of a multi-file project: use * from a barrel that re-exports with reuse; selective use { ... } with element kinds and as aliases; importing a whole schema and a table group; Metadata blocks adding properties to imported elements.

Covers: Module system: use * from, selective use { table … tablepartial … }, as aliases to avoid name clashes, importing a whole schema, a tablegroup and a sticky note, a barrel file that re-exports with reuse, .dbml extension optional in specifiers, nested folder, front matter, Metadata blocks on imported elements, a DiagramView over imported tables

12-modules/main.dbml
12-modules/main.dbmlauth_coreauth_coreauth_readmeauth.* is managed by theidentity service; read-only foreveryone else.auth.users.id < auth.sessions.user_idpublic.billing_users.id < public.invoices.billing_user_idorders_user: public.orders.user_id > public.users.id delete: restrictpublic.users.id - public.user_links.user_idpublic.billing_users.id - public.user_links.billing_user_idauth.users.id - public.user_links.auth_user_idpublic.orders.id < public.order_invoices.order_idpublic.invoices.id < public.order_invoices.invoice_iduser_linksuser_linksuser_id integer · primary key · foreign keyuser_idintegerbilling_user_id integer · foreign key · uniquebilling_user_idUintegerauth_user_id integer · foreign key · uniqueauth_user_idUintegerorder_invoicesorder_invoicesorder_id integer · foreign keyorder_idintegerinvoice_id integer · foreign keyinvoice_idintegerbilling_usersbilling_usersid integer · primary keyidintegerstripe_customer_id varchar(64) · uniquestripe_customer_idUvarchar(64)balance decimal(12,2) · not null · default: 0balanceNNdecimal(12,2)invoicesinvoicesid integer · primary key · incrementidintegerbilling_user_id integer · foreign key · not nullbilling_user_idNNintegeramount decimal(12,2) · not nullamountNNdecimal(12,2)usersusersid integer · primary key · incrementidintegeremail varchar(255) · unique · not nullemailUNNvarchar(255)created_at timestamp · not null · default: now()created_atNNtimestampupdated_at timestampupdated_attimestampordersordersid integer · primary key · incrementidintegeruser_id integer · foreign key · not nulluser_idNNintegertotal decimal(10,2) · not nulltotalNNdecimal(10,2)placed_at timestamp · not null · default: now()placed_atNNtimestampauth.usersauth.usersid integer · primary keyidintegeremail varcharemailvarcharpassword_hash varchar · not nullpassword_hashNNvarcharauth.rolesauth.rolesid integer · primary keyidintegername varchar · unique · not nullnameUNNvarcharauth.sessionsauth.sessionsid integer · primary keyidintegeruser_id integer · foreign key · not nulluser_idNNintegerexpires_at timestamp · not nullexpires_atNNtimestamp

View: customer_360​

A DiagramView shows a subset of the schema. Pass view="customer_360" (or pick it in the toolbar's view menu) to start there:

customer_360
customer_360auth_coreauth_coreorders_user: public.orders.user_id > public.users.id delete: restrictpublic.users.id - public.user_links.user_idpublic.billing_users.id - public.user_links.billing_user_idauth.users.id - public.user_links.auth_user_iduser_linksuser_linksuser_id integer · primary key · foreign keyuser_idintegerbilling_user_id integer · foreign key · uniquebilling_user_idUintegerauth_user_id integer · foreign key · uniqueauth_user_idUintegerbilling_usersbilling_usersid integer · primary keyidintegerstripe_customer_id varchar(64) · uniquestripe_customer_idUvarchar(64)balance decimal(12,2) · not null · default: 0balanceNNdecimal(12,2)usersusersid integer · primary key · incrementidintegeremail varchar(255) · unique · not nullemailUNNvarchar(255)created_at timestamp · not null · default: now()created_atNNtimestampupdated_at timestampupdated_attimestampordersordersid integer · primary key · incrementidintegeruser_id integer · foreign key · not nulluser_idNNintegertotal decimal(10,2) · not nulltotalNNdecimal(10,2)placed_at timestamp · not null · default: now()placed_atNNtimestampauth.usersauth.usersid integer · primary keyidintegeremail varcharemailvarcharpassword_hash varchar · not nullpassword_hashNNvarcharauth.rolesauth.rolesid integer · primary keyidintegername varchar · unique · not nullnameUNNvarchar

Source​

6 files in examples/12-modules/
examples/12-modules/auth.dbml
// The auth schema, imported selectively and as a whole schema by main.dbml.

Table auth.users {
id integer [pk]
email varchar
password_hash varchar [not null]
}

Table auth.roles {
id integer [pk]
name varchar [not null, unique]
}

Table auth.sessions {
id integer [pk]
user_id integer [not null, ref: > auth.users.id]
expires_at timestamp [not null]
}

TableGroup auth_core [color: #8e44ad] {
auth.users
auth.roles
}

Note auth_readme {
'auth.* is managed by the identity service; read-only for everyone else.'
}
examples/12-modules/billing.dbml
// Defines its own `users` table, which would clash with common/users.dbml;
// main.dbml imports it under an alias.

Table users {
id integer [pk]
stripe_customer_id varchar(64) [unique]
balance "decimal(12,2)" [not null, default: 0]
}

Table invoices {
id integer [pk, increment]
billing_user_id integer [not null, ref: > users.id]
amount "decimal(12,2)" [not null]
}
examples/12-modules/common/index.dbml
// Barrel file: `reuse` re-exports so importers of common/index see these elements
// without knowing the folder layout. A plain `use` would keep them private here.
reuse * from './users'
reuse * from './orders'
examples/12-modules/common/orders.dbml
// Orders depend on users: a sibling import inside the common/ folder.
// @dbml/parse 12.1.0 requires a table's partials to be imported alongside it.
use {
table users
tablepartial timestamps
} from './users'

Table orders {
id integer [pk, increment]
user_id integer [not null]
total "decimal(10,2)" [not null]
placed_at timestamp [not null, default: `now()`]
}

Ref orders_user: orders.user_id > users.id [delete: restrict]
examples/12-modules/common/users.dbml
// Shared user tables. Re-exported by common/index.dbml.

TablePartial timestamps {
created_at timestamp [not null, default: `now()`]
updated_at timestamp
}

Table users [owner: 'identity-team'] {
id integer [pk, increment]
email varchar(255) [not null, unique]
~timestamps
}

enum user_role {
member
admin
owner
}
examples/12-modules/main.dbml
---
title: Modular shop
owner: platform-team
---
// Entry point of a multi-file project.
// - `use *` from a barrel that re-exports with `reuse`
// - selective `use { ... }` with element kinds and `as` aliases
// - importing a whole schema and a table group
// - Metadata blocks adding properties to imported elements

use * from './common/index'

use {
table users as billing_users
table invoices
} from './billing'

use {
schema auth
tablegroup auth_core
note auth_readme
} from './auth.dbml'

Project modular_shop {
database_type: 'PostgreSQL'
Note: 'Example of the DBML module system (use / reuse).'
}

Table user_links {
user_id integer [pk, ref: - users.id]
billing_user_id integer [unique, ref: - billing_users.id]
auth_user_id integer [unique, ref: - auth.users.id]
}

Table order_invoices {
order_id integer [ref: > orders.id]
invoice_id integer [ref: > invoices.id]

indexes {
(order_id, invoice_id) [pk]
}
}

Metadata Table users {
owner: 'growth-team'
pii: true
}

Metadata Ref orders_user {
critical: true
}

DiagramView customer_360 {
Tables {
users
user_links
billing_users
orders
}
TableGroups { auth_core }
}