.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