aboutsummaryrefslogtreecommitdiffstats
path: root/man
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2026-11-13 21:43:11 -0800
committerEugene Triguba <hello@eugenetriguba.com>2026-11-13 21:43:11 -0800
commit28dd0bfc1373746b8c056a211f068da71fdc80b2 (patch)
tree9c04a08501bc5abe7413263f60eaa55400dd162f /man
parentRelease v0.13.1 (diff)
downloadcli-28dd0bfc1373746b8c056a211f068da71fdc80b2.zip
Remove migration dependencies
Diffstat (limited to 'man')
-rw-r--r--man/bolt-dependencies.7121
-rw-r--r--man/bolt-down.12
-rw-r--r--man/bolt-execution.713
-rw-r--r--man/bolt-migration.534
-rw-r--r--man/bolt-new.112
-rw-r--r--man/bolt-status.13
-rw-r--r--man/bolt-tutorial.722
-rw-r--r--man/bolt-up.14
-rw-r--r--man/bolt.11
9 files changed, 10 insertions, 202 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
diff --git a/man/bolt-down.1 b/man/bolt-down.1
index 5a331d4..18be02c 100644
--- a/man/bolt-down.1
+++ b/man/bolt-down.1
@@ -11,7 +11,7 @@
.Sh DESCRIPTION
.Nm
reverts applied migrations from the database. Migrations are reverted in
-reverse dependency order.
+reverse version order, newest first.
.Pp
By default, all applied migrations are reverted. Use the
.Fl v
diff --git a/man/bolt-execution.7 b/man/bolt-execution.7
index 75494ac..5e5d64c 100644
--- a/man/bolt-execution.7
+++ b/man/bolt-execution.7
@@ -61,13 +61,13 @@ Bolt scans the migrations directory for
files.
.It
.Sy Parsing :
-Each file is parsed to extract the version, message, and dependencies.
+Each file name is parsed to extract the version and message.
.It
.Sy Comparison :
Bolt queries the tracking table to find unapplied migrations.
.It
.Sy Ordering :
-Pending migrations are ordered by their dependencies.
+Pending migrations are ordered by version, oldest first.
.It
.Sy Execution :
For each pending migration:
@@ -77,8 +77,6 @@ The
.Cm -- migrate:up
section is extracted.
.It
-All dependencies are verified to be applied.
-.It
A transaction is started (unless disabled).
.It
The SQL is executed.
@@ -106,7 +104,7 @@ Bolt queries the tracking table for applied migrations.
Applied versions are matched against local files.
.It
.Sy Ordering :
-Applied migrations are ordered in reverse dependency order.
+Applied migrations are ordered by version, newest first.
.It
.Sy Execution :
For the target migration(s):
@@ -116,8 +114,6 @@ The
.Cm -- migrate:down
section is extracted.
.It
-Bolt verifies no other applied migrations depend on this one.
-.It
A transaction is started (unless disabled).
.It
The SQL is executed.
@@ -140,5 +136,4 @@ Migration files should be committed to version control and not deleted.
.Xr bolt 1 ,
.Xr bolt-down 1 ,
.Xr bolt-up 1 ,
-.Xr bolt-migration 5 ,
-.Xr bolt-dependencies 7
+.Xr bolt-migration 5
diff --git a/man/bolt-migration.5 b/man/bolt-migration.5
index dd5080e..92728e8 100644
--- a/man/bolt-migration.5
+++ b/man/bolt-migration.5
@@ -26,9 +26,6 @@ for configuration details.
Migration files use comment directives to separate sections. All directives are
case-insensitive.
.Bl -tag -width Ds
-.It Cm -- depends: Ar version1, version2, ...
-Declares dependencies on other migrations. Dependencies determine execution
-order. Multiple versions are separated by commas.
.It Cm -- migrate:up Op Ar options
Marks the beginning of the upgrade section. All SQL statements following
this directive until the next directive or end of file are executed when
@@ -53,7 +50,7 @@ inside a transaction, such as
in PostgreSQL.
.El
.Sh EXAMPLES
-A basic migration with no dependencies:
+A basic migration:
.Bd -literal -offset indent
-- migrate:up
CREATE TABLE users (
@@ -65,36 +62,8 @@ CREATE TABLE users (
DROP TABLE users;
.Ed
.Pp
-A migration with a single dependency:
-.Bd -literal -offset indent
--- depends: 20240316145038
--- migrate:up
-CREATE TABLE posts (
- id SERIAL PRIMARY KEY,
- user_id INTEGER NOT NULL REFERENCES users(id)
-);
-
--- migrate:down
-DROP TABLE posts;
-.Ed
-.Pp
-A migration with multiple dependencies:
-.Bd -literal -offset indent
--- depends: 20240316145038, 20240317120000
--- migrate:up
-CREATE TABLE comments (
- id SERIAL PRIMARY KEY,
- post_id INTEGER NOT NULL REFERENCES posts(id),
- user_id INTEGER NOT NULL REFERENCES users(id)
-);
-
--- migrate:down
-DROP TABLE comments;
-.Ed
-.Pp
A non-transactional migration:
.Bd -literal -offset indent
--- depends: 20240316145038
-- migrate:up transaction:false
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
@@ -105,5 +74,4 @@ DROP INDEX CONCURRENTLY idx_users_email;
.Xr bolt 1 ,
.Xr bolt-new 1 ,
.Xr bolt.toml 5 ,
-.Xr bolt-dependencies 7 ,
.Xr bolt-execution 7
diff --git a/man/bolt-new.1 b/man/bolt-new.1
index c9662a5..4e83be0 100644
--- a/man/bolt-new.1
+++ b/man/bolt-new.1
@@ -15,15 +15,6 @@ creates a new database migration file in the migrations directory.
The migration file is named using the configured version style (timestamp
or sequential) followed by the message. For example:
.Pa 20240316145038_create_users_table.sql .
-.Pp
-When other migrations exist,
-.Nm
-automatically populates the
-.Ql -- depends:
-directive with the current leaf migrations (migrations that no other
-migration depends on). See
-.Xr bolt-dependencies 7
-for details on how dependencies work.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl m Ar message , Fl -message Ar message
@@ -41,5 +32,4 @@ Create a migration with the default message:
.Dl $ bolt new
.Sh SEE ALSO
.Xr bolt 1 ,
-.Xr bolt-migration 5 ,
-.Xr bolt-dependencies 7
+.Xr bolt-migration 5
diff --git a/man/bolt-status.1 b/man/bolt-status.1
index 10a60bc..e07c404 100644
--- a/man/bolt-status.1
+++ b/man/bolt-status.1
@@ -11,8 +11,7 @@
displays all discovered migrations and indicates which ones have been applied
to the database.
.Pp
-Migrations are shown in the order they would be executed, based on their
-dependency relationships.
+Migrations are shown in the order they would be executed, by version.
The output includes:
.Bl -bullet -offset Ds -compact
.It
diff --git a/man/bolt-tutorial.7 b/man/bolt-tutorial.7
index 83933aa..0a137a0 100644
--- a/man/bolt-tutorial.7
+++ b/man/bolt-tutorial.7
@@ -75,27 +75,7 @@ Revert the most recent migration:
.Pp
Revert to a specific version:
.Dl $ bolt down -v 20240316145038
-.Sh WORKING WITH DEPENDENCIES
-When you create a second migration, Bolt automatically adds a dependency
-on existing migrations:
-.Bd -literal -offset indent
--- depends: 20240316145038
--- migrate:up
-CREATE TABLE posts (
- id SERIAL PRIMARY KEY,
- user_id INTEGER NOT NULL REFERENCES users(id),
- title VARCHAR(255) NOT NULL
-);
-
--- migrate:down
-DROP TABLE posts;
-.Ed
-.Pp
-Dependencies ensure migrations run in the correct order. See
-.Xr bolt-dependencies 7
-for details.
.Sh SEE ALSO
.Xr bolt 1 ,
.Xr bolt.toml 5 ,
-.Xr bolt-migration 5 ,
-.Xr bolt-dependencies 7
+.Xr bolt-migration 5
diff --git a/man/bolt-up.1 b/man/bolt-up.1
index c8729b4..19b41e9 100644
--- a/man/bolt-up.1
+++ b/man/bolt-up.1
@@ -11,9 +11,7 @@
.Sh DESCRIPTION
.Nm
applies pending migrations to the database. Migrations are executed in
-dependency order as determined by the
-.Ql -- depends:
-directives in each migration file.
+version order, oldest first.
.Pp
By default, all pending migrations are applied. Use the
.Fl v
diff --git a/man/bolt.1 b/man/bolt.1
index 4ab6d64..74d65d9 100644
--- a/man/bolt.1
+++ b/man/bolt.1
@@ -55,7 +55,6 @@ exits 0 on success, and >0 if an error occurs.
.Xr bolt-migration 5 ,
.Xr bolt.toml 5 ,
.Xr bolt-databases 7 ,
-.Xr bolt-dependencies 7 ,
.Xr bolt-execution 7 ,
.Xr bolt-tutorial 7
.Sh AUTHOR