aboutsummaryrefslogtreecommitdiffstats
path: root/docs/how-to.md
blob: 0d5c3702215d73f5e1043973e16313c62e6e9b3b (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
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
# How-To Guides

This section contains guides for specific tasks you may want to accomplish with Bolt.

## How to execute a migration script without a transaction

By default, Bolt executes all migrations within a transaction. However, some
SQL commands cannot be executed within a transaction (for example, certain
DDL operations in some databases).

To execute a migration without a transaction, add a `transaction:false` option
to the migration directives:

```sql
-- migrate:up transaction:false
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);

-- migrate:down transaction:false
DROP INDEX CONCURRENTLY idx_users_email;
```

!!! note
    The `transaction:false` option can be applied independently to
    `-- migrate:up` and `-- migrate:down`. You can have one run in
    a transaction and the other not, depending on your needs.

## How to make a migration depend on a specific migrations

By default, Bolt automatically manages dependencies when you create a new
migration. To manually control which migrations must run first, add a
`-- depends:` directive at the top of the migration file.

Single dependency:

```sql
-- depends: 20240316145038
-- migrate:up
CREATE TABLE posts (
    id SERIAL PRIMARY KEY,
    user_id INTEGER NOT NULL REFERENCES users(id)
);

-- migrate:down
DROP TABLE posts;
```

Multiple dependencies (comma-separated):

```sql
-- 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;
```

Bolt ensures all listed migrations are applied before this one runs.

## How to determine migration execution order

Use `bolt status` to see migrations in the order they'll be executed:

```bash
bolt status
```

Output:
```
Version           Message               Applied
20240316145038    create_users          X
20240317120000    create_posts          X
20240318093000    add_comments
```

Migrations are listed in dependency order. Applied migrations show an `X` in
the Applied column.

## How to jump to a specific migration version

You can apply or revert migrations up to a specific version using the `-version` or `-v` flag.

### Upgrading to a specific version

To upgrade to and including a specific migration version:

```bash
bolt up -version 20240316145038
```

This will apply all unapplied migrations up to and including version `20240316145038`.

### Downgrading to a specific version

To downgrade to and including a specific migration version:

```bash
bolt down -version 20240316145038
```

This will revert all applied migrations down to and including version `20240316145038`.

## How to use environment variables for configuration

```bash
export BOLT_DB_DSN="postgresql://user:password@localhost:5432/mydb?sslmode=disable"
export BOLT_DB_DRIVER="postgresql"
bolt up
```

See the [reference](./reference.md#environment-variables) for the complete list
of environment variables supported.

!!! tip
    Environment variables take precedence over `bolt.toml` settings. You can
    use a mix of both, with environment variables overriding file-based
    configuration when needed.

## How to use a custom migrations table name

By default, Bolt uses a table named `bolt_migrations` to track applied
migrations. You can customize this table name in your configuration.

### In bolt.toml

```toml
[database]
migrations_table = "my_custom_migrations"
```

### Using environment variables

```bash
export BOLT_DB_MIGRATIONS_TABLE="my_custom_migrations"
```

### Using a different schema (PostgreSQL and MSSQL only)

```toml
[database]
migrations_table = "myschema.migrations"
```

## How to use sequential versioning instead of timestamps

By default, Bolt uses timestamp-based versioning for migrations
(e.g., `20240316145038`). You can switch to sequential versioning
(e.g., `001`, `002`, `003`) for new projects.

### In bolt.toml

```toml
[migrations]
version_style = "sequential"
```

### Using environment variables

```bash
export BOLT_MIGRATIONS_VERSION_STYLE="sequential"
```

!!! danger "Important"
    You shouldn't change version styles once you have existing migrations.
    Mixing timestamp and sequential versions is not well supported.