diff options
| author | Eugene Triguba <hello@eugenetriguba.com> | 2025-10-18 10:43:39 -0400 |
|---|---|---|
| committer | Eugene Triguba <hello@eugenetriguba.com> | 2025-11-26 11:46:57 -0500 |
| commit | e5658d1f61415054029b66cd2f703f1f40138460 (patch) | |
| tree | c609e209f4cebc62dd985d1b773558f47eb73bf6 /docs/how-to.md | |
| parent | Add is-branch main check for docs deployment (diff) | |
| download | cli-e5658d1f61415054029b66cd2f703f1f40138460.zip | |
Add support for migration dependencies
Diffstat (limited to 'docs/how-to.md')
| -rw-r--r-- | docs/how-to.md | 101 |
1 files changed, 77 insertions, 24 deletions
diff --git a/docs/how-to.md b/docs/how-to.md index 5d59a39..0d5c370 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -4,9 +4,12 @@ This section contains guides for specific tasks you may want to accomplish with ## 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). +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: +To execute a migration without a transaction, add a `transaction:false` option +to the migration directives: ```sql -- migrate:up transaction:false @@ -17,7 +20,65 @@ 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. + 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 @@ -45,37 +106,29 @@ This will revert all applied migrations down to and including version `202403161 ## 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 ``` +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. + 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. +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" ``` @@ -92,12 +145,11 @@ export BOLT_DB_MIGRATIONS_TABLE="my_custom_migrations" 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. +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 @@ -113,4 +165,5 @@ 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. + You shouldn't change version styles once you have existing migrations. + Mixing timestamp and sequential versions is not well supported. |