aboutsummaryrefslogtreecommitdiffstats
path: root/man/bolt-migration.5
blob: dd5080e8bd8d776754c311a61d8230190948b4bb (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
.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 either a timestamp (e.g.,
.Li 20240316145038 )
or sequential number (e.g.,
.Li 001 )
depending on the configured version style. See
.Xr bolt.toml 5
for configuration details.
.Sh DIRECTIVES
Migration files use comment directives to separate sections. All directives are
case-insensitive.
.Bl -tag -width Ds
.It Cm -- depends: Ar version1, version2, ...
Declares dependencies on other migrations. Dependencies determine execution
order. Multiple versions are separated by commas.
.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 with no dependencies:
.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 migration with a single dependency:
.Bd -literal -offset indent
-- depends: 20240316145038
-- migrate:up
CREATE TABLE posts (
    id SERIAL PRIMARY KEY,
    user_id INTEGER NOT NULL REFERENCES users(id)
);

-- migrate:down
DROP TABLE posts;
.Ed
.Pp
A migration with multiple dependencies:
.Bd -literal -offset indent
-- depends: 20240316145038, 20240317120000
-- migrate:up
CREATE TABLE comments (
    id SERIAL PRIMARY KEY,
    post_id INTEGER NOT NULL REFERENCES posts(id),
    user_id INTEGER NOT NULL REFERENCES users(id)
);

-- migrate:down
DROP TABLE comments;
.Ed
.Pp
A non-transactional migration:
.Bd -literal -offset indent
-- depends: 20240316145038
-- 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-dependencies 7 ,
.Xr bolt-execution 7