diff options
| author | Eugene Triguba <hello@eugenetriguba.com> | 2025-10-10 23:11:16 -0400 |
|---|---|---|
| committer | Eugene Triguba <hello@eugenetriguba.com> | 2025-10-10 23:11:16 -0400 |
| commit | c500a84b35338ac0f429133a0b07ced8d457976f (patch) | |
| tree | 54d526e4c07c0171f8e6f41933b607a8ab09127c /docs/how-to.md | |
| parent | Add note on contributing guide to README (diff) | |
| download | cli-c500a84b35338ac0f429133a0b07ced8d457976f.zip | |
Refactor docs to use mkdocs and sourcehut pages
Diffstat (limited to 'docs/how-to.md')
| -rw-r--r-- | docs/how-to.md | 116 |
1 files changed, 116 insertions, 0 deletions
diff --git a/docs/how-to.md b/docs/how-to.md new file mode 100644 index 0000000..5d59a39 --- /dev/null +++ b/docs/how-to.md @@ -0,0 +1,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. |