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