diff options
Diffstat (limited to 'man/bolt-migration.5')
| -rw-r--r-- | man/bolt-migration.5 | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/man/bolt-migration.5 b/man/bolt-migration.5 new file mode 100644 index 0000000..dd5080e --- /dev/null +++ b/man/bolt-migration.5 @@ -0,0 +1,109 @@ +.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 |