aboutsummaryrefslogtreecommitdiffstats
path: root/docs/how-to.md
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2025-10-18 10:43:39 -0400
committerEugene Triguba <hello@eugenetriguba.com>2025-11-26 11:46:57 -0500
commite5658d1f61415054029b66cd2f703f1f40138460 (patch)
treec609e209f4cebc62dd985d1b773558f47eb73bf6 /docs/how-to.md
parentAdd is-branch main check for docs deployment (diff)
downloadcli-e5658d1f61415054029b66cd2f703f1f40138460.zip
Add support for migration dependencies
Diffstat (limited to 'docs/how-to.md')
-rw-r--r--docs/how-to.md101
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.