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:

-- 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:

-- 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):

-- 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:

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:

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:

bolt down -version 20240316145038

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

How to use environment variables for configuration¶

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

See the reference 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¶

[database]
migrations_table = "my_custom_migrations"

Using environment variables¶

export BOLT_DB_MIGRATIONS_TABLE="my_custom_migrations"

Using a different schema (PostgreSQL and MSSQL only)¶

[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¶

[migrations]
version_style = "sequential"

Using environment variables¶

export BOLT_MIGRATIONS_VERSION_STYLE="sequential"

Important

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