diff options
Diffstat (limited to 'man/bolt-dependencies.7')
| -rw-r--r-- | man/bolt-dependencies.7 | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/man/bolt-dependencies.7 b/man/bolt-dependencies.7 new file mode 100644 index 0000000..4188fcb --- /dev/null +++ b/man/bolt-dependencies.7 @@ -0,0 +1,121 @@ +.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 |