diff options
Diffstat (limited to 'docs/how-to.md')
| -rw-r--r-- | docs/how-to.md | 169 |
1 files changed, 0 insertions, 169 deletions
diff --git a/docs/how-to.md b/docs/how-to.md deleted file mode 100644 index 0d5c370..0000000 --- a/docs/how-to.md +++ /dev/null @@ -1,169 +0,0 @@ -# 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 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 - -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 - -```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. - -## 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] -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" -``` - -## 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 shouldn't change version styles once you have existing migrations. - Mixing timestamp and sequential versions is not well supported. |