.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 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 version, oldest first. .It .Sy Execution : For each pending migration: .Bl -bullet -offset Ds -compact .It The .Cm -- migrate:up section is extracted. .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 by version, newest first. .It .Sy Execution : For the target migration(s): .Bl -bullet -offset Ds -compact .It The .Cm -- migrate:down section is extracted. .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