From 449f74ded67b49fb3066d6d107fa6de9dba0093c Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Thu, 12 Feb 2026 19:14:17 -0500 Subject: Replace HTML docs with man pages that ship with bolt --- .builds/docs.yml | 22 --- .builds/lint.yml | 2 +- CHANGELOG.md | 5 + CONTRIBUTING.md | 80 ++++++++ Makefile | 49 +++++ README.md | 114 ++++++++++-- docs/contributing.md | 80 -------- docs/explanation.md | 357 ------------------------------------ docs/how-to.md | 169 ----------------- docs/index.md | 82 --------- docs/installation.md | 39 ---- docs/reference.md | 446 --------------------------------------------- docs/requirements-docs.txt | 3 - docs/tutorial.md | 250 ------------------------- internal/cli/cli.go | 2 +- internal/commands/down.go | 2 +- man/bolt-databases.7 | 145 +++++++++++++++ man/bolt-dependencies.7 | 121 ++++++++++++ man/bolt-down.1 | 42 +++++ man/bolt-execution.7 | 144 +++++++++++++++ man/bolt-help.1 | 27 +++ man/bolt-migration.5 | 109 +++++++++++ man/bolt-new.1 | 45 +++++ man/bolt-status.1 | 40 ++++ man/bolt-tutorial.7 | 101 ++++++++++ man/bolt-up.1 | 45 +++++ man/bolt-version.1 | 17 ++ man/bolt.1 | 70 +++++++ man/bolt.toml.5 | 106 +++++++++++ mkdocs.yml | 52 ------ scripts/deploy-docs.sh | 48 ----- scripts/is-branch.sh | 39 ---- scripts/release.sh | 26 +-- 33 files changed, 1253 insertions(+), 1626 deletions(-) delete mode 100644 .builds/docs.yml create mode 100644 CONTRIBUTING.md create mode 100644 Makefile delete mode 100644 docs/contributing.md delete mode 100644 docs/explanation.md delete mode 100644 docs/how-to.md delete mode 100644 docs/index.md delete mode 100644 docs/installation.md delete mode 100644 docs/reference.md delete mode 100644 docs/requirements-docs.txt delete mode 100644 docs/tutorial.md create mode 100644 man/bolt-databases.7 create mode 100644 man/bolt-dependencies.7 create mode 100644 man/bolt-down.1 create mode 100644 man/bolt-execution.7 create mode 100644 man/bolt-help.1 create mode 100644 man/bolt-migration.5 create mode 100644 man/bolt-new.1 create mode 100644 man/bolt-status.1 create mode 100644 man/bolt-tutorial.7 create mode 100644 man/bolt-up.1 create mode 100644 man/bolt-version.1 create mode 100644 man/bolt.1 create mode 100644 man/bolt.toml.5 delete mode 100644 mkdocs.yml delete mode 100755 scripts/deploy-docs.sh delete mode 100755 scripts/is-branch.sh 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/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9a0263e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,80 @@ +# 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 + use a prefix of `[bolt]`. + +## 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/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/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 `, 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 `, 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: `_.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] -``` - -**Options:** - -- `-message ` - Message to use for the migration (default: "autogenerated") -- `-m ` - Alias for `-message` - -**Example:** - -```bash -bolt new -m "create users table" -``` - -### `bolt up` - -Apply migrations against the database. - -```bash -bolt up [-version|-v] -``` - -**Options:** - -- `-version ` - The version to upgrade up to and including (optional) -- `-v ` - 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] -``` - -**Options:** - -- `-version ` - The version to downgrade down to and including (optional) -- `-v ` - 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: , -``` - -### `-- 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 " >&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/ - 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 " @@ -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" } -- cgit v1.2.3