You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[Re-Exporting with `reuse`](#re-exporting-with-reuse)
18
-
-[Circular Imports](#circular-imports)
15
+
-[Notes](#notes)
19
16
20
17
## Overview
21
18
22
19
Use `use` to import elements from another file:
23
20
24
21
```text
25
22
use {
26
-
kind name
23
+
type name
27
24
} from './path-to-file'
28
25
```
29
26
30
-
-**`kind`** — the element kind: `table`, `enum`, `tablepartial`, `schema`, or `tablegroup`. See [Supported Import Kinds](#supported-import-kinds).
27
+
-**`type`** — the element type: `table`, `enum`, `tablepartial`, `note`, `schema`, or `tablegroup`. See [Supported Import Types](#supported-import-types).
31
28
-**`name`** — the element name as declared in the source file
32
29
-**`./path-to-file`** — a relative path to the source file; the `.dbml` extension is optional (`'./types'` and `'./types.dbml'` both work)
33
30
@@ -36,7 +33,9 @@ use {
36
33
Enum job_status {
37
34
pending running done
38
35
}
36
+
```
39
37
38
+
```text
40
39
// jobs.dbml
41
40
use {
42
41
enum job_status
@@ -48,47 +47,37 @@ Table jobs {
48
47
}
49
48
```
50
49
51
-
Each file is isolated by default — nothing is visible across files unless explicitly imported. Imports are also not transitive: if `a.dbml` imports `b.dbml` and `b.dbml` imports `c.dbml`, elements from `c.dbml` are not available in `a.dbml`.
50
+
Each file is isolated by default — nothing is visible across files unless explicitly imported.
52
51
53
52
## Selective Import
54
53
55
-
When you only need a few specific elements from another file, list them by kind and name.
54
+
You can selectively pick some elements from another file to import into the current file.
56
55
57
56
```text
58
-
// types.dbml
59
-
Enum job_status {
60
-
pending
61
-
running
62
-
done
57
+
// shared.dbml
58
+
Table users {
59
+
id int [pk]
63
60
}
64
61
65
-
// jobs.dbml
66
-
use {
67
-
enum job_status
68
-
} from './types'
62
+
Enum role {
63
+
admin member
64
+
}
69
65
70
-
Table jobs {
66
+
Table products {
71
67
id int [pk]
72
-
status job_status
68
+
user_id int [ref: > users.id]
73
69
}
74
70
```
75
71
76
-
Multiple entries can appear in one block or across separate statements:
77
-
78
72
```text
73
+
// products won't be imported here
79
74
use {
80
75
table users
81
76
enum role
82
77
} from './shared'
83
-
84
-
use {
85
-
table orders
86
-
} from './orders'
87
78
```
88
79
89
-
Only the named elements become available in the importing file. Everything else in the source file stays out of scope.
@@ -99,70 +88,83 @@ Only the named elements become available in the importing file. Everything else
99
88
|`schema`| All elements under that schema |
100
89
|`tablegroup`| TableGroup (all tables in the group) |
101
90
102
-
Element kind keywords are case-insensitive (`Table`, `TABLE`, and `table` are all valid).
103
-
104
-
### Importing a Schema
105
-
106
-
When a source file defines multiple tables under the same schema, importing the schema brings all of them in at once instead of listing each table individually.
91
+
Element type keywords are case-insensitive (`Table`, `TABLE`, and `table` are all valid).
107
92
108
93
```text
109
94
// auth.dbml
110
95
Table auth.users {
111
96
id int [pk]
97
+
email varchar
112
98
}
113
99
114
100
Table auth.roles {
115
101
id int [pk]
102
+
name varchar
116
103
}
117
104
118
105
Table auth.sessions {
119
106
id int [pk]
120
107
}
121
108
122
-
// main.dbml
109
+
TableGroup auth_core {
110
+
auth.users
111
+
auth.roles
112
+
}
113
+
```
114
+
115
+
```text
116
+
// u is available as a table here
117
+
use {
118
+
table auth.users as u
119
+
} from './auth'
120
+
121
+
// auth.users, auth.roles, auth.sessions are available here
123
122
use {
124
123
schema auth
125
124
} from './auth'
126
125
127
-
Table orders {
128
-
id int [pk]
129
-
user_id int [ref: > auth.users.id]
130
-
}
126
+
// auth_core, auth.user, auth.roles are available here
127
+
use {
128
+
tablegroup auth_core
129
+
} from './auth'
131
130
```
132
131
133
-
All tables, enums, and other elements declared under the `auth` schema become available in `main.dbml` under their original schema-qualified names.
134
-
135
-
### Importing a TableGroup
132
+
### Import Aliases
136
133
137
-
Importing a `tablegroup` brings the group definition itself into scope, along with all the tables it references.
134
+
When two files define elements with the same name, use `as` to rename imports and avoid conflicts.
138
135
139
136
```text
140
-
// base.dbml
137
+
// auth.dbml
141
138
Table users {
142
139
id int [pk]
140
+
email varchar
143
141
}
142
+
```
144
143
145
-
Table posts {
144
+
```text
145
+
// billing.dbml
146
+
Table users {
146
147
id int [pk]
147
-
user_id int
148
+
amount decimal
148
149
}
150
+
```
149
151
150
-
TableGroup blog {
151
-
users
152
-
posts
153
-
}
152
+
```text
153
+
// Alias the tables to avoid name conflicts
154
+
use {
155
+
table users as auth_users
156
+
} from './auth'
154
157
155
-
// main.dbml
156
158
use {
157
-
tablegroup blog
158
-
} from './base'
159
+
table users as billing_users
160
+
} from './billing'
159
161
```
160
162
161
-
The `blog` tablegroup and its member tables (`users`, `posts`) are all available in `main.dbml`.
163
+
Once aliased, only the alias name is accessible — the original name is not.
162
164
163
-
## Wildcard Import
165
+
## Import All
164
166
165
-
When you want everything a file has to offer, use a wildcard instead of listing each element individually.
167
+
When you want everything a file exports, use `*`instead of listing each element.
166
168
167
169
```text
168
170
// base.dbml
@@ -173,121 +175,106 @@ Table users {
173
175
Table orders {
174
176
id int [pk]
175
177
}
178
+
```
176
179
177
-
// main.dbml
180
+
```text
181
+
// Everything from ./base.dbml will be imported
178
182
use * from './base'
179
183
180
184
Ref: orders.user_id > users.id
181
185
```
182
186
183
-
Wildcard and selective imports from the same file can coexist; any duplicate names are deduplicated automatically.
187
+
`use *` and selective imports from the same file can coexist; any duplicate names are deduplicated automatically.
184
188
185
-
## Import Aliases
189
+
## Re-Exporting with `reuse`
186
190
187
-
When two files define elements with the same name, or when you want a shorter name locally, use `as` to rename an import.
191
+
`use` makes imported elements available only in the current file. If another file imports the current file, it will **not** see elements brought in via `use`:
188
192
189
193
```text
190
-
// auth.dbml
191
-
Table auth.users {
192
-
id int [pk]
193
-
email varchar
194
-
}
194
+
// common/index.dbml
195
+
use * from './users'
196
+
use * from './orders'
197
+
```
195
198
199
+
```text
196
200
// main.dbml
197
-
use {
198
-
table auth.users as u
199
-
} from './auth'
200
-
201
-
Table orders {
202
-
id int [pk]
203
-
user_id int [ref: > u.id]
204
-
}
201
+
// users and orders are NOT available here
202
+
use * from './common/index'
205
203
```
206
204
207
-
Once aliased, only the alias name (`u`) is accessible — the original name is not. Aliases also strip any schema prefix, so `auth.users as u` is visible as plain `u` in the default schema.
208
-
209
-
The same element can be imported multiple times under different aliases. Giving two different elements the same alias name is an error.
210
-
211
-
## Schema-Qualified Import
212
-
213
-
To import elements that live inside a named schema, qualify the name with the schema.
205
+
`reuse` goes one step further — it also makes them visible to any file that imports the current file.
214
206
215
207
```text
216
-
// auth.dbml
217
-
Table auth.users {
218
-
id int [pk]
219
-
}
220
-
221
-
Table auth.roles {
222
-
id int [pk]
223
-
}
208
+
// common/index.dbml
209
+
reuse * from './users'
210
+
reuse * from './orders'
211
+
```
224
212
213
+
```text
225
214
// main.dbml
226
-
use {
227
-
table auth.users
228
-
} from './auth'
215
+
// users and orders are available here
216
+
use * from './common/index'
229
217
```
230
218
231
-
Without an alias the element keeps its schema-qualified name (`auth.users`). Combined with `as`, it is placed in the default schema under the alias:
219
+
`reuse` is best for cases where you want to expose some schema elements to other consumers, without forcing the consumers to be aware of the internal folder structure of your project.
220
+
221
+
### The Barrel File Pattern With `reuse`
222
+
223
+
To illustrate a use case of `reuse`, suppose you have a project named `management` that is split into 3 files for easier personal management: `management/users.dbml`, `management/products.dbml`, `management/orders.dbml`.
224
+
225
+
With `use`, all consumers of `management` must be aware of your project structure to import everything:
232
226
233
227
```text
234
-
use {
235
-
table auth.users as u
236
-
} from './auth'
237
-
// visible as: u (no schema prefix)
228
+
// Consumer's file
229
+
use * from './management/users'
230
+
use * from './management/products'
231
+
use * from './management/orders'
238
232
```
239
233
240
-
## Re-Exporting with `reuse`
234
+
This is fragile, as when you decide to reorganize your project (e.g. merge `products` and `orders` into one file), all consumers' schemas will be broken.
241
235
242
-
When you do want a file to pass elements through to its own importers — for example, a barrel file that composes several sub-files — use `reuse`instead of `use`.
236
+
With `reuse`, you can do this instead:
243
237
244
238
```text
245
-
// common/index.dbml
239
+
// management/index.dbml
240
+
// You totally control this file
246
241
reuse * from './users'
247
-
reuse * from './orders'
248
242
reuse * from './products'
249
-
250
-
// main.dbml
251
-
use * from './common/index'
243
+
reuse * from './orders'
252
244
```
253
245
254
-
Consumers of `common/index.dbml` never need to know how the files are organized internally. If you later restructure the sub-files, only the barrel changes — not every consumer.
255
-
256
-
`reuse` works with selective imports and aliases too:
246
+
Now, the consumers only have to import this barrel file:
257
247
258
248
```text
259
-
reuse {
260
-
table users
261
-
} from './base'
262
-
263
-
reuse {
264
-
table auth.users as u
265
-
} from './auth'
249
+
// Consumer's file
250
+
use * from './management/index'
266
251
```
267
252
268
-
## Circular Imports
253
+
This way, you can reorganize your project as you wish, only needing to modify your own barrel file. Your consumers never need to be aware of your changes.
254
+
255
+
## Notes
269
256
270
-
Because DBML is declarative, files can freely reference each other without any issues.
257
+
**`use` is not transitive** — If `a.dbml` imports `b.dbml` and `b.dbml` imports `c.dbml` via `use`, elements from `c.dbml` would not be available in `a.dbml`. Use [`reuse`](#re-exporting-with-reuse) if you need to pass elements through.
258
+
259
+
**Circular imports** — Because DBML is declarative, files can reference each other without any issues. For example, `users.dbml` can import from `orders.dbml` and vice versa.
0 commit comments