aboutsummaryrefslogtreecommitdiffstats
path: root/docs/how-to.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/how-to.md')
-rw-r--r--docs/how-to.md169
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.