aboutsummaryrefslogtreecommitdiffstats
path: root/docs
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 /docs
parentRelease v0.12.1 (diff)
downloadcli-449f74ded67b49fb3066d6d107fa6de9dba0093c.zip
Replace HTML docs with man pages that ship with bolt
Diffstat (limited to 'docs')
-rw-r--r--docs/contributing.md80
-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
8 files changed, 0 insertions, 1426 deletions
diff --git a/docs/contributing.md b/docs/contributing.md
deleted file mode 100644
index 418958f..0000000
--- a/docs/contributing.md
+++ /dev/null
@@ -1,80 +0,0 @@
-# Contributing to Bolt
-
-Thank you for your interest in contributing to Bolt! This document provides
-guidelines and instructions for contributing to the project.
-
-Bolt is hosted on [SourceHut](https://sr.ht/~eugenetriguba/Bolt/). If you're new
-to SourceHut, see the [git.sr.ht quickstart](https://man.sr.ht/git.sr.ht/).
-
-You do not need an account on SourceHut to contribute.
-
-## How to Contribute
-
-Bolt uses an [email-based workflow](https://git-send-email.io/) for
-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.
-
-## Development Setup
-
-### Prerequisites
-
-- Go 1.24.0 or later
-- Docker (for running database integration tests)
-- git
-
-### Initial Setup
-
-1. Clone the repository:
-```bash
-git clone https://git.sr.ht/~eugenetriguba/bolt
-cd bolt
-```
-
-2. Install dependencies:
-```bash
-go mod download
-```
-
-3. Build the project:
-```bash
-./scripts/build.sh
-```
-
-### Running Tests
-
-Bolt has integration tests for all supported databases. The test
-suite uses docker containers to run database instances.
-
-Run all tests:
-```bash
-./scripts/test.sh
-```
-
-Run all tests and leave database containers running:
-```
-./scripts/test.sh --keepdb
-```
-
-Run tests for a specific database:
-```bash
-./scripts/test.sh postgres
-./scripts/test.sh mysql
-./scripts/test.sh mssql
-./scripts/test.sh sqlite3
-```
-
-### Running Linters/Formatters
-
-To lint:
-```bash
-./scripts/lint.sh
-```
-
-To format:
-```bash
-./scripts/format.sh
-```
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