aboutsummaryrefslogtreecommitdiffstats
path: root/man/bolt-execution.7
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2026-02-12 19:14:17 -0500
committerEugene Triguba <hello@eugenetriguba.com>2026-02-12 19:14:17 -0500
commit449f74ded67b49fb3066d6d107fa6de9dba0093c (patch)
treed18017e8e318541781d5cf1cb3e161d3c2ee0be8 /man/bolt-execution.7
parentRelease v0.12.1 (diff)
downloadcli-449f74ded67b49fb3066d6d107fa6de9dba0093c.zip
Replace HTML docs with man pages that ship with bolt
Diffstat (limited to 'man/bolt-execution.7')
-rw-r--r--man/bolt-execution.7144
1 files changed, 144 insertions, 0 deletions
diff --git a/man/bolt-execution.7 b/man/bolt-execution.7
new file mode 100644
index 0000000..75494ac
--- /dev/null
+++ b/man/bolt-execution.7
@@ -0,0 +1,144 @@
+.Dd February 12, 2026
+.Dt BOLT-EXECUTION 7
+.Os
+.Sh NAME
+.Nm bolt-execution
+.Nd how migrations are executed
+.Sh DESCRIPTION
+This document explains how
+.Xr bolt 1
+executes migration scripts, including transaction behavior, the apply
+process, and the revert process.
+.Sh TRANSACTION BEHAVIOR
+By default, each migration runs within a database transaction:
+.Bl -enum -offset Ds
+.It
+Bolt opens a database connection.
+.It
+Begins a transaction.
+.It
+Executes the SQL statements.
+.It
+If successful, commits the transaction and records the migration as applied.
+.It
+If an error occurs, rolls back the transaction and exits with an error.
+.El
+.Ss Database Considerations
+Some databases auto-commit certain DDL statements even within a transaction.
+MySQL, for example, auto-commits statements like
+.Li CREATE TABLE .
+This means if a migration fails partway through, some changes may have
+already been committed.
+.Ss Disabling Transactions
+For operations that cannot run within a transaction (like
+.Li CREATE INDEX CONCURRENTLY
+in PostgreSQL), use the
+.Cm transaction:false
+option:
+.Bd -literal -offset indent
+-- migrate:up transaction:false
+CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
+.Ed
+.Sh TRACKING TABLE
+Bolt tracks applied migrations in a database table (default:
+.Li bolt_migrations ) .
+The table has a single column:
+.Bl -tag -width Ds
+.It Li version
+The version identifier of each applied migration.
+.El
+.Pp
+The migration message is not stored; it exists only in the filename for
+human readability.
+.Sh APPLYING MIGRATIONS
+When you run
+.Xr bolt-up 1 :
+.Bl -enum -offset Ds
+.It
+.Sy Discovery :
+Bolt scans the migrations directory for
+.Pa .sql
+files.
+.It
+.Sy Parsing :
+Each file is parsed to extract the version, message, and dependencies.
+.It
+.Sy Comparison :
+Bolt queries the tracking table to find unapplied migrations.
+.It
+.Sy Ordering :
+Pending migrations are ordered by their dependencies.
+.It
+.Sy Execution :
+For each pending migration:
+.Bl -bullet -offset Ds -compact
+.It
+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.
+.It
+The version is inserted into the tracking table.
+.It
+The transaction is committed.
+.El
+.It
+.Sy Reporting :
+Success or failure is reported. If any migration fails, the process halts.
+.El
+.Sh REVERTING MIGRATIONS
+When you run
+.Xr bolt-down 1 :
+.Bl -enum -offset Ds
+.It
+.Sy Discovery :
+Bolt scans the migrations directory.
+.It
+.Sy Query :
+Bolt queries the tracking table for applied migrations.
+.It
+.Sy Matching :
+Applied versions are matched against local files.
+.It
+.Sy Ordering :
+Applied migrations are ordered in reverse dependency order.
+.It
+.Sy Execution :
+For the target migration(s):
+.Bl -bullet -offset Ds -compact
+.It
+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.
+.It
+The version is removed from the tracking table.
+.It
+The transaction is committed.
+.El
+.It
+.Sy Reporting :
+Success or failure is reported. If any revert fails, the process halts.
+.El
+.Sh MISSING FILES
+If a migration has been applied but the file no longer exists locally, Bolt
+cannot revert it automatically. You must either restore the file or manually
+revert the changes and remove the version from the tracking table.
+.Pp
+Migration files should be committed to version control and not deleted.
+.Sh SEE ALSO
+.Xr bolt 1 ,
+.Xr bolt-down 1 ,
+.Xr bolt-up 1 ,
+.Xr bolt-migration 5 ,
+.Xr bolt-dependencies 7