diff options
| author | Eugene Triguba <hello@eugenetriguba.com> | 2025-10-11 00:03:56 -0400 |
|---|---|---|
| committer | Eugene Triguba <hello@eugenetriguba.com> | 2025-10-11 00:03:56 -0400 |
| commit | f16fb506a937b8e37982143698d33922464c294d (patch) | |
| tree | 12c67c0e0ffd3e4457a433ca8062957633488f69 /docs | |
| parent | Adjust formatting of a few bullets in explanation.md (diff) | |
| download | cli-f16fb506a937b8e37982143698d33922464c294d.zip | |
Fix more bullet formats in explanations
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/explanation.md | 20 |
1 files changed, 15 insertions, 5 deletions
diff --git a/docs/explanation.md b/docs/explanation.md index b3b63a3..d10d35f 100644 --- a/docs/explanation.md +++ b/docs/explanation.md @@ -59,11 +59,13 @@ When you run `bolt up`, the following process occurs: haven't been applied 4. **Sorting**: Pending migrations are sorted by version (oldest first) 5. **Execution**: For each pending migration: + - The file is read and parsed to extract the `-- migrate:up` portion - A transaction is started (unless `transaction:false` is specified) - The SQL is executed - The version is inserted into the tracking table - The transaction is committed + 6. **Reporting**: Success or failure is reported for each migration. If any migrations fail to be applied, the process halts and no more migrations are applied. @@ -85,11 +87,13 @@ When you run `bolt down`, the following process occurs: 3. **Matching**: Applied versions are matched against local migration files 4. **Sorting**: Applied migrations are sorted by version (newest first for reverting) 5. **Execution**: For the most recent applied migration (or down to a target version): + - The file is read and parsed to extract the `-- migrate:down` portion - A transaction is started (unless `transaction:false` is specified) - The SQL is executed - The version is removed from the tracking table - The transaction is committed + 6. **Reporting**: Success or failure is reported for each migration. If any migrations fail to be reverted, the process halts and no more migrations are applied. @@ -128,6 +132,7 @@ Bolt supports two version styles: Format: `YYYYMMDDHHMMSS` (e.g., `20240316145038`) The version represents the timestamp when the migration was created: + - `2024` - Year - `03` - Month - `16` - Day @@ -140,7 +145,6 @@ The version represents the timestamp when the migration was created: - **Pros:** - Avoids filename conflicts when multiple developers create migrations on different branches - Embeds creation time in the version number - - **Cons:** - Migration order may not match merge order (e.g., if a migration with an earlier timestamp is merged after one with a later timestamp, it will run out of chronological order) - Longer, harder to remember version numbers @@ -154,12 +158,13 @@ Format: Zero-padded integers (e.g., `001`, `002`, `003`) The version is simply an incrementing counter. **Trade-offs:** + - **Pros:** - - Simple, easy-to-remember version numbers - - Clear sequential ordering intention + - Simple, easy-to-remember version numbers + - Clear sequential ordering intention - **Cons:** - - Multiple developers creating migrations on different branches will create filename conflicts (e.g., both create `003_...sql`), requiring manual resolution during merge - - Forces explicit coordination between developers + - Multiple developers creating migrations on different branches will create filename conflicts (e.g., both create `003_...sql`), requiring manual resolution during merge + - Forces explicit coordination between developers **Best for:** Single-developer projects or teams with strict coordination where you want simple version numbers and explicit conflict resolution. @@ -265,16 +270,19 @@ While you can configure the database table that Bolt uses for tracking applied m ### Naming Restrictions The migrations table name must: + - Contain only alphanumeric characters and underscores - Follow your database's table naming rules Valid examples: + - `bolt_migrations` (default) - `my_custom_migrations` - `migrations_v2` - `app_schema_versions` Invalid examples: + - `my-migrations` (contains hyphen) - `my.custom.migrations` (contains multiple dots) - `migrations!` (contains special character) @@ -289,6 +297,7 @@ migrations_table = "myschema.migrations" ``` **Schema support:** + - ✓ **PostgreSQL**: Full support for schemas - ✓ **SQL Server**: Full support for schemas - ✗ **MySQL**: Does not support schemas (use databases instead) @@ -297,6 +306,7 @@ migrations_table = "myschema.migrations" ### Why These Restrictions? These restrictions exist to: + - Ensure cross-database compatibility - Prevent SQL injection risks - Avoid parsing ambiguities |