.Dd February 12, 2026 .Dt BOLT-MIGRATION 5 .Os .Sh NAME .Nm bolt-migration .Nd bolt migration script format .Sh DESCRIPTION Migration scripts are SQL files that define database schema changes. Each migration file contains both the upgrade (up) and downgrade (down) SQL statements. .Sh FILE NAMING Migration files are named using the pattern: .Pp .D1 Ar version Ns _ Ns Ar message Ns .sql .Pp Where .Ar version is a sequential number (e.g., .Li 0001 ) . .Xr bolt-new 1 picks the next number automatically. .Pp Each version must be unique. If two migrations exist with the same version, Bolt refuses to run until one of them is renumbered. .Sh DIRECTIVES Migration files use comment directives to separate sections. All directives are case-insensitive. .Bl -tag -width Ds .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 applying the migration. .It Cm -- migrate:down Op Ar options Marks the beginning of the downgrade section. All SQL statements following this directive until the next directive or end of file are executed when reverting the migration. .El .Sh OPTIONS Options can be added to the .Cm -- migrate:up or .Cm -- migrate:down directives: .Bl -tag -width Ds .It Cm transaction:false Execute the migration without a transaction. By default, each migration runs within a transaction. Use this option for statements that cannot run inside a transaction, such as .Li CREATE INDEX CONCURRENTLY in PostgreSQL. .El .Sh EXAMPLES A basic migration: .Bd -literal -offset indent -- migrate:up CREATE TABLE users ( id SERIAL PRIMARY KEY, name VARCHAR(255) NOT NULL ); -- migrate:down DROP TABLE users; .Ed .Pp A non-transactional migration: .Bd -literal -offset indent -- migrate:up transaction:false CREATE INDEX CONCURRENTLY idx_users_email ON users(email); -- migrate:down transaction:false DROP INDEX CONCURRENTLY idx_users_email; .Ed .Sh SEE ALSO .Xr bolt 1 , .Xr bolt-new 1 , .Xr bolt.toml 5 , .Xr bolt-execution 7