aboutsummaryrefslogtreecommitdiffstats
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
parentRelease v0.12.1 (diff)
downloadcli-449f74ded67b49fb3066d6d107fa6de9dba0093c.zip
Replace HTML docs with man pages that ship with bolt
-rw-r--r--.builds/docs.yml22
-rw-r--r--.builds/lint.yml2
-rw-r--r--CHANGELOG.md5
-rw-r--r--CONTRIBUTING.md (renamed from docs/contributing.md)2
-rw-r--r--Makefile49
-rw-r--r--README.md114
-rw-r--r--docs/explanation.md357
-rw-r--r--docs/how-to.md169
-rw-r--r--docs/index.md82
-rw-r--r--docs/installation.md39
-rw-r--r--docs/reference.md446
-rw-r--r--docs/requirements-docs.txt3
-rw-r--r--docs/tutorial.md250
-rw-r--r--internal/cli/cli.go2
-rw-r--r--internal/commands/down.go2
-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
-rw-r--r--mkdocs.yml52
-rwxr-xr-xscripts/deploy-docs.sh48
-rwxr-xr-xscripts/is-branch.sh39
-rwxr-xr-xscripts/release.sh26
32 files changed, 1174 insertions, 1547 deletions
diff --git a/.builds/docs.yml b/.builds/docs.yml
deleted file mode 100644
index 047f21b..0000000
--- a/.builds/docs.yml
+++ /dev/null
@@ -1,22 +0,0 @@
-image: alpine/3.22
-packages:
- - python3
- - py3-pip
- - mkdocs
- - mkdocs-material
- - py3-regex
- - hut
-secrets:
- - ac3eecc9-8fb0-4ed4-ae53-0472c093a1f1
-sources:
- - https://git.sr.ht/~eugenetriguba/bolt
-triggers:
- - action: email
- condition: failure
- to: builds@eugenetriguba.com
-tasks:
- - deploy: |
- cd bolt
- if ./scripts/is-branch.sh "main"; then
- ./scripts/deploy-docs.sh
- fi
diff --git a/.builds/lint.yml b/.builds/lint.yml
index 098ae3d..17d6d73 100644
--- a/.builds/lint.yml
+++ b/.builds/lint.yml
@@ -1,4 +1,4 @@
-image: alpine/3.22
+image: alpine/3.23
packages:
- go
- shellcheck
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b289700..0891006 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Changed
+
+- The documentation for `bolt` now ships with it when you install it as man
+ pages. The HTML documentation at `bolt.eugenetriguba.com` has been removed.
+
## [0.12.1] - 2025-12-27
### Fixed
diff --git a/docs/contributing.md b/CONTRIBUTING.md
index 418958f..9a0263e 100644
--- a/docs/contributing.md
+++ b/CONTRIBUTING.md
@@ -16,7 +16,7 @@ accepting contributions.
- All questions, discussions, requests, or patches should be submitted via
email to my [public-inbox mailing list](https://lists.sr.ht/~eugenetriguba/public-inbox).
For patches, use the subject prefix `[PATCH bolt]`. For anything else, please
- make it obvious it is for the bolt project.
+ use a prefix of `[bolt]`.
## Development Setup
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..df60659
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,49 @@
+PREFIX ?= /usr/local
+BINDIR ?= $(PREFIX)/bin
+MANDIR ?= $(PREFIX)/share/man
+
+.PHONY: all build install uninstall clean
+
+all: build
+
+build:
+ go build -o bolt ./cmd/bolt
+
+install: build
+ install -d $(DESTDIR)$(BINDIR)
+ install -m 755 bolt $(DESTDIR)$(BINDIR)/
+ install -d $(DESTDIR)$(MANDIR)/man1
+ install -m 644 man/bolt.1 $(DESTDIR)$(MANDIR)/man1/
+ install -m 644 man/bolt-new.1 $(DESTDIR)$(MANDIR)/man1/
+ install -m 644 man/bolt-up.1 $(DESTDIR)$(MANDIR)/man1/
+ install -m 644 man/bolt-down.1 $(DESTDIR)$(MANDIR)/man1/
+ install -m 644 man/bolt-status.1 $(DESTDIR)$(MANDIR)/man1/
+ install -m 644 man/bolt-version.1 $(DESTDIR)$(MANDIR)/man1/
+ install -m 644 man/bolt-help.1 $(DESTDIR)$(MANDIR)/man1/
+ install -d $(DESTDIR)$(MANDIR)/man5
+ install -m 644 man/bolt.toml.5 $(DESTDIR)$(MANDIR)/man5/
+ install -m 644 man/bolt-migration.5 $(DESTDIR)$(MANDIR)/man5/
+ install -d $(DESTDIR)$(MANDIR)/man7
+ install -m 644 man/bolt-tutorial.7 $(DESTDIR)$(MANDIR)/man7/
+ install -m 644 man/bolt-databases.7 $(DESTDIR)$(MANDIR)/man7/
+ install -m 644 man/bolt-dependencies.7 $(DESTDIR)$(MANDIR)/man7/
+ install -m 644 man/bolt-execution.7 $(DESTDIR)$(MANDIR)/man7/
+
+uninstall:
+ rm -f $(DESTDIR)$(BINDIR)/bolt
+ rm -f $(DESTDIR)$(MANDIR)/man1/bolt.1
+ rm -f $(DESTDIR)$(MANDIR)/man1/bolt-new.1
+ rm -f $(DESTDIR)$(MANDIR)/man1/bolt-up.1
+ rm -f $(DESTDIR)$(MANDIR)/man1/bolt-down.1
+ rm -f $(DESTDIR)$(MANDIR)/man1/bolt-status.1
+ rm -f $(DESTDIR)$(MANDIR)/man1/bolt-version.1
+ rm -f $(DESTDIR)$(MANDIR)/man1/bolt-help.1
+ rm -f $(DESTDIR)$(MANDIR)/man5/bolt.toml.5
+ rm -f $(DESTDIR)$(MANDIR)/man5/bolt-migration.5
+ rm -f $(DESTDIR)$(MANDIR)/man7/bolt-tutorial.7
+ rm -f $(DESTDIR)$(MANDIR)/man7/bolt-databases.7
+ rm -f $(DESTDIR)$(MANDIR)/man7/bolt-dependencies.7
+ rm -f $(DESTDIR)$(MANDIR)/man7/bolt-execution.7
+
+clean:
+ rm -f bolt
diff --git a/README.md b/README.md
index d33c93a..b6644d1 100644
--- a/README.md
+++ b/README.md
@@ -5,22 +5,112 @@
![Version](https://img.shields.io/badge/version-0.12.1-blue)
[![Build Status](https://builds.sr.ht/~eugenetriguba/bolt/commits/main.svg)](https://builds.sr.ht/~eugenetriguba/bolt/commits/main?)
-Bolt is a command-line tool designed to simplify and streamline your
-database migration process.
+Bolt is a command-line tool for database migrations.
+
+## Why Bolt?
+
+Bolt aims to be a simple and reliable tool that can work anywhere you need to
+run database migrations.
+
+- Schema migrations are written in plain SQL.
+- Migrations can be versioned sequentially or by creation timestamp.
+- All migrations run in transactions by default.
+- Supports up and down migrations and jumping to any particular schema version.
+- Supports PostgreSQL, MySQL, SQL Server, and SQLite3.
+
+## What It Looks Like
+
+Migrations are separated by "up" and "down" comments to delineate what runs when
+you apply the migration and what runs when you revert it. Additionally,
+migrations have dependencies which are what determine the execution order.
+
+```sql
+-- depends: 20240316145038
+-- migrate:up
+CREATE TABLE posts (
+ id SERIAL PRIMARY KEY,
+ user_id INTEGER NOT NULL REFERENCES users(id),
+ title VARCHAR(255) NOT NULL,
+ content TEXT NOT NULL,
+ created_at TIMESTAMP NOT NULL DEFAULT NOW()
+);
+
+-- migrate:down
+DROP TABLE posts;
+```
+
+```bash
+$ bolt status
+Version Message Applied
+20240316145038 create_users_table X
+20240317120000 create_posts_table X
+20240318093000 add_email_index
+```
+
+## Installation
+
+### From Source
+
+Clone the repository:
+
+```
+git clone https://git.sr.ht/~eugenetriguba/bolt
+```
+
+Build the binary:
+
+```
+cd bolt
+make
+```
+
+Install the binary and man pages:
+
+```
+sudo make install
+```
+
+### Homebrew
+
+If you're on macOS (or Linux and use Homebrew), you can install Bolt from the tap:
+
+```bash
+brew tap eugenetriguba/bolt https://git.sr.ht/~eugenetriguba/homebrew-bolt
+brew install bolt
+```
## Documentation
-For the full documentation, visit **[bolt.eugenetriguba.com](https://bolt.eugenetriguba.com/)**
+After installation, documentation is available via man pages.
-- [Installation Guide](https://bolt.eugenetriguba.com/installation/)
-- [Tutorial](https://bolt.eugenetriguba.com/tutorial/)
-- [How-To Guides](https://bolt.eugenetriguba.com/how-to/)
-- [Reference](https://bolt.eugenetriguba.com/reference/)
-- [Explanation](https://bolt.eugenetriguba.com/explanation/)
-- [Contributing](https://bolt.eugenetriguba.com/contributing/)
+### Commands
-## License
+| Page | Description |
+|------|-------------|
+| bolt(1) | Main command overview |
+| bolt-new(1) | Create a new migration |
+| bolt-up(1) | Apply migrations |
+| bolt-down(1) | Revert migrations |
+| bolt-status(1) | List migration statuses |
+| bolt-version(1) | Print version |
+| bolt-help(1) | Show manual pages |
+
+### File Formats
+
+| Page | Description |
+|------|-------------|
+| bolt.toml(5) | Configuration file and environment variables |
+| bolt-migration(5) | Migration script format |
-MIT License
+### Concepts
+
+| Page | Description |
+|------|-------------|
+| bolt-tutorial(7) | Getting started tutorial |
+| bolt-databases(7) | Database drivers and DSN formats |
+| bolt-dependencies(7) | Migration dependency system |
+| bolt-execution(7) | How migrations are executed |
+
+## License
-See [LICENSE](./LICENSE) file for details.
+MIT License. See [LICENSE](./LICENSE) for details.
diff --git a/docs/explanation.md b/docs/explanation.md
deleted file mode 100644
index 15eb729..0000000
--- a/docs/explanation.md
+++ /dev/null
@@ -1,357 +0,0 @@
-# Explanation
-
-This section provides deeper explanations of how Bolt works internally and the
-design decisions behind it.
-
-## How Are Migration Scripts Executed?
-
-Bolt executes upgrade and downgrade migration scripts in a transaction by
-default. This ensures that if any errors occur during the execution of a
-migration script, the transaction will be rolled back and the migration will be
-marked as failed. Bolt will then exit with an error code and output the error to
-standard error.
-
-### Transaction Behavior
-
-When you run a migration:
-
-1. Bolt opens a database connection.
-2. Begins a transaction.
-3. Executes the SQL statements in the migration script.
-4. If successful, commits the transaction and records the migration as applied.
-5. If an error occurs, rolls back the transaction and exits with an error.
-
-### Database-Specific Considerations
-
-!!! warning "Auto-commit DDL Statements"
- Some databases, i.e. MySQL, auto-commit certain DDL statements even
- within a transaction. This means that if a migration fails partway through,
- some changes may have already been committed.
-
-### Opting Out of Transactions
-
-For operations that cannot run within a transaction (like `CREATE INDEX
-CONCURRENTLY` in PostgreSQL), you can opt out using the `transaction:false`
-option:
-
-```sql
--- migrate:up transaction:false
-```
-
-## How Does Bolt Know What Migrations Have Been Applied?
-
-Bolt keeps track of which migrations have been applied by creating a tracking
-table in your database (by default named `bolt_migrations`).
-
-### Migrations Tracking Table
-
-The tracking table has a simple structure with a single column:
-
-- `version` - Stores the version identifier of each applied migration.
-
-When you run `bolt status`, Bolt:
-
-1. Reads all migration files from your migrations directory.
-2. Queries the tracking table for applied versions.
-3. Compares the two lists to show you which migrations are pending or applied.
- Any pending migrations will be shown in the order they would be executed.
-
-### Why Not Use Migration Names?
-
-Bolt only uses the version portion of the migration filename (e.g.,
-`20240316145038` from `20240316145038_create_users.sql`) for tracking.
-
-This allows the descriptive message portion to be purely for human readability.
-It is not stored in the database.
-
-## How Are Migrations Applied?
-
-When you run `bolt up`, the following process occurs:
-
-1. **Discovery**: Bolt scans your migrations directory for all `.sql` files.
-2. **Parsing**: Each filename is parsed to extract the version and message, and
- each file is parsed to extract dependencies.
-3. **Comparison**: Bolt queries the tracking table to determine which migrations
- haven't been applied.
-4. **Ordering**: Pending migrations are ordered based on their dependencies to
- ensure each migration runs after its dependencies.
-5. **Execution**: For each pending migration:
-
- - The file is read and parsed to extract the `-- migrate:up` portion.
- - All dependencies are verified to be applied.
- - The transaction is started (unless `transaction:false` is specified)
- - The SQL is executed
- - The version is inserted into the tracking table
- - The transaction is committed
-
-6. **Reporting**: Success or failure is reported for each migration. If any
- migrations fail to be applied, the process halts and no more migrations are
- applied.
-
-### Applying Up to a Specific Version
-
-When you specify a target version with `bolt up -v <version>`, only migrations up
-to and including the target version are considered.
-
-## How Are Migrations Reverted?
-
-When you run `bolt down`, the following process occurs:
-
-1. **Discovery**: Bolt scans your migrations directory for all `.sql` files.
-2. **Query**: Bolt queries the tracking table for applied migrations.
-3. **Matching**: Applied versions are matched against local migration files.
-4. **Ordering**: Applied migrations are ordered in reverse dependency order.
- (migrations that depend on others are reverted first)
-5. **Execution**: For the most recent applied migration (or down to a target
- version):
-
- - The file is read and parsed to extract the `-- migrate:down` portion.
- - Bolt verifies that no other applied migrations depend on this one
- - A transaction is started (unless `transaction:false` is specified)
- - The SQL is executed
- - The version is removed from the tracking table
- - The transaction is committed
-
-5. **Reporting**: Success or failure is reported for each migration. If any
- migrations fail to be reverted, the process halts and no more migrations are
- applied.
-
-### Reverting to a Specific Version
-
-When you specify a target version with `bolt down -v <version>`, all migrations
-down to and including the target version are reverted.
-
-### Missing Migration Files
-
-!!! danger "Missing Migration Files"
- If a migration has been applied (its version is in the tracking table) but
- the migration file no longer exists locally, Bolt cannot revert it
- automatically. You'll need to either:
-
- - Restore the missing migration file.
- - Manually revert the changes and remove the version from the tracking
- table.
-
- Generally, migration files should be committed to version control and not deleted.
-
-## How Do Migration Dependencies Work?
-
-Migration dependencies solve a fundamental problem in collaborative database
-development: how do many developers create migrations on different branches
-without conflicts once merged?
-
-### The Problem with Version-Based Ordering
-
-Traditionally, migration tools order migrations by version number (timestamp or
-sequential).
-
-#### Sequential
-
-- Developer A creates migration `002` for feature X on branch A.
-- Developer B creates migration `002` for feature Y on branch B.
-- When branches merge, there's a filename conflict that one of them will need
- to resolve.
-
-#### Timestamp
-
-- Developer A creates migration `20251013214743` for feature X on branch A.
-- Developer B creates migration `20251013214943` for feature Y on branch B.
-- Developer B merges first and applies their migration successfully.
-- Developer A merges second and applies their migration successfully.
-- Everything works in this environment.
-
-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, even though
- the original environment worked fine.
-
-While timestamp-versioned migrations generally won't run into filename
-conflicts, they don't respect the actual dependencies between migrations
-or the order they were validated in.
-
-### The Dependency Solution
-
-Instead of relying solely on version numbers, migrations explicitly declare
-which other migrations they depend on. This creates a dependency graph where
-Bolt can determine the correct execution order.
-
-The key insight is that execution order should be based on what migrations need
-to run before others, not when they were created.
-
-### Automatic Dependency Population
-
-Managing these migration dependencies is low-friction because Bolt automatically
-populating them on creation. When you create a new migration, Bolt finds all
-"leaf" migrations (migrations that nothing else depends on) and makes your new
-migration depend on them.
-
-This means:
-
-- The first migration in a project has no dependencies.
-- The second migration automatically depends on the first.
-- If developers create migrations in parallel branches, a subsequent migration
- will depend on both when merged.
-
-You'll get a dependency chain by default but can manually edit dependencies for
-more complex scenarios.
-
-### How Execution Order is Determined
-
-Bolt uses topological sorting to determine execution order. Migrations are
-modeled as a directed graph:
-
-- Each migration is a node.
-- Dependencies are edges pointing from a migration to what it depends on.
-- Bolt finds an ordering where every migration runs after its dependencies.
-
-When multiple migrations have all their dependencies satisfied, Bolt uses
-version number as a tiebreaker for deterministic ordering.
-
-### Validation and Safety
-
-Bolt validates the dependency graph before execution:
-
-**Before applying**:
-
-- Verifies that all dependencies exist and have been applied.
-- Detects circular dependencies (A depends on B, B depends on A).
-
-**Before reverting**: Ensures no other applied migrations depend on the
-migration being reverted. This prevents breaking the dependency chain and
-leaving the database in an inconsistent state.
-
-### Why This Matters
-
-Dependencies enable:
-
-- **Parallel development**: Multiple developers can create migrations
- simultaneously without version conflicts.
-- **Flexible merging**: Migrations can be merged in any order as long as
- dependencies are correct.
-- **Explicit ordering**: The dependency graph makes execution order explicit
- and reviewable.
-- **Safer operations**: Bolt prevents invalid apply/revert operations that would
- violate dependencies
-
-## What are Migration Version Styles?
-
-Whenever you create a migration with `bolt new`, it's prefixed with a "version".
-This version is used by Bolt to:
-
-- Uniquely identify each migration.
-- Name the migration file.
-- Track which migrations have been applied.
-
-Bolt supports two version styles.
-
-### Timestamp Versions (Default)
-
-Format: `YYYYMMDDHHMMSS` (e.g., `20240316145038`)
-
-The version represents the timestamp when the migration was created:
-
-- `2024` - Year
-- `03` - Month
-- `16` - Day
-- `14` - Hour (24-hour format)
-- `50` - Minute
-- `38` - Second
-
-### Sequential Versions
-
-Format: Zero-padded integers (e.g., `001`, `002`, `003`)
-
-The version is simply an incrementing counter.
-
-## Can I switch between version styles?
-
-Yes, _if_ you do the work to migrate all the way to one version style or the
-other. There is no automated tooling support for that.
-
-In a mixed state? Kind of. It's not well supported or recommended. Some aspects
-of using Bolt would not work properly if your migration file versions are in a
-mixed state. Some examples:
-
-- If you were using timestamp versions and switched to sequential versions, the
- next migration would simply be the highest timestamp version incremented by 1.
-
-- If you were using sequential versions and switched to timestamp versions, the
- sorting would error out because Bolt wouldn't be able to parse the sequential
- versions as timestamps.
-
-## How is the migration message used?
-
-When you create a migration with `bolt new -m "create users table"`, the
-resulting file is named:
-
-```
-20240316145038_create_users_table.sql
-```
-
-The format is: `<version>_<message>.sql`
-
-The message is purely for human understanding of the migration. It is not used
-by Bolt for any purpose.
-
-### Message Formatting
-
-When you provide a message:
-
-- Spaces are converted to underscores.
-- Extra leading or trailing spaces are trimmed.
-- The message is lowercased.
-
-Example:
-
-```bash
-bolt new -m " add INDEX to users table "
-# Creates: 20240316145038_add_index_to_users_table.sql
-```
-
-## What restrictions are there on the custom migration table?
-
-While you can configure the database table that Bolt uses for tracking applied
-migrations, there are restrictions on the name.
-
-### Naming Restrictions
-
-The migrations table name must contain only alphanumeric characters and
-underscores.
-
-Valid examples:
-
-- `bolt_migrations` (default)
-- `my_custom_migrations`
-- `migrations_v2` -
-- `app_schema_versions`
-
-Invalid examples:
-
-- `my-migrations` (contains hyphen)
-- `my.custom.migrations` (contains multiple dots)
-- `migrations!` (contains special character)
-
-### Schema Qualification
-
-You may specify a schema-qualified table name using a single dot (`.`):
-
-```toml
-[database]
-migrations_table = "myschema.migrations"
-```
-
-**Schema support:**
-
-- **PostgreSQL**: Full support for schemas
-- **SQL Server**: Full support for schemas
-- **MySQL**: Does not support schemas
-- **SQLite**: Does not support schemas
-
-### Existing Table Handling
-
-!!! info
- If you change the `migrations_table` setting after migrations have already
- been applied, Bolt will look for the new table name. This effectively resets
- your migration state unless you manually copy the data from the old table to
- the new one.
diff --git a/docs/how-to.md b/docs/how-to.md
deleted file mode 100644
index 0d5c370..0000000
--- a/docs/how-to.md
+++ /dev/null
@@ -1,169 +0,0 @@
-# How-To Guides
-
-This section contains guides for specific tasks you may want to accomplish with Bolt.
-
-## How to execute a migration script without a transaction
-
-By default, Bolt executes all migrations within a transaction. However, some
-SQL commands cannot be executed within a transaction (for example, certain
-DDL operations in some databases).
-
-To execute a migration without a transaction, add a `transaction:false` option
-to the migration directives:
-
-```sql
--- migrate:up transaction:false
-CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
-
--- migrate:down transaction:false
-DROP INDEX CONCURRENTLY idx_users_email;
-```
-
-!!! note
- The `transaction:false` option can be applied independently to
- `-- migrate:up` and `-- migrate:down`. You can have one run in
- a transaction and the other not, depending on your needs.
-
-## How to make a migration depend on a specific migrations
-
-By default, Bolt automatically manages dependencies when you create a new
-migration. To manually control which migrations must run first, add a
-`-- depends:` directive at the top of the migration file.
-
-Single dependency:
-
-```sql
--- depends: 20240316145038
--- migrate:up
-CREATE TABLE posts (
- id SERIAL PRIMARY KEY,
- user_id INTEGER NOT NULL REFERENCES users(id)
-);
-
--- migrate:down
-DROP TABLE posts;
-```
-
-Multiple dependencies (comma-separated):
-
-```sql
--- 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;
-```
-
-Bolt ensures all listed migrations are applied before this one runs.
-
-## How to determine migration execution order
-
-Use `bolt status` to see migrations in the order they'll be executed:
-
-```bash
-bolt status
-```
-
-Output:
-```
-Version Message Applied
-20240316145038 create_users X
-20240317120000 create_posts X
-20240318093000 add_comments
-```
-
-Migrations are listed in dependency order. Applied migrations show an `X` in
-the Applied column.
-
-## How to jump to a specific migration version
-
-You can apply or revert migrations up to a specific version using the `-version` or `-v` flag.
-
-### Upgrading to a specific version
-
-To upgrade to and including a specific migration version:
-
-```bash
-bolt up -version 20240316145038
-```
-
-This will apply all unapplied migrations up to and including version `20240316145038`.
-
-### Downgrading to a specific version
-
-To downgrade to and including a specific migration version:
-
-```bash
-bolt down -version 20240316145038
-```
-
-This will revert all applied migrations down to and including version `20240316145038`.
-
-## How to use environment variables for configuration
-
-```bash
-export BOLT_DB_DSN="postgresql://user:password@localhost:5432/mydb?sslmode=disable"
-export BOLT_DB_DRIVER="postgresql"
-bolt up
-```
-
-See the [reference](./reference.md#environment-variables) for the complete list
-of environment variables supported.
-
-!!! tip
- Environment variables take precedence over `bolt.toml` settings. You can
- use a mix of both, with environment variables overriding file-based
- configuration when needed.
-
-## How to use a custom migrations table name
-
-By default, Bolt uses a table named `bolt_migrations` to track applied
-migrations. You can customize this table name in your configuration.
-
-### In bolt.toml
-
-```toml
-[database]
-migrations_table = "my_custom_migrations"
-```
-
-### Using environment variables
-
-```bash
-export BOLT_DB_MIGRATIONS_TABLE="my_custom_migrations"
-```
-
-### Using a different schema (PostgreSQL and MSSQL only)
-
-```toml
-[database]
-migrations_table = "myschema.migrations"
-```
-
-## How to use sequential versioning instead of timestamps
-
-By default, Bolt uses timestamp-based versioning for migrations
-(e.g., `20240316145038`). You can switch to sequential versioning
-(e.g., `001`, `002`, `003`) for new projects.
-
-### In bolt.toml
-
-```toml
-[migrations]
-version_style = "sequential"
-```
-
-### Using environment variables
-
-```bash
-export BOLT_MIGRATIONS_VERSION_STYLE="sequential"
-```
-
-!!! danger "Important"
- You shouldn't change version styles once you have existing migrations.
- Mixing timestamp and sequential versions is not well supported.
diff --git a/docs/index.md b/docs/index.md
deleted file mode 100644
index e024c08..0000000
--- a/docs/index.md
+++ /dev/null
@@ -1,82 +0,0 @@
-# Bolt
-
-![Version](https://img.shields.io/badge/version-0.12.1-blue)
-[![Build Status](https://builds.sr.ht/~eugenetriguba/bolt/commits/main.svg)](https://builds.sr.ht/~eugenetriguba/bolt/commits/main?)
-[![GoDoc](https://godoc.org/git.sr.ht/~eugenetriguba/bolt?status.svg)](https://godoc.org/git.sr.ht/~eugenetriguba/bolt)
-[![Go Report Card](https://goreportcard.com/badge/git.sr.ht/~eugenetriguba/bolt)](https://goreportcard.com/report/git.sr.ht/~eugenetriguba/bolt)
-
-Bolt is a command-line tool designed to simplify and streamline your database
-migration process.
-
-It is distributed as a standalone binary, making it easy to run anywhere
-without having to setup any tooling, and it is language independent. It
-doesn't matter what programming language you're using, you can use Bolt
-for any project you have.
-
-## Features
-
-- Schema migrations are written in plain SQL
-- Migrations can be versioned sequentially or by creation timestamp
-- All migrations run in transactions by default
-- Supports up and down migrations and jumping to any particular schema version
-- Supports PostgreSQL, MySQL, SQL Server, and SQLite3
-
-## Quick Start
-
-### Install Bolt
-
-```bash
-go install git.sr.ht/~eugenetriguba/bolt/cmd/bolt@v0.12.1
-```
-
-This will install Bolt to your `$GOBIN` directory. Make sure that `$GOBIN` is in your `$PATH`.
-
-### Create your first migration
-
-```bash
-bolt new -m "create users table"
-```
-
-### Write your migration
-
-Edit the generated SQL file in the `migrations/` directory:
-
-```sql
--- 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(),
- updated_at TIMESTAMP NOT NULL DEFAULT NOW()
-);
-
--- migrate:down
-DROP TABLE users;
-```
-
-### Configure Bolt
-
-Create a `bolt.toml` file:
-
-```toml
-[database]
-dsn = "postgresql://user:password@localhost:5432/mydb?sslmode=disable"
-driver = "postgresql"
-```
-
-### Apply your migration
-
-```bash
-bolt up
-```
-
-## Next Steps
-
-- Read the [installation guide](./installation.md) for all installation options.
-- Follow the [Tutorial](tutorial.md) for a detailed walkthrough.
-- Check out [How-To Guides](how-to.md) for specific tasks.
-- Browse the [Reference](reference.md) for commands and configuration options.
-- Read [Explanations](explanation.md) to understand how Bolt works internally.
-- See [Contributing](contributing.md) if you're interesting in contributing to
- Bolt.
diff --git a/docs/installation.md b/docs/installation.md
deleted file mode 100644
index 8bcbef6..0000000
--- a/docs/installation.md
+++ /dev/null
@@ -1,39 +0,0 @@
-# Installation
-
-Bolt is distributed as a standalone binary that can be installed through
-several methods.
-
-## Go install
-
-If you have Go installed, you can install Bolt using `go install`:
-
-```bash
-go install git.sr.ht/~eugenetriguba/bolt/cmd/bolt@v0.12.1
-```
-
-This will install Bolt to your `$GOBIN` directory. Make sure that `$GOBIN` is
-in your `$PATH`.
-
-## Homebrew
-
-If you're on macOS or Linux and use Homebrew, you can install Bolt from the tap:
-
-```bash
-brew tap eugenetriguba/bolt https://git.sr.ht/~eugenetriguba/homebrew-bolt
-brew install bolt
-```
-
-## Verifying Installation
-
-After installation, verify that Bolt is correctly installed by checking the
-version:
-
-```bash
-bolt version
-```
-
-You should see output displaying the current version of Bolt.
-
-## Next Steps
-
-Once installed, head over to the [Tutorial](tutorial.md) to learn how to use Bolt for your first migration.
diff --git a/docs/reference.md b/docs/reference.md
deleted file mode 100644
index 595a0a4..0000000
--- a/docs/reference.md
+++ /dev/null
@@ -1,446 +0,0 @@
-# Reference
-
-This section provides detailed reference information for Bolt's commands,
-configuration options, and supported databases.
-
-## Database Compatibility
-
-Bolt supports the following databases:
-
-- **PostgreSQL** - 13+
-- **MySQL** - 5.7+
-- **Microsoft SQL Server** - 2017+
-- **SQLite3** - All recent versions. We explicitly test against the latest
- version.
-
-## Commands
-
-### `bolt new`
-
-Create a new database migration.
-
-```bash
-bolt new [-message|-m] <message>
-```
-
-**Options:**
-
-- `-message <message>` - Message to use for the migration (default: "autogenerated")
-- `-m <message>` - Alias for `-message`
-
-**Example:**
-
-```bash
-bolt new -m "create users table"
-```
-
-### `bolt up`
-
-Apply migrations against the database.
-
-```bash
-bolt up [-version|-v] <version>
-```
-
-**Options:**
-
-- `-version <version>` - The version to upgrade up to and including (optional)
-- `-v <version>` - Alias for `-version`
-
-**Examples:**
-
-```bash
-# Apply all pending migrations
-bolt up
-
-# Apply migrations up to and including version 20240316145038
-bolt up -v 20240316145038
-```
-
-### `bolt down`
-
-Downgrade migrations against the database.
-
-```bash
-bolt down [-version|-v] <version>
-```
-
-**Options:**
-
-- `-version <version>` - The version to downgrade down to and including (optional)
-- `-v <version>` - Alias for `-version`
-
-**Examples:**
-
-```bash
-# Revert the most recent migration
-bolt down
-
-# Revert migrations down to and including version 20240316145038
-bolt down -v 20240316145038
-```
-
-### `bolt status`
-
-List the database migrations and their statuses.
-
-```bash
-bolt status
-```
-
-**Example output:**
-
-The migrations will be ordered in the same in the same order that they would be
-executed.
-
-```
-Version Message Applied
-20240316145038 my_first_migration X
-20240317120000 add_email_index
-```
-
-### `bolt version`
-
-Show the current version of Bolt.
-
-```bash
-bolt version
-```
-
-## Configuration
-
-Bolt can be configured using a `bolt.toml` configuration file and environment
-variables. Environment variables take precedence over configuration file
-settings if both are utilized.
-
-### Configuration File
-
-Bolt searches for a `bolt.toml` file in your current working directory or any
-parent directory.
-
-**Complete example:**
-
-```toml
-[migrations]
-# The directory where your migration scripts are located.
-# Defaults to "migrations". This directory is relative to
-# the current working directory. You may also use an absolute
-# path.
-directory_path = "migrations"
-
-# The migration versioning style you prefer. Supported options
-# are "timestamp" and "sequential". Defaults to "timestamp".
-version_style = "timestamp"
-
-[database]
-# The DSN (Data Source Name) for connecting to your database.
-dsn = "postgresql://user:password@localhost:5432/mydb?sslmode=disable"
-
-# The name of the database driver to use to connect to
-# the database. Either "postgresql", "mysql", "mssql", or "sqlite3".
-driver = "postgresql"
-
-# The name of the database table to create for managing
-# the applied migration versions. Defaults to "bolt_migrations".
-migrations_table = "bolt_migrations"
-```
-
-### Environment Variables
-
-All configuration file settings have corresponding environment variables:
-
-| Environment Variable | Configuration Key | Description |
-|---------------------|------------------|-------------|
-| `BOLT_MIGRATIONS_DIR_PATH` | `migrations.directory_path` | Path to migrations directory |
-| `BOLT_MIGRATIONS_VERSION_STYLE` | `migrations.version_style` | Versioning style (`timestamp` or `sequential`) |
-| `BOLT_DB_DSN` | `database.dsn` | Database connection string |
-| `BOLT_DB_DRIVER` | `database.driver` | Database driver name |
-| `BOLT_DB_MIGRATIONS_TABLE` | `database.migrations_table` | Name of migrations tracking table |
-
-**Example:**
-
-```bash
-export BOLT_DB_DSN="postgresql://user:password@localhost:5432/mydb?sslmode=disable"
-export BOLT_DB_DRIVER="postgresql"
-export BOLT_MIGRATIONS_DIR_PATH="db/migrations"
-```
-
-## Database Connection (DSN)
-
-Bolt uses DSN (Data Source Name) for database connections. This allows you to
-use any connection format supported by the database driver.
-
-### What is a DSN?
-
-A DSN (Data Source Name) 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.
-
-### PostgreSQL
-
-**Driver:** [pgx](https://github.com/jackc/pgx)
-
-[DSN Documentation](https://github.com/jackc/pgx/blob/v5.7.6/pgxpool/pool.go#L352)
-
-**Format:**
-```
-postgresql://username:password@hostname:port/database?option1=value1&option2=value2
-```
-
-**Examples:**
-
-```toml
-# Basic connection
-dsn = "postgresql://user:password@localhost:5432/mydb"
-
-# With SSL disabled
-dsn = "postgresql://user:password@localhost:5432/mydb?sslmode=disable"
-
-# With multiple options
-dsn = "postgresql://user:password@localhost:5432/mydb?sslmode=require&connect_timeout=10&application_name=bolt"
-
-# Using Unix socket
-dsn = "postgresql://user:password@/mydb?host=/var/run/postgresql"
-```
-
-### MySQL
-
-**Driver:** [go-sql-driver/mysql](https://github.com/go-sql-driver/mysql)
-
-[DSN Documentation](https://github.com/go-sql-driver/mysql#dsn-data-source-name)
-
-**Format:**
-```
-username:password@tcp(hostname:port)/database?option1=value1&option2=value2
-```
-
-**Examples:**
-
-```toml
-# Basic connection
-dsn = "user:password@tcp(localhost:3306)/mydb"
-
-# With parse time and charset
-dsn = "user:password@tcp(localhost:3306)/mydb?parseTime=true&charset=utf8mb4"
-
-# With connection timeout and TLS
-dsn = "user:password@tcp(localhost:3306)/mydb?timeout=10s&tls=true"
-
-# Using Unix socket
-dsn = "user:password@unix(/tmp/mysql.sock)/mydb"
-```
-
-### SQL Server (MSSQL)
-
-**Driver:** [microsoft/go-mssqldb](https://github.com/microsoft/go-mssqldb)
-
-[DSN Documentation](https://github.com/microsoft/go-mssqldb#connection-parameters-and-dsn)
-
-**Format:**
-```
-sqlserver://username:password@hostname:port?database=database&option1=value1&option2=value2
-```
-
-**Examples:**
-
-```toml
-# Basic connection
-dsn = "sqlserver://user:password@localhost:1433?database=mydb"
-
-# With encryption and timeout
-dsn = "sqlserver://user:password@localhost:1433?database=mydb&encrypt=disable&connection+timeout=30"
-
-# With instance name
-dsn = "sqlserver://user:password@localhost\\SQLEXPRESS?database=mydb"
-
-# Using Windows authentication
-dsn = "sqlserver://localhost:1433?database=mydb&trusted_connection=yes"
-```
-
-### SQLite
-
-**Driver:** [mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)
-
-[DSN Documentation](https://github.com/mattn/go-sqlite3#connection-string)
-
-**Format:**
-```
-/path/to/database.db?option1=value1&option2=value2
-```
-
-**Examples:**
-
-```toml
-# Basic file-based database
-dsn = "/path/to/mydatabase.db"
-
-# In-memory database
-dsn = ":memory:"
-
-# With read-only mode
-dsn = "/path/to/mydatabase.db?mode=ro"
-
-# With foreign keys enabled
-dsn = "/path/to/mydatabase.db?_foreign_keys=on"
-```
-
-## Migration Script Directives
-
-Bolt supports several directives that can be added to migration files to
-control behavior.
-
-### `-- depends:`
-
-Declares dependencies on other migrations. Dependencies determine execution order.
-
-**Syntax:**
-```sql
--- depends: version1, version2, version3
-```
-
-**Format Rules:**
-
-- Multiple versions are separated by commas
-- Whitespace around commas is optional (`version1,version2` and `version1, version2` are equivalent)
-- The directive is case-insensitive (`-- DEPENDS:`, `-- depends:`, `-- Depends:` all work)
-- Version numbers must exactly match existing migration version numbers
-
-**Examples:**
-
-No dependencies (root migration):
-```sql
--- migrate:up
-CREATE TABLE users (
- id SERIAL PRIMARY KEY,
- name VARCHAR(255)
-);
-
--- migrate:down
-DROP TABLE users;
-```
-
-Single dependency:
-```sql
--- depends: 20240316145038
--- migrate:up
-CREATE TABLE posts (
- id SERIAL PRIMARY KEY,
- user_id INTEGER NOT NULL REFERENCES users(id)
-);
-
--- migrate:down
-DROP TABLE posts;
-```
-
-Multiple dependencies:
-```sql
--- depends: 20240316145038, 20240317120000, 20240318093000
--- 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;
-```
-
-**Execution Order:**
-
-Migrations are executed in topological order:
-1. Migrations with no dependencies run first
-2. Once a migration completes, migrations that depend only on completed
- migrations become eligible
-3. When multiple migrations are eligible simultaneously, they execute in
- version order (timestamp or sequential) for deterministic behavior
-
-**Automatic Population:**
-
-When you create a new migration with `bolt new`, Bolt automatically populates
-the `-- depends:` directive with current "leaf" migrations (migrations that
-no other migration depends on).
-
-First migration in a project:
-```bash
-bolt new -m "create users"
-# Generated file has no -- depends: line
-```
-
-Second migration:
-```bash
-bolt new -m "create posts"
-# Generated file has: -- depends: 20240316145038
-```
-
-After parallel migrations merge:
-```bash
-# If migrations A and B both exist and neither depends on the other
-bolt new -m "create feature needing both"
-# Generated file has: -- depends: <version_A>, <version_B>
-```
-
-### `-- migrate:up` and `-- migrate:down`
-
-These directives separate the upgrade and downgrade portions of your migration.
-
-**Syntax:**
-```sql
--- migrate:up [option1] [option2]
--- migrate:down [option1] [option2]
-```
-
-**Example:**
-```sql
--- migrate:up
-CREATE TABLE users (
- id SERIAL PRIMARY KEY,
- name VARCHAR(255) NOT NULL
-);
-
--- migrate:down
-DROP TABLE users;
-```
-
-### Available Options
-
-Options can be added to the `-- migrate:up` or `-- migrate:down` directives.
-
-#### `transaction:false`
-
-Execute the migration script without a transaction. By default, every
-migration script is executed within a transaction.
-
-**Example:**
-
-```sql
--- migrate:up transaction:false
-CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
-
--- migrate:down transaction:false
-DROP INDEX CONCURRENTLY idx_users_email;
-```
-
-## Version Styles
-
-Bolt supports two migration versioning styles:
-
-### Timestamp (Default)
-
-Migrations are versioned using timestamps (e.g., `20240316145038`).
-
-**Configuration:**
-```toml
-[migrations]
-version_style = "timestamp"
-```
-
-### Sequential
-
-Migrations are versioned using incrementing integers (e.g., `001`, `002`, `003`).
-
-**Configuration:**
-```toml
-[migrations]
-version_style = "sequential"
-```
diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
deleted file mode 100644
index 4fddf5c..0000000
--- a/docs/requirements-docs.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-mkdocs==1.6.1
-mkdocs-material==9.6.21
-
diff --git a/docs/tutorial.md b/docs/tutorial.md
deleted file mode 100644
index 147a6f6..0000000
--- a/docs/tutorial.md
+++ /dev/null
@@ -1,250 +0,0 @@
-# Tutorial
-
-In this tutorial, we'll guide you through the basics of using Bolt by running
-through how you can create a migration, apply it, revert it, and see the
-status of your migrations.
-
-## Prerequisites
-
-Before starting this tutorial, make sure you have:
-
-- Bolt installed (see [Installation](installation.md))
-- Docker installed (for running the database container)
-
-## Creating your first migration
-
-Run the following command to create your first migration:
-
-```bash
-bolt new -m "my first migration"
-```
-
-Output:
-```
-Created migration 20240316145038 - my first migration.
-```
-
-Upon completion, a migrations directory will be created with the following
-structure:
-
-```bash
-migrations
-└── 20240316145038_my_first_migration.sql
-
-1 directory, 1 file
-```
-
-Bolt automatically creates the migrations directory and your migration scripts
-inside it.
-
-## Writing your migration scripts
-
-Bolt utilizes plain SQL for migration scripts. Each migration file contains a
-comment for the upgrade script portion with `-- migrate:up` and a comment for
-the downgrade script with `-- migrate:down`.
-
-1. Open up `20240316145038_my_first_migration.sql`
-
-You'll see the following template in the file for your migration:
-
-```sql
--- migrate:up
-
--- migrate:down
-```
-
-2. Write your migration script
-
-```sql
--- 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(),
- updated_at TIMESTAMP NOT NULL DEFAULT NOW()
-);
-
--- migrate:down
-DROP TABLE users;
-```
-
-## Starting up a Database Container
-
-We'll use Docker to run a PostgreSQL database container for this tutorial:
-
-1. Install Docker
-
-If you don't have docker installed, view the installation instructions [here](https://docs.docker.com/get-docker/).
-
-2. Startup the PostgreSQL container
-
-```bash
-docker run \
- --name bolt-postgres \
- --env POSTGRES_USER=bolt_user \
- --env POSTGRES_PASSWORD=bolt_password \
- --env POSTGRES_DB=bolt_tutorial_db \
- --publish 5432:5432 \
- --detach \
- postgres:latest
-```
-
-## Configuring Bolt
-
-Bolt can be configured with a `bolt.toml` file and environment variables. For
-simplicity, we'll use a `bolt.toml` file in this tutorial.
-
-1. Create a `bolt.toml` file:
-
-```bash
-touch bolt.toml
-```
-
-2. Add the following contents to the file:
-
-```toml
-[database]
-dsn = "postgresql://bolt_user:bolt_password@localhost:5432/bolt_tutorial_db?sslmode=disable"
-driver = "postgresql"
-```
-
-## Applying your migration
-
-Apply your migration, which will execute the upgrade script:
-
-```bash
-bolt up
-```
-
-Output:
-```
-Applying migration 20240316145038_my_first_migration..
-Successfully applied migration 20240316145038_my_first_migration in 3.217875ms!
-```
-
-## Checking Migration Status
-
-To view the status of your migration:
-
-```bash
-bolt status
-```
-
-Output:
-```
-Version Message Applied
-20240316145038 my_first_migration X
-```
-
-This command displays the migration's version, name, and whether the migration
-was applied or not.
-
-## Verifying the Migration
-
-Connect to the database container to confirm the users table was created:
-
-```bash
-docker exec -it bolt-postgres psql -U bolt_user -d bolt_tutorial_db
-```
-
-```psql
-bolt_tutorial_db=# \dt
- List of relations
- Schema | Name | Type | Owner
---------+-----------------+-------+-----------
- public | bolt_migrations | table | bolt_user
- public | users | table | bolt_user
-(2 rows)
-```
-
-We can see that our `users` table was created successfully. We also see another
-table that we didn't explicitly create called `bolt_migrations`. This table is
-used by Bolt to keep track of which migrations have been applied to your
-database. Generally, you should not modify this table manually.
-
-## Downgrading Your Migration
-
-To revert your migration:
-
-```bash
-bolt down
-```
-
-Output:
-```
-Reverting migration 20240316145038_my_first_migration..
-Successfully reverted migration 20240316145038_my_first_migration in 6.283667ms!
-```
-
-## Verifying Migration Reversion
-
-Reconnect to the database container and check that the users table has been
-removed:
-
-```bash
-docker exec -it bolt-postgres psql -U bolt_user -d bolt_tutorial_db
-```
-
-```psql
-bolt_tutorial_db=# \dt
- List of relations
- Schema | Name | Type | Owner
---------+-----------------+-------+-----------
- public | bolt_migrations | table | bolt_user
-(1 row)
-```
-
-## Creating a migration with dependencies
-
-Let's create another migration that depends on the first one:
-
-```bash
-bolt new -m "create posts table"
-```
-
-Open the new migration file. You'll see that Bolt automatically added
-a dependency on the previous migration:
-
-```sql
--- depends: 20240316145038
--- migrate:up
-
--- migrate:down
-```
-
-Add the migration SQL:
-
-```sql
--- depends: 20240316145038
--- migrate:up
-CREATE TABLE posts (
- id SERIAL PRIMARY KEY,
- user_id INTEGER NOT NULL REFERENCES users(id),
- title VARCHAR(255) NOT NULL,
- content TEXT NOT NULL,
- created_at TIMESTAMP NOT NULL DEFAULT NOW()
-);
-
--- migrate:down
-DROP TABLE posts;
-```
-
-Apply the new migration:
-
-```bash
-bolt up
-```
-
-The dependency ensures that the `users` table exists before creating the
-`posts` table with its foreign key reference.
-
-## Next Steps
-
-Congratulations! You've learned the core features of Bolt.
-
-To learn more:
-
-- Check out [How-To Guides](how-to.md) for specific tasks
-- Browse the [Reference](reference.md) for detailed command and configuration documentation
-- Read the [Explanation](explanation.md) section to understand how Bolt works internally
diff --git a/internal/cli/cli.go b/internal/cli/cli.go
index 1c8bd74..1561da4 100644
--- a/internal/cli/cli.go
+++ b/internal/cli/cli.go
@@ -9,7 +9,7 @@ import (
// Run runs the Bolt CLI and returns the exit code.
func Run() int {
- subcmd.Register(subcmd.HelpCommand(), "")
+ subcmd.Register(subcmd.ManHelpCommand("bolt"), "")
subcmd.Register(&commands.VersionCmd{}, "")
subcmd.Register(&commands.NewCmd{}, "")
subcmd.Register(&commands.UpCmd{}, "")
diff --git a/internal/commands/down.go b/internal/commands/down.go
index 4980940..affa02b 100644
--- a/internal/commands/down.go
+++ b/internal/commands/down.go
@@ -44,7 +44,7 @@ func (cmd *DownCmd) SetFlags(f *flag.FlagSet) {
func (cmd *DownCmd) Execute(
_ context.Context,
f *flag.FlagSet,
- _ ...interface{},
+ _ ...any,
) subcmd.ExitStatus {
consoleOutputter := output.NewConsoleOutputter()
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
diff --git a/mkdocs.yml b/mkdocs.yml
deleted file mode 100644
index 79e161a..0000000
--- a/mkdocs.yml
+++ /dev/null
@@ -1,52 +0,0 @@
-site_name: Bolt
-site_url: https://bolt.eugenetriguba.com
-site_description: A command-line tool for database migrations
-site_author: Eugene Triguba
-repo_url: https://git.sr.ht/~eugenetriguba/bolt
-repo_name: ~eugenetriguba/bolt
-
-theme:
- name: material
- palette:
- - scheme: default
- primary: indigo
- accent: indigo
- toggle:
- icon: material/brightness-7
- name: Switch to dark mode
- - scheme: slate
- primary: indigo
- accent: indigo
- toggle:
- icon: material/brightness-4
- name: Switch to light mode
- features:
- - navigation.instant
- - navigation.tracking
- - navigation.tabs
- - navigation.sections
- - navigation.expand
- - navigation.top
- - search.suggest
- - search.highlight
- - content.code.copy
-
-markdown_extensions:
- - admonition
- - pymdownx.details
- - pymdownx.superfences
- - pymdownx.highlight:
- anchor_linenums: true
- - pymdownx.inlinehilite
- - pymdownx.snippets
- - toc:
- permalink: true
-
-nav:
- - Home: index.md
- - Installation: installation.md
- - Tutorial: tutorial.md
- - How-To Guides: how-to.md
- - Reference: reference.md
- - Explanation: explanation.md
- - Contributing: contributing.md
diff --git a/scripts/deploy-docs.sh b/scripts/deploy-docs.sh
deleted file mode 100755
index 194882a..0000000
--- a/scripts/deploy-docs.sh
+++ /dev/null
@@ -1,48 +0,0 @@
-#!/usr/bin/env bash
-set -eou pipefail
-
-source "$(dirname "${BASH_SOURCE[0]}")/lib/log.sh"
-source "$(dirname "${BASH_SOURCE[0]}")/lib/path.sh"
-
-readonly SITE="bolt.eugenetriguba.com"
-
-usage() {
- echo "Usage: $0"
- echo ""
- echo "Build and deploy documentation to SourceHut Pages"
- echo ""
- echo "Examples:"
- echo " $0 # Build and deploy docs to $SITE"
-}
-
-main() {
- if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
- usage
- exit 0
- fi
-
- log_header "Deploying Documentation"
- build_docs
- package_site
- deploy_to_pages
-}
-
-build_docs() {
- log_step "Building documentation with MkDocs"
- mkdocs build
- log_success "Documentation built successfully"
-}
-
-package_site() {
- log_step "Creating tarball"
- tar -C site -czf site.tar.gz .
- log_success "Site packaged as site.tar.gz"
-}
-
-deploy_to_pages() {
- log_step "Deploying to SourceHut Pages: $SITE"
- hut pages publish -d "$SITE" site.tar.gz
- log_success "Documentation deployed to https://$SITE"
-}
-
-main "$@"
diff --git a/scripts/is-branch.sh b/scripts/is-branch.sh
deleted file mode 100755
index 7bba709..0000000
--- a/scripts/is-branch.sh
+++ /dev/null
@@ -1,39 +0,0 @@
-#!/usr/bin/env bash
-set -eou pipefail
-
-source "$(dirname "${BASH_SOURCE[0]}")/lib/log.sh"
-
-TARGET_BRANCH=""
-
-main() {
- if [[ $# -ne 1 ]]; then
- echo "Usage: $0 <target-branch>" >&2
- exit 1
- fi
- TARGET_BRANCH="$1"
- local -r current_branch=$(get_current_branch)
-
- if [[ "$current_branch" != "$TARGET_BRANCH" ]]; then
- log_warn "Not on $TARGET_BRANCH branch (current branch is $current_branch)"
- exit 2
- fi
- log_info "On $TARGET_BRANCH branch"
-}
-
-get_current_branch() {
- # build.sr.ht automatically injects the GIT_REF environment variable
- # - GIT_REF: Git reference which triggered the build (e.g. refs/heads/master)
- #
- # See https://man.sr.ht/builds.sr.ht/
- local current_branch="${GIT_REF:-}"
- if [[ -z "$current_branch" ]]; then
- current_branch=$(git rev-parse --abbrev-ref HEAD)
- else
- # Strip refs/heads/ prefix if present
- # GIT_REF, if set, should be in the format: refs/heads/<branch-name>
- current_branch="${current_branch#refs/heads/}"
- fi
- echo "$current_branch"
-}
-
-main "$@"
diff --git a/scripts/release.sh b/scripts/release.sh
index aeb90e3..b914b9f 100755
--- a/scripts/release.sh
+++ b/scripts/release.sh
@@ -7,8 +7,6 @@ source "$(dirname "${BASH_SOURCE[0]}")/lib/path.sh"
readonly VERSION_FILE="$PATH_PROJECT_DIR/internal/commands/version.go"
readonly CHANGELOG_FILE="$PATH_PROJECT_DIR/CHANGELOG.md"
readonly README_FILE="$PATH_PROJECT_DIR/README.md"
-readonly DOCS_INDEX_FILE="$PATH_PROJECT_DIR/docs/index.md"
-readonly DOCS_INSTALLATION_FILE="$PATH_PROJECT_DIR/docs/installation.md"
usage() {
echo "Usage: $0 <version>"
@@ -51,8 +49,6 @@ main() {
update_version_file "$current_version" "$new_version"
update_readme "$current_version" "$new_version"
- update_docs_index "$current_version" "$new_version"
- update_docs_installation "$current_version" "$new_version"
update_changelog "$new_version"
show_changes
@@ -139,24 +135,6 @@ update_readme() {
mv "$README_FILE.tmp" "$README_FILE"
}
-update_docs_index() {
- local old_version="$1"
- local new_version="$2"
-
- log_step "Updating version in $DOCS_INDEX_FILE"
- sed "s/version-$old_version-blue/version-$new_version-blue/g; s|bolt/cmd/bolt@v$old_version|bolt/cmd/bolt@v$new_version|g" "$DOCS_INDEX_FILE" >"$DOCS_INDEX_FILE.tmp"
- mv "$DOCS_INDEX_FILE.tmp" "$DOCS_INDEX_FILE"
-}
-
-update_docs_installation() {
- local old_version="$1"
- local new_version="$2"
-
- log_step "Updating version in $DOCS_INSTALLATION_FILE"
- sed "s|bolt/cmd/bolt@v$old_version|bolt/cmd/bolt@v$new_version|g" "$DOCS_INSTALLATION_FILE" >"$DOCS_INSTALLATION_FILE.tmp"
- mv "$DOCS_INSTALLATION_FILE.tmp" "$DOCS_INSTALLATION_FILE"
-}
-
update_changelog() {
local new_version="$1"
local today
@@ -186,7 +164,7 @@ update_changelog() {
show_changes() {
log_newline
log_step "Changes to be committed:"
- git diff "$VERSION_FILE" "$README_FILE" "$DOCS_INDEX_FILE" "$DOCS_INSTALLATION_FILE" "$CHANGELOG_FILE"
+ git diff "$VERSION_FILE" "$README_FILE" "$CHANGELOG_FILE"
}
confirm_release() {
@@ -204,7 +182,7 @@ create_release_commit() {
local version="$1"
log_step "Creating release commit"
- git add "$VERSION_FILE" "$README_FILE" "$DOCS_INDEX_FILE" "$DOCS_INSTALLATION_FILE" "$CHANGELOG_FILE"
+ git add "$VERSION_FILE" "$README_FILE" "$CHANGELOG_FILE"
git commit -m "Release v$version"
}