diff options
Diffstat (limited to 'man/bolt-dependencies.7')
| -rw-r--r-- | man/bolt-dependencies.7 | 121 |
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 |