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
|
.Dd February 12, 2026
.Dt BOLT-TUTORIAL 7
.Os
.Sh NAME
.Nm bolt-tutorial
.Nd getting started with bolt
.Sh DESCRIPTION
This tutorial guides you through the basics of using
.Xr bolt 1
to manage database migrations.
.Sh PREREQUISITES
Before starting, ensure you have:
.Bl -bullet -offset Ds -compact
.It
Bolt installed
.It
A database available (PostgreSQL, MySQL, SQL Server, or SQLite)
.El
.Sh CREATING YOUR FIRST MIGRATION
Create a migration with:
.Dl $ bolt new -m \(dqcreate users table\(dq
.Pp
This creates a
.Pa migrations/
directory with a file like:
.Dl 20240316145038_create_users_table.sql
.Sh WRITING MIGRATION SCRIPTS
Edit the migration file to add SQL statements:
.Bd -literal -offset indent
-- migrate:up
CREATE TABLE users (
id SERIAL PRIMARY KEY,
name VARCHAR(255) NOT NULL,
email VARCHAR(255) NOT NULL,
created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
-- migrate:down
DROP TABLE users;
.Ed
.Pp
The
.Cm -- migrate:up
section runs when applying the migration.
The
.Cm -- migrate:down
section runs when reverting it.
.Sh CONFIGURING BOLT
Create a
.Pa bolt.toml
file:
.Bd -literal -offset indent
[database]
dsn = "postgresql://user:password@localhost:5432/mydb?sslmode=disable"
driver = "postgresql"
.Ed
.Pp
See
.Xr bolt.toml 5
for all configuration options.
.Sh APPLYING MIGRATIONS
Apply all pending migrations:
.Dl $ bolt up
.Pp
Apply up to a specific version:
.Dl $ bolt up -v 20240316145038
.Sh CHECKING STATUS
View migration status:
.Dl $ bolt status
.Pp
Output shows version, message, and whether each migration is applied.
.Sh REVERTING MIGRATIONS
Revert the most recent migration:
.Dl $ bolt down
.Pp
Revert to a specific version:
.Dl $ bolt down -v 20240316145038
.Sh WORKING WITH DEPENDENCIES
When you create a second migration, Bolt automatically adds a dependency
on existing migrations:
.Bd -literal -offset indent
-- depends: 20240316145038
-- migrate:up
CREATE TABLE posts (
id SERIAL PRIMARY KEY,
user_id INTEGER NOT NULL REFERENCES users(id),
title VARCHAR(255) NOT NULL
);
-- migrate:down
DROP TABLE posts;
.Ed
.Pp
Dependencies ensure migrations run in the correct order. See
.Xr bolt-dependencies 7
for details.
.Sh SEE ALSO
.Xr bolt 1 ,
.Xr bolt.toml 5 ,
.Xr bolt-migration 5 ,
.Xr bolt-dependencies 7
|