diff options
| -rw-r--r-- | docs/explanation.md | 58 |
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? |