# 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.