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
|
# 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 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
Instead of using a `bolt.toml` file, you can configure Bolt using environment variables. This is particularly useful for CI/CD environments or when you want to keep sensitive information out of configuration files.
### Available environment variables
- `BOLT_MIGRATIONS_DIR_PATH` - The directory where your migration scripts are located
- `BOLT_MIGRATIONS_VERSION_STYLE` - The migration versioning style (`timestamp` or `sequential`)
- `BOLT_DB_DSN` - The database connection string (DSN)
- `BOLT_DB_DRIVER` - The database driver (`postgresql`, `mysql`, `mssql`, or `sqlite3`)
- `BOLT_DB_MIGRATIONS_TABLE` - The name of the migrations tracking table
### Example
```bash
export BOLT_DB_DSN="postgresql://user:password@localhost:5432/mydb?sslmode=disable"
export BOLT_DB_DRIVER="postgresql"
bolt up
```
!!! 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]
dsn = "postgresql://user:password@localhost:5432/mydb"
driver = "postgresql"
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"
```
!!! warning "Restrictions"
The migrations table name must only contain alphanumeric characters or underscores (e.g., `my_custom_table`). It may contain one dot (`.`) if specifying a schema, but custom schemas are only supported with PostgreSQL and MSSQL.
## 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 cannot change version styles once you have existing migrations. Mixing timestamp and sequential versions is not supported. See the [Explanation](explanation.md#why-cant-i-change-between-version-styles) section for more details.
|