aboutsummaryrefslogtreecommitdiffstats
path: root/docs/reference.md
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/reference.md
parentRelease v0.12.1 (diff)
downloadcli-449f74ded67b49fb3066d6d107fa6de9dba0093c.zip
Replace HTML docs with man pages that ship with bolt
Diffstat (limited to 'docs/reference.md')
-rw-r--r--docs/reference.md446
1 files changed, 0 insertions, 446 deletions
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"
-```