diff options
| author | Eugene Triguba <hello@eugenetriguba.com> | 2026-11-13 21:43:11 -0800 |
|---|---|---|
| committer | Eugene Triguba <hello@eugenetriguba.com> | 2026-11-13 21:43:11 -0800 |
| commit | 28dd0bfc1373746b8c056a211f068da71fdc80b2 (patch) | |
| tree | 9c04a08501bc5abe7413263f60eaa55400dd162f /man | |
| parent | Release v0.13.1 (diff) | |
| download | cli-28dd0bfc1373746b8c056a211f068da71fdc80b2.zip | |
Remove migration dependencies
Diffstat (limited to 'man')
| -rw-r--r-- | man/bolt-dependencies.7 | 121 | ||||
| -rw-r--r-- | man/bolt-down.1 | 2 | ||||
| -rw-r--r-- | man/bolt-execution.7 | 13 | ||||
| -rw-r--r-- | man/bolt-migration.5 | 34 | ||||
| -rw-r--r-- | man/bolt-new.1 | 12 | ||||
| -rw-r--r-- | man/bolt-status.1 | 3 | ||||
| -rw-r--r-- | man/bolt-tutorial.7 | 22 | ||||
| -rw-r--r-- | man/bolt-up.1 | 4 | ||||
| -rw-r--r-- | man/bolt.1 | 1 |
9 files changed, 10 insertions, 202 deletions
diff --git a/man/bolt-dependencies.7 b/man/bolt-dependencies.7 deleted file mode 100644 index 4188fcb..0000000 --- a/man/bolt-dependencies.7 +++ /dev/null @@ -1,121 +0,0 @@ -.Dd February 12, 2026 -.Dt BOLT-DEPENDENCIES 7 -.Os -.Sh NAME -.Nm bolt-dependencies -.Nd migration dependency system -.Sh DESCRIPTION -Migration dependencies solve a fundamental problem in collaborative database -development: ensuring migrations run in the correct order regardless of when -they were created or merged. -.Sh THE PROBLEM -.Ss Sequential Versions -Developer A creates migration -.Li 002 -for feature X on branch A. Developer B creates migration -.Li 002 -for feature Y on branch B. When branches merge, there is a filename conflict. -.Ss Timestamp Versions -Developer A creates migration -.Li 20251013214743 -on branch A. Developer B creates migration -.Li 20251013214799 -on branch B. Developer B merges first. Developer A merges second. -.Pp -In this environment, both migrations apply successfully. However, when a -fresh database is set up (staging, production, new developer), migrations -run in timestamp order: A's migration runs first, then B's. This is the -opposite order from the original development environment. If B's migration -depends on A's changes, the fresh setup fails. -.Sh THE SOLUTION -Instead of relying on version numbers, migrations explicitly declare which -other migrations they depend on using the -.Cm -- depends: -directive: -.Bd -literal -offset indent --- depends: 20240316145038 --- migrate:up -CREATE TABLE posts ( - user_id INTEGER REFERENCES users(id) -); -.Ed -.Pp -This creates a dependency graph where Bolt determines execution order based -on what migrations need to run before others, not when they were created. -.Sh AUTOMATIC POPULATION -When you create a new migration with -.Xr bolt-new 1 , -Bolt automatically populates the -.Cm -- depends: -directive with current -.Dq leaf -migrations (migrations that no other migration depends on). -.Pp -This means: -.Bl -bullet -offset Ds -compact -.It -The first migration has no dependencies. -.It -The second migration depends on the first. -.It -Migrations created in parallel branches will both be listed as dependencies -in subsequent migrations after merging. -.El -.Sh EXECUTION ORDER -Bolt uses topological sorting to determine execution order: -.Bl -enum -offset Ds -compact -.It -Migrations with no dependencies run first. -.It -Once a migration completes, migrations depending only on completed -migrations become eligible. -.It -When multiple migrations are eligible, version number is used as a -tiebreaker for deterministic ordering. -.El -.Sh VALIDATION -Bolt validates the dependency graph before execution: -.Bl -tag -width Ds -.It Before applying -Verifies all dependencies exist and have been applied. This step detects -any circular dependencies. -.It Before reverting -Ensures no other applied migrations depend on the migration being reverted. -.El -.Sh EXAMPLES -No dependencies (root migration): -.Bd -literal -offset indent --- migrate:up -CREATE TABLE users (id SERIAL PRIMARY KEY); - --- migrate:down -DROP TABLE users; -.Ed -.Pp -Single dependency: -.Bd -literal -offset indent --- depends: 20240316145038 --- migrate:up -CREATE TABLE posts (user_id INTEGER REFERENCES users(id)); - --- migrate:down -DROP TABLE posts; -.Ed -.Pp -Multiple dependencies: -.Bd -literal -offset indent --- depends: 20240316145038, 20240317120000 --- migrate:up -CREATE TABLE comments ( - post_id INTEGER REFERENCES posts(id), - user_id INTEGER REFERENCES users(id) -); - --- migrate:down -DROP TABLE comments; -.Ed -.Sh SEE ALSO -.Xr bolt 1 , -.Xr bolt-new 1 , -.Xr bolt-migration 5 , -.Xr bolt-execution 7 diff --git a/man/bolt-down.1 b/man/bolt-down.1 index 5a331d4..18be02c 100644 --- a/man/bolt-down.1 +++ b/man/bolt-down.1 @@ -11,7 +11,7 @@ .Sh DESCRIPTION .Nm reverts applied migrations from the database. Migrations are reverted in -reverse dependency order. +reverse version order, newest first. .Pp By default, all applied migrations are reverted. Use the .Fl v diff --git a/man/bolt-execution.7 b/man/bolt-execution.7 index 75494ac..5e5d64c 100644 --- a/man/bolt-execution.7 +++ b/man/bolt-execution.7 @@ -61,13 +61,13 @@ Bolt scans the migrations directory for files. .It .Sy Parsing : -Each file is parsed to extract the version, message, and dependencies. +Each file name is parsed to extract the version and message. .It .Sy Comparison : Bolt queries the tracking table to find unapplied migrations. .It .Sy Ordering : -Pending migrations are ordered by their dependencies. +Pending migrations are ordered by version, oldest first. .It .Sy Execution : For each pending migration: @@ -77,8 +77,6 @@ The .Cm -- migrate:up section is extracted. .It -All dependencies are verified to be applied. -.It A transaction is started (unless disabled). .It The SQL is executed. @@ -106,7 +104,7 @@ Bolt queries the tracking table for applied migrations. Applied versions are matched against local files. .It .Sy Ordering : -Applied migrations are ordered in reverse dependency order. +Applied migrations are ordered by version, newest first. .It .Sy Execution : For the target migration(s): @@ -116,8 +114,6 @@ The .Cm -- migrate:down section is extracted. .It -Bolt verifies no other applied migrations depend on this one. -.It A transaction is started (unless disabled). .It The SQL is executed. @@ -140,5 +136,4 @@ Migration files should be committed to version control and not deleted. .Xr bolt 1 , .Xr bolt-down 1 , .Xr bolt-up 1 , -.Xr bolt-migration 5 , -.Xr bolt-dependencies 7 +.Xr bolt-migration 5 diff --git a/man/bolt-migration.5 b/man/bolt-migration.5 index dd5080e..92728e8 100644 --- a/man/bolt-migration.5 +++ b/man/bolt-migration.5 @@ -26,9 +26,6 @@ for configuration details. Migration files use comment directives to separate sections. All directives are case-insensitive. .Bl -tag -width Ds -.It Cm -- depends: Ar version1, version2, ... -Declares dependencies on other migrations. Dependencies determine execution -order. Multiple versions are separated by commas. .It Cm -- migrate:up Op Ar options Marks the beginning of the upgrade section. All SQL statements following this directive until the next directive or end of file are executed when @@ -53,7 +50,7 @@ inside a transaction, such as in PostgreSQL. .El .Sh EXAMPLES -A basic migration with no dependencies: +A basic migration: .Bd -literal -offset indent -- migrate:up CREATE TABLE users ( @@ -65,36 +62,8 @@ CREATE TABLE users ( DROP TABLE users; .Ed .Pp -A migration with a single dependency: -.Bd -literal -offset indent --- depends: 20240316145038 --- migrate:up -CREATE TABLE posts ( - id SERIAL PRIMARY KEY, - user_id INTEGER NOT NULL REFERENCES users(id) -); - --- migrate:down -DROP TABLE posts; -.Ed -.Pp -A migration with multiple dependencies: -.Bd -literal -offset indent --- 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; -.Ed -.Pp A non-transactional migration: .Bd -literal -offset indent --- depends: 20240316145038 -- migrate:up transaction:false CREATE INDEX CONCURRENTLY idx_users_email ON users(email); @@ -105,5 +74,4 @@ DROP INDEX CONCURRENTLY idx_users_email; .Xr bolt 1 , .Xr bolt-new 1 , .Xr bolt.toml 5 , -.Xr bolt-dependencies 7 , .Xr bolt-execution 7 diff --git a/man/bolt-new.1 b/man/bolt-new.1 index c9662a5..4e83be0 100644 --- a/man/bolt-new.1 +++ b/man/bolt-new.1 @@ -15,15 +15,6 @@ creates a new database migration file in the migrations directory. The migration file is named using the configured version style (timestamp or sequential) followed by the message. For example: .Pa 20240316145038_create_users_table.sql . -.Pp -When other migrations exist, -.Nm -automatically populates the -.Ql -- depends: -directive with the current leaf migrations (migrations that no other -migration depends on). See -.Xr bolt-dependencies 7 -for details on how dependencies work. .Sh OPTIONS .Bl -tag -width Ds .It Fl m Ar message , Fl -message Ar message @@ -41,5 +32,4 @@ Create a migration with the default message: .Dl $ bolt new .Sh SEE ALSO .Xr bolt 1 , -.Xr bolt-migration 5 , -.Xr bolt-dependencies 7 +.Xr bolt-migration 5 diff --git a/man/bolt-status.1 b/man/bolt-status.1 index 10a60bc..e07c404 100644 --- a/man/bolt-status.1 +++ b/man/bolt-status.1 @@ -11,8 +11,7 @@ displays all discovered migrations and indicates which ones have been applied to the database. .Pp -Migrations are shown in the order they would be executed, based on their -dependency relationships. +Migrations are shown in the order they would be executed, by version. The output includes: .Bl -bullet -offset Ds -compact .It diff --git a/man/bolt-tutorial.7 b/man/bolt-tutorial.7 index 83933aa..0a137a0 100644 --- a/man/bolt-tutorial.7 +++ b/man/bolt-tutorial.7 @@ -75,27 +75,7 @@ Revert the most recent migration: .Pp Revert to a specific version: .Dl $ bolt down -v 20240316145038 -.Sh WORKING WITH DEPENDENCIES -When you create a second migration, Bolt automatically adds a dependency -on existing migrations: -.Bd -literal -offset indent --- depends: 20240316145038 --- migrate:up -CREATE TABLE posts ( - id SERIAL PRIMARY KEY, - user_id INTEGER NOT NULL REFERENCES users(id), - title VARCHAR(255) NOT NULL -); - --- migrate:down -DROP TABLE posts; -.Ed -.Pp -Dependencies ensure migrations run in the correct order. See -.Xr bolt-dependencies 7 -for details. .Sh SEE ALSO .Xr bolt 1 , .Xr bolt.toml 5 , -.Xr bolt-migration 5 , -.Xr bolt-dependencies 7 +.Xr bolt-migration 5 diff --git a/man/bolt-up.1 b/man/bolt-up.1 index c8729b4..19b41e9 100644 --- a/man/bolt-up.1 +++ b/man/bolt-up.1 @@ -11,9 +11,7 @@ .Sh DESCRIPTION .Nm applies pending migrations to the database. Migrations are executed in -dependency order as determined by the -.Ql -- depends: -directives in each migration file. +version order, oldest first. .Pp By default, all pending migrations are applied. Use the .Fl v @@ -55,7 +55,6 @@ exits 0 on success, and >0 if an error occurs. .Xr bolt-migration 5 , .Xr bolt.toml 5 , .Xr bolt-databases 7 , -.Xr bolt-dependencies 7 , .Xr bolt-execution 7 , .Xr bolt-tutorial 7 .Sh AUTHOR |