diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/bolt-databases.7 | 145 | ||||
| -rw-r--r-- | man/bolt-dependencies.7 | 121 | ||||
| -rw-r--r-- | man/bolt-down.1 | 42 | ||||
| -rw-r--r-- | man/bolt-execution.7 | 144 | ||||
| -rw-r--r-- | man/bolt-help.1 | 27 | ||||
| -rw-r--r-- | man/bolt-migration.5 | 109 | ||||
| -rw-r--r-- | man/bolt-new.1 | 45 | ||||
| -rw-r--r-- | man/bolt-status.1 | 40 | ||||
| -rw-r--r-- | man/bolt-tutorial.7 | 101 | ||||
| -rw-r--r-- | man/bolt-up.1 | 45 | ||||
| -rw-r--r-- | man/bolt-version.1 | 17 | ||||
| -rw-r--r-- | man/bolt.1 | 70 | ||||
| -rw-r--r-- | man/bolt.toml.5 | 106 |
13 files changed, 1012 insertions, 0 deletions
diff --git a/man/bolt-databases.7 b/man/bolt-databases.7 new file mode 100644 index 0000000..5526bba --- /dev/null +++ b/man/bolt-databases.7 @@ -0,0 +1,145 @@ +.Dd February 12, 2026 +.Dt BOLT-DATABASES 7 +.Os +.Sh NAME +.Nm bolt-databases +.Nd database drivers and connection strings +.Sh DESCRIPTION +.Xr bolt 1 +uses Data Source Name (DSN) strings for database connections. A DSN is a string +that contains all the information needed to connect to a database. It includes +the database type, connection parameters, and optional driver-specific options. +.Pp +This document describes the supported databases and their connection string formats. +.Sh COMPATIBILITY +.Bl -tag -width 2Ds +.It PostgreSQL +Version 13 and later. +.It MySQL +Version 5.7 and later. +.It SQL Server +Version 2017 and later. +.It SQLite +Latest version. +.Pp +For SQLite, we only explicitly run our test suite against the latest version of +SQLite, so I find it hard to claim support for anything more. That said, SQLite +is an incredibly stable piece of software, and I'd find it unlikely any recent +version would have any issue. If you have an issue on any version, please file +a bug report. +.El +.Sh POSTGRESQL +.Ss Driver: +.Lk https://github.com/jackc/pgx pgx +.Pp +The connection string follows the libpq format. For a complete list of supported +options, see the PostgreSQL libpq documentation: +.Lk https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS +.Pp +.Ss Format: +.Pp +postgresql://username:password@hostname:port/database?options +.Pp +The keyword=value format is also supported: +.Bd -literal -offset indent -compact +host=hostname port=5432 dbname=database user=username password=password +.Ed +.Pp +.Ss Examples: +.Bl -ohang +.It Sy Basic connection +.Li postgresql://user:password@localhost:5432/mydb +.It Sy With SSL disabled +.Li postgresql://user:password@localhost:5432/mydb?sslmode=disable +.It Sy With multiple options +.Li postgresql://user:password@localhost:5432/mydb?sslmode=require&connect_timeout=10&application_name=bolt +.It Sy Using Unix socket +.Li postgresql://user:password@/mydb?host=/var/run/postgresql +.El +.Sh MYSQL +.Ss Driver: +.Lk https://github.com/go-sql-driver/mysql go-sql-driver/mysql +.Pp +For a complete list of supported options, see the driver DSN documentation: +.Lk https://github.com/go-sql-driver/mysql#dsn-data-source-name +.Pp +.Ss Format: +.Pp +username:password@protocol(address)/database?options +.Pp +.Ss Examples: +.Bl -ohang +.It Sy Basic connection +.Li user:password@tcp(localhost:3306)/mydb +.It Sy With parse time and charset +.Li user:password@tcp(localhost:3306)/mydb?parseTime=true&charset=utf8mb4 +.It Sy With connection timeout and TLS +.Li user:password@tcp(localhost:3306)/mydb?timeout=10s&tls=true +.It Sy Using Unix socket +.Li user:password@unix(/tmp/mysql.sock)/mydb +.El +.Sh SQL SERVER +.Ss Driver: +.Lk https://github.com/microsoft/go-mssqldb go-mssqldb +.Pp +For a complete list of supported parameters, see the driver documentation: +.Lk https://github.com/microsoft/go-mssqldb#connection-parameters-and-dsn +.Pp +.Ss Format: +.Pp +sqlserver://username:password@hostname:port?database=database&options +.Pp +.Ss Examples: +.Bl -ohang +.It Sy Basic connection +.Li sqlserver://user:password@localhost:1433?database=mydb +.It Sy With encryption and timeout +.Li sqlserver://user:password@localhost:1433?database=mydb&encrypt=disable&connection+timeout=30 +.It Sy With instance name +.Li sqlserver://user:password@localhost/SQL_EXPRESS?database=mydb +.It Sy Windows authentication +.Li sqlserver://localhost:1433?database=mydb&trusted_connection=yes +.El +.Sh SQLITE +.Ss Driver: +.Lk https://github.com/mattn/go-sqlite3 go-sqlite3 +.Pp +For a complete list of supported parameters, see the driver documentation: +.Lk https://github.com/mattn/go-sqlite3#connection-string +.Pp +.Ss Format: +.Pp +/path/to/database.db?options +.Pp +.Ss Examples: +.Bl -ohang +.It Sy File-based database +.Li /path/to/mydatabase.db +.It Sy In-memory database +.Li :memory: +.It Sy Read-only mode +.Li /path/to/mydatabase.db?mode=ro +.It Sy With foreign keys enabled +.Li /path/to/mydatabase.db?_foreign_keys=on +.El +.Sh CONFIGURATION +Set the DSN and driver in +.Pa bolt.toml : +.Bd -literal -offset indent +[database] +dsn = "postgresql://user:password@localhost:5432/mydb" +driver = "postgresql" +.Ed +.Pp +Or via environment variables: +.Bd -literal -offset indent +export BOLT_DB_DSN="postgresql://user:password@localhost:5432/mydb" +export BOLT_DB_DRIVER="postgresql" +.Ed +.Sh SEE ALSO +.Xr bolt 1 , +.Xr bolt.toml 5 , +.Xr psql 1 , +.Xr mysql 1 , +.Xr sqlite3 1 + diff --git a/man/bolt-dependencies.7 b/man/bolt-dependencies.7 new file mode 100644 index 0000000..4188fcb --- /dev/null +++ b/man/bolt-dependencies.7 @@ -0,0 +1,121 @@ +.Dd February 12, 2026 +.Dt BOLT-DEPENDENCIES 7 +.Os +.Sh NAME +.Nm bolt-dependencies +.Nd migration dependency system +.Sh DESCRIPTION +Migration dependencies solve a fundamental problem in collaborative database +development: ensuring migrations run in the correct order regardless of when +they were created or merged. +.Sh THE PROBLEM +.Ss Sequential Versions +Developer A creates migration +.Li 002 +for feature X on branch A. Developer B creates migration +.Li 002 +for feature Y on branch B. When branches merge, there is a filename conflict. +.Ss Timestamp Versions +Developer A creates migration +.Li 20251013214743 +on branch A. Developer B creates migration +.Li 20251013214799 +on branch B. Developer B merges first. Developer A merges second. +.Pp +In this environment, both migrations apply successfully. However, when a +fresh database is set up (staging, production, new developer), migrations +run in timestamp order: A's migration runs first, then B's. This is the +opposite order from the original development environment. If B's migration +depends on A's changes, the fresh setup fails. +.Sh THE SOLUTION +Instead of relying on version numbers, migrations explicitly declare which +other migrations they depend on using the +.Cm -- depends: +directive: +.Bd -literal -offset indent +-- depends: 20240316145038 +-- migrate:up +CREATE TABLE posts ( + user_id INTEGER REFERENCES users(id) +); +.Ed +.Pp +This creates a dependency graph where Bolt determines execution order based +on what migrations need to run before others, not when they were created. +.Sh AUTOMATIC POPULATION +When you create a new migration with +.Xr bolt-new 1 , +Bolt automatically populates the +.Cm -- depends: +directive with current +.Dq leaf +migrations (migrations that no other migration depends on). +.Pp +This means: +.Bl -bullet -offset Ds -compact +.It +The first migration has no dependencies. +.It +The second migration depends on the first. +.It +Migrations created in parallel branches will both be listed as dependencies +in subsequent migrations after merging. +.El +.Sh EXECUTION ORDER +Bolt uses topological sorting to determine execution order: +.Bl -enum -offset Ds -compact +.It +Migrations with no dependencies run first. +.It +Once a migration completes, migrations depending only on completed +migrations become eligible. +.It +When multiple migrations are eligible, version number is used as a +tiebreaker for deterministic ordering. +.El +.Sh VALIDATION +Bolt validates the dependency graph before execution: +.Bl -tag -width Ds +.It Before applying +Verifies all dependencies exist and have been applied. This step detects +any circular dependencies. +.It Before reverting +Ensures no other applied migrations depend on the migration being reverted. +.El +.Sh EXAMPLES +No dependencies (root migration): +.Bd -literal -offset indent +-- migrate:up +CREATE TABLE users (id SERIAL PRIMARY KEY); + +-- migrate:down +DROP TABLE users; +.Ed +.Pp +Single dependency: +.Bd -literal -offset indent +-- depends: 20240316145038 +-- migrate:up +CREATE TABLE posts (user_id INTEGER REFERENCES users(id)); + +-- migrate:down +DROP TABLE posts; +.Ed +.Pp +Multiple dependencies: +.Bd -literal -offset indent +-- depends: 20240316145038, 20240317120000 +-- migrate:up +CREATE TABLE comments ( + post_id INTEGER REFERENCES posts(id), + user_id INTEGER REFERENCES users(id) +); + +-- migrate:down +DROP TABLE comments; +.Ed +.Sh SEE ALSO +.Xr bolt 1 , +.Xr bolt-new 1 , +.Xr bolt-migration 5 , +.Xr bolt-execution 7 diff --git a/man/bolt-down.1 b/man/bolt-down.1 new file mode 100644 index 0000000..5a331d4 --- /dev/null +++ b/man/bolt-down.1 @@ -0,0 +1,42 @@ +.Dd February 12, 2026 +.Dt BOLT-DOWN 1 +.Os +.Sh NAME +.Nm bolt-down +.Nd revert migrations against the database +.Sh SYNOPSIS +.Nm bolt down +.Op Fl v Ar version +.Op Fl -version Ar version +.Sh DESCRIPTION +.Nm +reverts applied migrations from the database. Migrations are reverted in +reverse dependency order. +.Pp +By default, all applied migrations are reverted. Use the +.Fl v +option to revert migrations down to and including a specific version. +.Pp +Each migration runs within a transaction by default, ensuring that if any +statement fails, the entire revert is rolled back. See +.Xr bolt-execution 7 +for details on transaction behavior. +.Sh OPTIONS +.Bl -tag -width Ds +.It Fl v Ar version , Fl -version Ar version +Revert migrations down to and including the specified version. +.El +.Sh EXIT STATUS +.Nm +exits 0 on success, and >0 if an error occurs. +.Sh EXAMPLES +Revert all applied migrations: +.Dl $ bolt down +.Pp +Revert migrations down to a specific version: +.Dl $ bolt down -v 20240316145038 +.Sh SEE ALSO +.Xr bolt 1 , +.Xr bolt-status 1 , +.Xr bolt-up 1 , +.Xr bolt-execution 7 diff --git a/man/bolt-execution.7 b/man/bolt-execution.7 new file mode 100644 index 0000000..75494ac --- /dev/null +++ b/man/bolt-execution.7 @@ -0,0 +1,144 @@ +.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 is parsed to extract the version, message, and dependencies. +.It +.Sy Comparison : +Bolt queries the tracking table to find unapplied migrations. +.It +.Sy Ordering : +Pending migrations are ordered by their dependencies. +.It +.Sy Execution : +For each pending migration: +.Bl -bullet -offset Ds -compact +.It +The +.Cm -- migrate:up +section is extracted. +.It +All dependencies are verified to be applied. +.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 in reverse dependency order. +.It +.Sy Execution : +For the target migration(s): +.Bl -bullet -offset Ds -compact +.It +The +.Cm -- migrate:down +section is extracted. +.It +Bolt verifies no other applied migrations depend on this one. +.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 , +.Xr bolt-dependencies 7 diff --git a/man/bolt-help.1 b/man/bolt-help.1 new file mode 100644 index 0000000..7881373 --- /dev/null +++ b/man/bolt-help.1 @@ -0,0 +1,27 @@ +.Dd February 12, 2026 +.Dt BOLT-HELP 1 +.Os +.Sh NAME +.Nm bolt-help +.Nd show manual page +.Sh SYNOPSIS +.Nm bolt help +.Op Ar command +.Sh DESCRIPTION +.Nm +opens the manual page for a command. +.Pp +If no command is specified, opens the main +.Xr bolt 1 +page. +.Sh EXIT STATUS +.Nm +exits 0 on success, and >0 if an error occurs. +.Sh EXAMPLES +Show main documentation: +.Dl $ bolt help +.Pp +Show the new command documentation: +.Dl $ bolt help new +.Sh SEE ALSO +.Xr bolt 1 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 diff --git a/man/bolt-new.1 b/man/bolt-new.1 new file mode 100644 index 0000000..c9662a5 --- /dev/null +++ b/man/bolt-new.1 @@ -0,0 +1,45 @@ +.Dd February 12, 2026 +.Dt BOLT-NEW 1 +.Os +.Sh NAME +.Nm bolt-new +.Nd create a new database migration +.Sh SYNOPSIS +.Nm bolt new +.Op Fl m Ar message +.Op Fl -message Ar message +.Sh DESCRIPTION +.Nm +creates a new database migration file in the migrations directory. +.Pp +The migration file is named using the configured version style (timestamp +or sequential) followed by the message. For example: +.Pa 20240316145038_create_users_table.sql . +.Pp +When other migrations exist, +.Nm +automatically populates the +.Ql -- depends: +directive with the current leaf migrations (migrations that no other +migration depends on). See +.Xr bolt-dependencies 7 +for details on how dependencies work. +.Sh OPTIONS +.Bl -tag -width Ds +.It Fl m Ar message , Fl -message Ar message +Message to use for the migration. Default: +.Qq autogenerated . +.El +.Sh EXIT STATUS +.Nm +exits 0 on success, and >0 if an error occurs. +.Sh EXAMPLES +Create a migration with a message: +.Dl $ bolt new -m \(dqcreate users table\(dq +.Pp +Create a migration with the default message: +.Dl $ bolt new +.Sh SEE ALSO +.Xr bolt 1 , +.Xr bolt-migration 5 , +.Xr bolt-dependencies 7 diff --git a/man/bolt-status.1 b/man/bolt-status.1 new file mode 100644 index 0000000..10a60bc --- /dev/null +++ b/man/bolt-status.1 @@ -0,0 +1,40 @@ +.Dd February 12, 2026 +.Dt BOLT-STATUS 1 +.Os +.Sh NAME +.Nm bolt-status +.Nd list migrations and their statuses +.Sh SYNOPSIS +.Nm bolt status +.Sh DESCRIPTION +.Nm +displays all discovered migrations and indicates which ones have been applied +to the database. +.Pp +Migrations are shown in the order they would be executed, based on their +dependency relationships. +The output includes: +.Bl -bullet -offset Ds -compact +.It +Version - The migration version number +.It +Message - The migration description +.It +Applied - An +.Ql X +if the migration has been applied, blank otherwise +.El +.Sh EXIT STATUS +.Nm +exits 0 on success, and >0 if an error occurs. +.Sh EXAMPLES +.Bd -literal -offset indent +$ bolt status +Version Message Applied +20240316145038 create_users_table X +20240317120000 add_email_index +.Ed +.Sh SEE ALSO +.Xr bolt 1 , +.Xr bolt-down 1 , +.Xr bolt-up 1 diff --git a/man/bolt-tutorial.7 b/man/bolt-tutorial.7 new file mode 100644 index 0000000..83933aa --- /dev/null +++ b/man/bolt-tutorial.7 @@ -0,0 +1,101 @@ +.Dd February 12, 2026 +.Dt BOLT-TUTORIAL 7 +.Os +.Sh NAME +.Nm bolt-tutorial +.Nd getting started with bolt +.Sh DESCRIPTION +This tutorial guides you through the basics of using +.Xr bolt 1 +to manage database migrations. +.Sh PREREQUISITES +Before starting, ensure you have: +.Bl -bullet -offset Ds -compact +.It +Bolt installed +.It +A database available (PostgreSQL, MySQL, SQL Server, or SQLite) +.El +.Sh CREATING YOUR FIRST MIGRATION +Create a migration with: +.Dl $ bolt new -m \(dqcreate users table\(dq +.Pp +This creates a +.Pa migrations/ +directory with a file like: +.Dl 20240316145038_create_users_table.sql +.Sh WRITING MIGRATION SCRIPTS +Edit the migration file to add SQL statements: +.Bd -literal -offset indent +-- migrate:up +CREATE TABLE users ( + id SERIAL PRIMARY KEY, + name VARCHAR(255) NOT NULL, + email VARCHAR(255) NOT NULL, + created_at TIMESTAMP NOT NULL DEFAULT NOW() +); + +-- migrate:down +DROP TABLE users; +.Ed +.Pp +The +.Cm -- migrate:up +section runs when applying the migration. +The +.Cm -- migrate:down +section runs when reverting it. +.Sh CONFIGURING BOLT +Create a +.Pa bolt.toml +file: +.Bd -literal -offset indent +[database] +dsn = "postgresql://user:password@localhost:5432/mydb?sslmode=disable" +driver = "postgresql" +.Ed +.Pp +See +.Xr bolt.toml 5 +for all configuration options. +.Sh APPLYING MIGRATIONS +Apply all pending migrations: +.Dl $ bolt up +.Pp +Apply up to a specific version: +.Dl $ bolt up -v 20240316145038 +.Sh CHECKING STATUS +View migration status: +.Dl $ bolt status +.Pp +Output shows version, message, and whether each migration is applied. +.Sh REVERTING MIGRATIONS +Revert the most recent migration: +.Dl $ bolt down +.Pp +Revert to a specific version: +.Dl $ bolt down -v 20240316145038 +.Sh WORKING WITH DEPENDENCIES +When you create a second migration, Bolt automatically adds a dependency +on existing migrations: +.Bd -literal -offset indent +-- depends: 20240316145038 +-- migrate:up +CREATE TABLE posts ( + id SERIAL PRIMARY KEY, + user_id INTEGER NOT NULL REFERENCES users(id), + title VARCHAR(255) NOT NULL +); + +-- migrate:down +DROP TABLE posts; +.Ed +.Pp +Dependencies ensure migrations run in the correct order. See +.Xr bolt-dependencies 7 +for details. +.Sh SEE ALSO +.Xr bolt 1 , +.Xr bolt.toml 5 , +.Xr bolt-migration 5 , +.Xr bolt-dependencies 7 diff --git a/man/bolt-up.1 b/man/bolt-up.1 new file mode 100644 index 0000000..c8729b4 --- /dev/null +++ b/man/bolt-up.1 @@ -0,0 +1,45 @@ +.Dd February 12, 2026 +.Dt BOLT-UP 1 +.Os +.Sh NAME +.Nm bolt-up +.Nd apply migrations against the database +.Sh SYNOPSIS +.Nm bolt up +.Op Fl v Ar version +.Op Fl -version Ar version +.Sh DESCRIPTION +.Nm +applies pending migrations to the database. Migrations are executed in +dependency order as determined by the +.Ql -- depends: +directives in each migration file. +.Pp +By default, all pending migrations are applied. Use the +.Fl v +option to apply migrations up to and including a specific version. +.Pp +Each migration runs within a transaction by default, ensuring that if any +statement fails, the entire migration is rolled back. See +.Xr bolt-execution 7 +for details on transaction behavior. +.Sh OPTIONS +.Bl -tag -width Ds +.It Fl v Ar version , Fl -version Ar version +Apply migrations up to and including the specified version. If not provided, +all pending migrations are applied. +.El +.Sh EXIT STATUS +.Nm +exits 0 on success, and >0 if an error occurs. +.Sh EXAMPLES +Apply all pending migrations: +.Dl $ bolt up +.Pp +Apply migrations up to a specific version: +.Dl $ bolt up -v 20240316145038 +.Sh SEE ALSO +.Xr bolt 1 , +.Xr bolt-down 1 , +.Xr bolt-status 1 , +.Xr bolt-execution 7 diff --git a/man/bolt-version.1 b/man/bolt-version.1 new file mode 100644 index 0000000..4faede8 --- /dev/null +++ b/man/bolt-version.1 @@ -0,0 +1,17 @@ +.Dd February 12, 2026 +.Dt BOLT-VERSION 1 +.Os +.Sh NAME +.Nm bolt-version +.Nd print the version +.Sh SYNOPSIS +.Nm bolt version +.Sh DESCRIPTION +.Nm +prints the version of +.Xr bolt 1 . +.Sh EXIT STATUS +.Nm +exits 0 on success, and >0 if an error occurs. +.Sh SEE ALSO +.Xr bolt 1 diff --git a/man/bolt.1 b/man/bolt.1 new file mode 100644 index 0000000..4ab6d64 --- /dev/null +++ b/man/bolt.1 @@ -0,0 +1,70 @@ +.Dd February 12, 2026 +.Dt BOLT 1 +.Os +.Sh NAME +.Nm bolt +.Nd database migration tool +.Sh SYNOPSIS +.Nm +.Ar command +.Op Ar options +.Sh DESCRIPTION +.Nm +is a command-line tool for database migrations. +.Pp +.Bl -bullet +.It +Schema migrations are written in plain SQL. +.It +Migrations can be versioned sequentially or by creation timestamp. +.It +All migrations run in transactions by default. +.It +Supports up and down migrations and jumping to any particular schema version. +.It +Supports PostgreSQL 13+, MySQL 5.7+, SQL Server 2017+, and SQLite3. +.El +.Sh COMMANDS +.Bl -tag -width Ds +.It Xr bolt-new 1 +Create a new database migration. +.It Xr bolt-up 1 +Apply migrations against the database. +.It Xr bolt-down 1 +Revert migrations against the database. +.It Xr bolt-status 1 +List migrations and their statuses. +.It Xr bolt-version 1 +Print the version. +.It Xr bolt-help 1 +Show the manual for a command. +.El +.Sh FILES +.Bl -tag -width Ds +.It Pa bolt.toml +Configuration file. See +.Xr bolt.toml 5 . +.It Pa migrations/ +Default directory for migration scripts. See +.Xr bolt-migration 5 . +.El +.Sh EXIT STATUS +.Nm +exits 0 on success, and >0 if an error occurs. +.Sh SEE ALSO +.Xr bolt-migration 5 , +.Xr bolt.toml 5 , +.Xr bolt-databases 7 , +.Xr bolt-dependencies 7 , +.Xr bolt-execution 7 , +.Xr bolt-tutorial 7 +.Sh AUTHOR +.Nm +is maintained by +.An Eugene Triguba , +.Mt hello@eugenetriguba.com . +.Pp +Up-to-date sources can be found at +.Lk https://git.sr.ht/~eugenetriguba/bolt +and bugs/patches can be submitted by email to +.Mt ~eugenetriguba/public-inbox@lists.sr.ht . diff --git a/man/bolt.toml.5 b/man/bolt.toml.5 new file mode 100644 index 0000000..15858ff --- /dev/null +++ b/man/bolt.toml.5 @@ -0,0 +1,106 @@ +.Dd February 12, 2026 +.Dt BOLT.TOML 5 +.Os +.Sh NAME +.Nm bolt.toml +.Nd bolt configuration file +.Sh DESCRIPTION +.Nm +is the configuration file for +.Xr bolt 1 . +Bolt searches for this file in the current working directory or any parent +directory until the root of the filesystem. +.Pp +Environment variables take precedence over configuration file settings if +both are set. +.Sh FILE FORMAT +The configuration file uses TOML format with two sections: +.Bl -tag -width Ds +.It Cm [migrations] +Migration-related settings. +.It Cm [database] +Database connection settings. +.El +.Sh MIGRATIONS SECTION +.Bl -tag -width Ds +.It Cm directory_path +The directory where migration scripts are located. Defaults to +.Pa migrations . +This can be a relative path (from the current working directory) or an +absolute path. +.Pp +Environment variable: +.Ev BOLT_MIGRATIONS_DIR_PATH +.It Cm version_style +The migration versioning style. +.Qq timestamp +(default) uses timestamps like +.Li 20240316145038 . +.Qq sequential +uses incrementing integers like +.Li 001 , 002 , 003 . +.Pp +Environment variable: +.Ev BOLT_MIGRATIONS_VERSION_STYLE +.El +.Sh DATABASE SECTION +.Bl -tag -width Ds +.It Cm dsn +The Data Source Name (connection string) for the database. See +.Xr bolt-databases 7 +for format details. +.Pp +Environment variable: +.Ev BOLT_DB_DSN +.It Cm driver +The database driver to use. One of: +.Qq postgresql , +.Qq mysql , +.Qq mssql , +or +.Qq sqlite3 . +.Pp +Environment variable: +.Ev BOLT_DB_DRIVER +.It Cm migrations_table +The name of the table used to track applied migrations. Defaults to +.Qq bolt_migrations . +.Pp +Environment variable: +.Ev BOLT_DB_MIGRATIONS_TABLE +.El +.Sh ENVIRONMENT +All configuration options can be set via environment variables. When both +a configuration file setting and environment variable are present, the +environment variable takes precedence. +.Pp +.Bl -column "BOLT_MIGRATIONS_VERSION_STYLE" "migrations.version_style" -offset indent +.It Sy Environment Variable Ta Sy Configuration Key +.It Ev BOLT_MIGRATIONS_DIR_PATH Ta Cm migrations.directory_path +.It Ev BOLT_MIGRATIONS_VERSION_STYLE Ta Cm migrations.version_style +.It Ev BOLT_DB_DSN Ta Cm database.dsn +.It Ev BOLT_DB_DRIVER Ta Cm database.driver +.It Ev BOLT_DB_MIGRATIONS_TABLE Ta Cm database.migrations_table +.El +.Sh EXAMPLES +A complete configuration file: +.Bd -literal -offset indent +[migrations] +directory_path = "migrations" +version_style = "timestamp" + +[database] +dsn = "postgresql://user:password@localhost:5432/mydb?sslmode=disable" +driver = "postgresql" +migrations_table = "bolt_migrations" +.Ed +.Pp +Using environment variables: +.Bd -literal -offset indent +export BOLT_DB_DSN="postgresql://user:password@localhost:5432/mydb" +export BOLT_DB_DRIVER="postgresql" +export BOLT_MIGRATIONS_DIR_PATH="db/migrations" +.Ed +.Sh SEE ALSO +.Xr bolt 1 , +.Xr bolt-databases 7 |