aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2025-10-11 00:03:56 -0400
committerEugene Triguba <hello@eugenetriguba.com>2025-10-11 00:03:56 -0400
commitf16fb506a937b8e37982143698d33922464c294d (patch)
tree12c67c0e0ffd3e4457a433ca8062957633488f69 /docs
parentAdjust formatting of a few bullets in explanation.md (diff)
downloadcli-f16fb506a937b8e37982143698d33922464c294d.zip
Fix more bullet formats in explanations
Diffstat (limited to 'docs')
-rw-r--r--docs/explanation.md20
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