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