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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
.Dd February 12, 2026
.Dt BOLT-EXECUTION 7
.Os
.Sh NAME
.Nm bolt-execution
.Nd how migrations are executed
.Sh DESCRIPTION
This document explains how
.Xr bolt 1
executes migration scripts, including transaction behavior, the apply
process, and the revert process.
.Sh TRANSACTION BEHAVIOR
By default, each migration runs within a database transaction:
.Bl -enum -offset Ds
.It
Bolt opens a database connection.
.It
Begins a transaction.
.It
Executes the SQL statements.
.It
If successful, commits the transaction and records the migration as applied.
.It
If an error occurs, rolls back the transaction and exits with an error.
.El
.Ss Database Considerations
Some databases auto-commit certain DDL statements even within a transaction.
MySQL, for example, auto-commits statements like
.Li CREATE TABLE .
This means if a migration fails partway through, some changes may have
already been committed.
.Ss Disabling Transactions
For operations that cannot run within a transaction (like
.Li CREATE INDEX CONCURRENTLY
in PostgreSQL), use the
.Cm transaction:false
option:
.Bd -literal -offset indent
-- migrate:up transaction:false
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
.Ed
.Sh TRACKING TABLE
Bolt tracks applied migrations in a database table (default:
.Li bolt_migrations ) .
The table has a single column:
.Bl -tag -width Ds
.It Li version
The version identifier of each applied migration.
.El
.Pp
The migration message is not stored; it exists only in the filename for
human readability.
.Sh APPLYING MIGRATIONS
When you run
.Xr bolt-up 1 :
.Bl -enum -offset Ds
.It
.Sy Discovery :
Bolt scans the migrations directory for
.Pa .sql
files.
.It
.Sy Parsing :
Each file is parsed to extract the version, message, and dependencies.
.It
.Sy Comparison :
Bolt queries the tracking table to find unapplied migrations.
.It
.Sy Ordering :
Pending migrations are ordered by their dependencies.
.It
.Sy Execution :
For each pending migration:
.Bl -bullet -offset Ds -compact
.It
The
.Cm -- migrate:up
section is extracted.
.It
All dependencies are verified to be applied.
.It
A transaction is started (unless disabled).
.It
The SQL is executed.
.It
The version is inserted into the tracking table.
.It
The transaction is committed.
.El
.It
.Sy Reporting :
Success or failure is reported. If any migration fails, the process halts.
.El
.Sh REVERTING MIGRATIONS
When you run
.Xr bolt-down 1 :
.Bl -enum -offset Ds
.It
.Sy Discovery :
Bolt scans the migrations directory.
.It
.Sy Query :
Bolt queries the tracking table for applied migrations.
.It
.Sy Matching :
Applied versions are matched against local files.
.It
.Sy Ordering :
Applied migrations are ordered in reverse dependency order.
.It
.Sy Execution :
For the target migration(s):
.Bl -bullet -offset Ds -compact
.It
The
.Cm -- migrate:down
section is extracted.
.It
Bolt verifies no other applied migrations depend on this one.
.It
A transaction is started (unless disabled).
.It
The SQL is executed.
.It
The version is removed from the tracking table.
.It
The transaction is committed.
.El
.It
.Sy Reporting :
Success or failure is reported. If any revert fails, the process halts.
.El
.Sh MISSING FILES
If a migration has been applied but the file no longer exists locally, Bolt
cannot revert it automatically. You must either restore the file or manually
revert the changes and remove the version from the tracking table.
.Pp
Migration files should be committed to version control and not deleted.
.Sh SEE ALSO
.Xr bolt 1 ,
.Xr bolt-down 1 ,
.Xr bolt-up 1 ,
.Xr bolt-migration 5 ,
.Xr bolt-dependencies 7
|