aboutsummaryrefslogtreecommitdiffstats
path: root/man
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2026-02-12 19:14:17 -0500
committerEugene Triguba <hello@eugenetriguba.com>2026-02-12 19:14:17 -0500
commit449f74ded67b49fb3066d6d107fa6de9dba0093c (patch)
treed18017e8e318541781d5cf1cb3e161d3c2ee0be8 /man
parentRelease v0.12.1 (diff)
downloadcli-449f74ded67b49fb3066d6d107fa6de9dba0093c.zip
Replace HTML docs with man pages that ship with bolt
Diffstat (limited to 'man')
-rw-r--r--man/bolt-databases.7145
-rw-r--r--man/bolt-dependencies.7121
-rw-r--r--man/bolt-down.142
-rw-r--r--man/bolt-execution.7144
-rw-r--r--man/bolt-help.127
-rw-r--r--man/bolt-migration.5109
-rw-r--r--man/bolt-new.145
-rw-r--r--man/bolt-status.140
-rw-r--r--man/bolt-tutorial.7101
-rw-r--r--man/bolt-up.145
-rw-r--r--man/bolt-version.117
-rw-r--r--man/bolt.170
-rw-r--r--man/bolt.toml.5106
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