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
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
# Tutorial
In this tutorial, we'll guide you through the basics of using Bolt by running through how you can create a migration, apply it, revert it, and see the status of your migrations.
## Prerequisites
Before starting this tutorial, make sure you have:
- Bolt installed (see [Installation](installation.md))
- Docker installed (for running the database container)
## Creating your first migration
Run the following command to create your first migration:
```bash
bolt new -m "my first migration"
```
Output:
```
Created migration 20240316145038 - my first migration.
```
Upon completion, a migrations directory will be created with the following structure:
```bash
migrations
└── 20240316145038_my_first_migration.sql
1 directory, 1 file
```
Bolt automatically creates the migrations directory and your migration scripts inside it.
## Writing your migration scripts
Bolt utilizes plain SQL for migration scripts. Each migration file contains a comment for the upgrade script portion with `-- migrate:up` and a comment for the downgrade script with `-- migrate:down`.
1. Open up `20240316145038_my_first_migration.sql`
You'll see the following template in the file for your migration:
```sql
-- migrate:up
-- migrate:down
```
2. Write your migration script
```sql
-- 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(),
updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);
-- migrate:down
DROP TABLE users;
```
## Starting up a Database Container
We'll use Docker to run a PostgreSQL database container for this tutorial:
1. Install Docker
If you don't have docker installed, view the installation instructions [here](https://docs.docker.com/get-docker/).
2. Startup the PostgreSQL container
```bash
docker run \
--name bolt-postgres \
--env POSTGRES_USER=bolt_user \
--env POSTGRES_PASSWORD=bolt_password \
--env POSTGRES_DB=bolt_tutorial_db \
--publish 5432:5432 \
--detach \
postgres:latest
```
## Configuring Bolt
Bolt can be configured with a `bolt.toml` file or environment variables. For simplicity, we'll use a `bolt.toml` file in this tutorial.
1. Create a `bolt.toml` file:
```bash
touch bolt.toml
```
2. Add the following contents to the file:
```toml
[database]
dsn = "postgresql://bolt_user:bolt_password@localhost:5432/bolt_tutorial_db?sslmode=disable"
driver = "postgresql"
```
## Applying your migration
Apply your migration, which will execute the upgrade script:
```bash
bolt up
```
Output:
```
Applying migration 20240316145038_my_first_migration..
Successfully applied migration 20240316145038_my_first_migration in 3.217875ms!
```
## Checking Migration Status
To view the status of your migration:
```bash
bolt status
```
Output:
```
Version Message Applied
20240316145038 my_first_migration X
```
This command displays the migration's version, name, and whether the migration was applied or not.
## Verifying the Migration
Connect to the database container to confirm the users table was created:
```bash
docker exec -it bolt-postgres psql -U bolt_user -d bolt_tutorial_db
```
```psql
bolt_tutorial_db=# \dt
List of relations
Schema | Name | Type | Owner
--------+-----------------+-------+-----------
public | bolt_migrations | table | bolt_user
public | users | table | bolt_user
(2 rows)
```
We can see that our `users` table was created successfully. We also see another
table that we didn't explicitly create called `bolt_migrations`. This table is
used by Bolt to keep track of which migrations have been applied to your
database. Generally, you should not modify this table manually.
## Downgrading Your Migration
To revert your migration:
```bash
bolt down
```
Output:
```
Reverting migration 20240316145038_my_first_migration..
Successfully reverted migration 20240316145038_my_first_migration in 6.283667ms!
```
## Verifying Migration Reversion
Reconnect to the database container and check that the users table has been removed:
```bash
docker exec -it bolt-postgres psql -U bolt_user -d bolt_tutorial_db
```
```psql
bolt_tutorial_db=# \dt
List of relations
Schema | Name | Type | Owner
--------+-----------------+-------+-----------
public | bolt_migrations | table | bolt_user
(1 row)
```
## Next Steps
Congratulations! You've learned the core features of Bolt.
To learn more:
- Check out [How-To Guides](how-to.md) for specific tasks
- Browse the [Reference](reference.md) for detailed command and configuration documentation
- Read the [Explanation](explanation.md) section to understand how Bolt works internally
|