aboutsummaryrefslogtreecommitdiffstats
path: root/man/bolt-migration.5
diff options
context:
space:
mode:
Diffstat (limited to 'man/bolt-migration.5')
-rw-r--r--man/bolt-migration.5109
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