blob: 92d1f3739c942887c6e82c450340659e15187f98 (
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
|
.Dd February 12, 2026
.Dt BOLT-MIGRATION 5
.Os
.Sh NAME
.Nm bolt-migration
.Nd bolt migration script format
.Sh DESCRIPTION
Migration scripts are SQL files that define database schema changes. Each
migration file contains both the upgrade (up) and downgrade (down) SQL
statements.
.Sh FILE NAMING
Migration files are named using the pattern:
.Pp
.D1 Ar version Ns _ Ns Ar message Ns .sql
.Pp
Where
.Ar version
is a sequential number (e.g.,
.Li 001 ) .
.Xr bolt-new 1
picks the next number automatically.
.Pp
Each version must be unique. If two migrations exist with the
same version, Bolt refuses to run until one of them is renumbered.
.Sh DIRECTIVES
Migration files use comment directives to separate sections. All directives are
case-insensitive.
.Bl -tag -width Ds
.It Cm -- migrate:up Op Ar options
Marks the beginning of the upgrade section. All SQL statements following
this directive until the next directive or end of file are executed when
applying the migration.
.It Cm -- migrate:down Op Ar options
Marks the beginning of the downgrade section. All SQL statements following
this directive until the next directive or end of file are executed when
reverting the migration.
.El
.Sh OPTIONS
Options can be added to the
.Cm -- migrate:up
or
.Cm -- migrate:down
directives:
.Bl -tag -width Ds
.It Cm transaction:false
Execute the migration without a transaction. By default, each migration
runs within a transaction. Use this option for statements that cannot run
inside a transaction, such as
.Li CREATE INDEX CONCURRENTLY
in PostgreSQL.
.El
.Sh EXAMPLES
A basic migration:
.Bd -literal -offset indent
-- migrate:up
CREATE TABLE users (
id SERIAL PRIMARY KEY,
name VARCHAR(255) NOT NULL
);
-- migrate:down
DROP TABLE users;
.Ed
.Pp
A non-transactional migration:
.Bd -literal -offset indent
-- migrate:up transaction:false
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
-- migrate:down transaction:false
DROP INDEX CONCURRENTLY idx_users_email;
.Ed
.Sh SEE ALSO
.Xr bolt 1 ,
.Xr bolt-new 1 ,
.Xr bolt.toml 5 ,
.Xr bolt-execution 7
|