aboutsummaryrefslogtreecommitdiffstats
path: root/man/bolt-dependencies.7
blob: 4188fcb10185193d1bf18113c88a3a05ead4e068 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
.Dd February 12, 2026
.Dt BOLT-DEPENDENCIES 7
.Os
.Sh NAME
.Nm bolt-dependencies
.Nd migration dependency system
.Sh DESCRIPTION
Migration dependencies solve a fundamental problem in collaborative database
development: ensuring migrations run in the correct order regardless of when
they were created or merged.
.Sh THE PROBLEM
.Ss Sequential Versions
Developer A creates migration
.Li 002
for feature X on branch A. Developer B creates migration
.Li 002
for feature Y on branch B. When branches merge, there is a filename conflict.
.Ss Timestamp Versions
Developer A creates migration
.Li 20251013214743
on branch A. Developer B creates migration
.Li 20251013214799
on branch B. Developer B merges first. Developer A merges second.
.Pp
In this environment, both migrations apply successfully. However, when a
fresh database is set up (staging, production, new developer), migrations
run in timestamp order: A's migration runs first, then B's. This is the
opposite order from the original development environment. If B's migration
depends on A's changes, the fresh setup fails.
.Sh THE SOLUTION
Instead of relying on version numbers, migrations explicitly declare which
other migrations they depend on using the
.Cm -- depends:
directive:
.Bd -literal -offset indent
-- depends: 20240316145038
-- migrate:up
CREATE TABLE posts (
    user_id INTEGER REFERENCES users(id)
);
.Ed
.Pp
This creates a dependency graph where Bolt determines execution order based
on what migrations need to run before others, not when they were created.
.Sh AUTOMATIC POPULATION
When you create a new migration with
.Xr bolt-new 1 ,
Bolt automatically populates the
.Cm -- depends:
directive with current
.Dq leaf
migrations (migrations that no other migration depends on).
.Pp
This means:
.Bl -bullet -offset Ds -compact
.It
The first migration has no dependencies.
.It
The second migration depends on the first.
.It
Migrations created in parallel branches will both be listed as dependencies
in subsequent migrations after merging.
.El
.Sh EXECUTION ORDER
Bolt uses topological sorting to determine execution order:
.Bl -enum -offset Ds -compact
.It
Migrations with no dependencies run first.
.It
Once a migration completes, migrations depending only on completed
migrations become eligible.
.It
When multiple migrations are eligible, version number is used as a
tiebreaker for deterministic ordering.
.El
.Sh VALIDATION
Bolt validates the dependency graph before execution:
.Bl -tag -width Ds
.It Before applying
Verifies all dependencies exist and have been applied. This step detects
any circular dependencies.
.It Before reverting
Ensures no other applied migrations depend on the migration being reverted.
.El
.Sh EXAMPLES
No dependencies (root migration):
.Bd -literal -offset indent
-- migrate:up
CREATE TABLE users (id SERIAL PRIMARY KEY);

-- migrate:down
DROP TABLE users;
.Ed
.Pp
Single dependency:
.Bd -literal -offset indent
-- depends: 20240316145038
-- migrate:up
CREATE TABLE posts (user_id INTEGER REFERENCES users(id));

-- migrate:down
DROP TABLE posts;
.Ed
.Pp
Multiple dependencies:
.Bd -literal -offset indent
-- depends: 20240316145038, 20240317120000
-- migrate:up
CREATE TABLE comments (
    post_id INTEGER REFERENCES posts(id),
    user_id INTEGER REFERENCES users(id)
);

-- migrate:down
DROP TABLE comments;
.Ed
.Sh SEE ALSO
.Xr bolt 1 ,
.Xr bolt-new 1 ,
.Xr bolt-migration 5 ,
.Xr bolt-execution 7