aboutsummaryrefslogtreecommitdiffstats
path: root/man/bolt-execution.7
blob: 5e5d64c5c8de0e7798aaad7d70382cdab8765da2 (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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
.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 name is parsed to extract the version and message.
.It
.Sy Comparison :
Bolt queries the tracking table to find unapplied migrations.
.It
.Sy Ordering :
Pending migrations are ordered by version, oldest first.
.It
.Sy Execution :
For each pending migration:
.Bl -bullet -offset Ds -compact
.It
The
.Cm -- migrate:up
section is extracted.
.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 by version, newest first.
.It
.Sy Execution :
For the target migration(s):
.Bl -bullet -offset Ds -compact
.It
The
.Cm -- migrate:down
section is extracted.
.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