.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 either a timestamp (e.g., .Li 20240316145038 ) or sequential number (e.g., .Li 001 ) depending on the configured version style. See .Xr bolt.toml 5 for configuration details. .Sh DIRECTIVES 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 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 with no dependencies: .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 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); -- 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-dependencies 7 , .Xr bolt-execution 7