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, 0 insertions, 121 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