aboutsummaryrefslogtreecommitdiffstats
path: root/docs/how-to.md
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2025-10-10 23:11:16 -0400
committerEugene Triguba <hello@eugenetriguba.com>2025-10-10 23:11:16 -0400
commitc500a84b35338ac0f429133a0b07ced8d457976f (patch)
tree54d526e4c07c0171f8e6f41933b607a8ab09127c /docs/how-to.md
parentAdd note on contributing guide to README (diff)
downloadcli-c500a84b35338ac0f429133a0b07ced8d457976f.zip
Refactor docs to use mkdocs and sourcehut pages
Diffstat (limited to 'docs/how-to.md')
-rw-r--r--docs/how-to.md116
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.