aboutsummaryrefslogtreecommitdiffstats
path: root/docs/explanation.md
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2025-10-11 00:00:19 -0400
committerEugene Triguba <hello@eugenetriguba.com>2025-10-11 00:00:19 -0400
commitd523b671a6837dbc3b1adbe4ebae430f28c0ecba (patch)
tree405269327c4366686194f088aede38a43190bdbc /docs/explanation.md
parentUpdate README to remove logo (diff)
downloadcli-d523b671a6837dbc3b1adbe4ebae430f28c0ecba.zip
Reword tradeoffs for version styles
Diffstat (limited to 'docs/explanation.md')
-rw-r--r--docs/explanation.md58
1 files changed, 37 insertions, 21 deletions
diff --git a/docs/explanation.md b/docs/explanation.md
index d01eb90..1d1393b 100644
--- a/docs/explanation.md
+++ b/docs/explanation.md
@@ -55,15 +55,18 @@ When you run `bolt up`, the following process occurs:
1. **Discovery**: Bolt scans your migrations directory for all `.sql` files
2. **Parsing**: Each filename is parsed to extract the version and message
-3. **Comparison**: Bolt queries the tracking table to determine which migrations haven't been applied
+3. **Comparison**: Bolt queries the tracking table to determine which migrations
+ 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
+ - 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.
### Applying to a Specific Version
@@ -82,12 +85,15 @@ 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
+ - 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.
+
### Reverting to a Specific Version
@@ -129,10 +135,15 @@ The version represents the timestamp when the migration was created:
- `50` - Minute
- `38` - Second
-**Best for:**
-- Teams with multiple developers
-- Distributed development where migrations may be created simultaneously on different branches
-- When you want to know when a migration was created
+**Trade-offs:**
+- **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
+
+**Best for:** Teams working on multiple branches simultaneously where avoiding Git merge conflicts is prioritized over strict chronological ordering.
### Sequential Versions
@@ -140,10 +151,15 @@ Format: Zero-padded integers (e.g., `001`, `002`, `003`)
The version is simply an incrementing counter.
-**Best for:**
-- Solo developers
-- Small teams with linear development workflows
-- When you prefer simple, easy-to-remember version numbers
+**Trade-offs:**
+- **Pros:**
+ - 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
+
+**Best for:** Single-developer projects or teams with strict coordination where you want simple version numbers and explicit conflict resolution.
## Why can't I change between version styles?