aboutsummaryrefslogtreecommitdiffstats
path: root/man/bolt-dependencies.7
diff options
context:
space:
mode:
Diffstat (limited to 'man/bolt-dependencies.7')
-rw-r--r--man/bolt-dependencies.7121
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