diff options
| -rw-r--r-- | .build-docs.yml | 16 | ||||
| -rw-r--r-- | .build-test.yml (renamed from .build.yml) | 0 | ||||
| -rw-r--r-- | README.md | 535 | ||||
| -rw-r--r-- | docs/contributing.md (renamed from CONTRIBUTING.md) | 0 | ||||
| -rw-r--r-- | docs/explanation.md | 286 | ||||
| -rw-r--r-- | docs/how-to.md | 116 | ||||
| -rw-r--r-- | docs/index.md | 90 | ||||
| -rw-r--r-- | docs/installation.md | 36 | ||||
| -rw-r--r-- | docs/reference.md | 346 | ||||
| -rw-r--r-- | docs/tutorial.md | 192 | ||||
| -rw-r--r-- | mkdocs.yml | 52 | ||||
| -rw-r--r-- | requirements-docs.txt | 1 | ||||
| -rwxr-xr-x | scripts/deploy-docs.sh | 47 |
13 files changed, 1216 insertions, 501 deletions
diff --git a/.build-docs.yml b/.build-docs.yml new file mode 100644 index 0000000..ba7fa9b --- /dev/null +++ b/.build-docs.yml @@ -0,0 +1,16 @@ +image: archlinux +packages: + - python + - python-pip + - hut +sources: + - https://git.sr.ht/~eugenetriguba/bolt +secrets: + - fa00a8d3-7b63-42bb-8f19-fd5b5f8f18ab +tasks: + - install-deps: | + cd bolt + pip install --user -r requirements-docs.txt + - deploy: | + cd bolt + ./scripts/deploy-docs.sh diff --git a/.build.yml b/.build-test.yml index a66da3e..a66da3e 100644 --- a/.build.yml +++ b/.build-test.yml @@ -3,7 +3,6 @@ <h1>Bolt</h1> </div> - [](https://godoc.org/git.sr.ht/~eugenetriguba/bolt) [](https://goreportcard.com/report/git.sr.ht/~eugenetriguba/bolt)  @@ -11,122 +10,38 @@ 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 indepenent. It doesn't matter what programming language you're using, you can use Bolt for any project you have. - -## Table of Contents - -- [Features](#features) -- [Installation](#installation) - - [Go install](#go-install) - - [Homebrew](#homebrew) -- [Tutorial](#tutorial) - - [Creating your first migration](#creating-your-first-migration) - - [Writing your migration scripts](#writing-your-migration-scripts) - - [Starting up a Database Container](#starting-up-a-database-container) - - [Configuring Bolt](#configuring-bolt) - - [Applying your migration](#applying-your-migration) - - [Checking Migration Status](#checking-migration-status) - - [Verifying the Migration](#verifying-the-migration) - - [Downgrading Your Migration](#downgrading-your-migration) - - [Verifying Migration Reversion](#verifying-migration-reversion) - - [Next Steps](#next-steps) -- [How-to](#how-to) - - [How to execute a migration script without a transaction](#how-to-execute-a-migration-script-without-a-transaction) -- [Reference](#reference) - - [Database Compatibility](#database-compatibility) - - [Configuration](#configuration) - - [Configuration File](#configuration-file) - - [Environment Variables](#environment-variables) - - [Database Connection (DSN)](#database-connection-dsn) - - [What is a DSN?](#what-is-a-dsn) - - [DSN Format Examples](#dsn-format-examples) - - [Environment Variable Examples](#environment-variable-examples) - - [Driver-Specific Considerations](#driver-specific-considerations) - - [Security Notes](#security-notes) - - [Migration from Individual Parameters](#migration-from-individual-parameters) - - [Commands](#commands) - - [`bolt new`](#bolt-new) - - [`bolt up`](#bolt-up) - - [`bolt down`](#bolt-down) - - [`bolt status`](#bolt-status) - - [`bolt version`](#bolt-version) - - [Script Execution Options](#script-execution-options) - - [Version Styles](#version-styles) -- [Explanation](#explanation) - - [How Are Migration Scripts Executed?](#how-are-migration-scripts-executed) - - [How Does Bolt Know What Migrations Have Been Applied?](#how-does-bolt-know-what-migrations-have-been-applied) - - [How Are Migrations Applied?](#how-are-migrations-applied) - - [How Are Migrations Reverted?](#how-are-migrations-reverted) - - [What are Migration Version Styles?](#what-are-migration-version-styles) - - [Why can't I change between version styles?](#why-cant-i-change-between-version-styles) - - [How is the migration message used?](#how-is-the-migration-message-used) - - [What restrictions are there on the custom migration table?](#what-restrictions-are-there-on-the-custom-migration-table) -- [Contributing](#contributing) +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. +- 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 -## Installation +## Quick Start -### Go install +### Install ```bash -$ go install git.sr.ht/~eugenetriguba/bolt/cmd/bolt@latest -``` +# Using Go +go install git.sr.ht/~eugenetriguba/bolt/cmd/bolt@latest -This will install Bolt to your `$GOBIN` directory. Make sure that `$GOBIN` is in your `$PATH`. - -### Homebrew - -```bash -$ brew tap eugenetriguba/bolt https://git.sr.ht/~eugenetriguba/homebrew-bolt -$ brew install bolt +# Using Homebrew +brew tap eugenetriguba/bolt https://git.sr.ht/~eugenetriguba/homebrew-bolt +brew install bolt ``` -## 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. - -### Creating your first migration - -Run the following command to create your first migration: +### Create a migration ```bash -$ bolt new -m "my first migration" -Created migration 20240316145038 - my first migration. +bolt new -m "create users table" ``` -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 directory 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 -``` +### Write your migration -2. Write your migration script +Edit the generated SQL file in `migrations/`: ```sql -- migrate:up @@ -134,425 +49,43 @@ 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() + created_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/). +### Configure and apply -2. Startup the PostgreSQL container - -```bash -$ docker run --name bolt-postgres -e POSTGRES_USER=bolt_user -e POSTGRES_PASSWORD=bolt_password -e POSTGRES_DB=bolt_tutorial_db -p 5432:5432 --detach postgres:16.1-alpine3.19 -``` - -### Configuring Bolt - -Bolt can be configured with a `bolt.toml` file or 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: +Create `bolt.toml`: ```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.sql` script: - -```bash -$ bolt up -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 -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. You should not modify this table manually. - -### Downgrading Your Migration - -To revert your migration: - -```bash -$ bolt down -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) -``` - -### Next Steps - -Congrats! You've learned the core features of Bolt. If you want learn more, see the [How-to](#how-to), [Reference](#reference), or [Explanation](#explanation) section. - -## How-to - -### How to execute a migration script without a transaction - -In your migration script, add a `transaction:false` option: - -```sql --- migrate:up transaction:false - --- migrate:down transaction:false -``` - -## Reference - -### Database Compatibility - -- PostgreSQL -- MySQL -- Microsoft SQL Server -- SQLite3 - -### Configuration - -There are two ways to configure Bolt: via a `bolt.toml` file or via environment variables. If you use both methods, the environment variables will always take precedence. - -#### Configuration File - -Bolt attempts to find a `bolt.toml` file in your current working directory -or in any parent directory. - -```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". -# -# Note: It is not supported to change migration version styles -# i.e. you can't have a mix of sequential and timestamp migrations. -version_style = "timestamp" - -# Connection parameters for the database Bolt will be applying -# migrations to. -[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. - -- `BOLT_MIGRATIONS_DIR_PATH` -- `BOLT_MIGRATIONS_VERSION_STYLE` -- `BOLT_DB_DSN` -- `BOLT_DB_DRIVER` -- `BOLT_DB_MIGRATIONS_TABLE` - -### 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. - -#### DSN Format Examples - -##### PostgreSQL - -**Driver**: [pgx](https://github.com/jackc/pgx) - [DSN Documentation](https://pkg.go.dev/github.com/jackc/pgx/v5#hdr-Connection_String_Parameters) - -**Basic 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" -``` - -```bash -export BOLT_DB_DSN="postgresql://user:password@localhost:5432/mydb?sslmode=disable" -export BOLT_DB_DRIVER="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) - -**Basic 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" -``` - -```bash -export BOLT_DB_DSN="user:password@tcp(localhost:3306)/mydb?parseTime=true" -export BOLT_DB_DRIVER="mysql" -``` - -##### 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) - -**Basic 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" -``` - -```bash -export BOLT_DB_DSN="sqlserver://user:password@localhost:1433?database=mydb" -export BOLT_DB_DRIVER="mssql" -``` - -##### SQLite - -**Driver**: [mattn/go-sqlite3](https://github.com/mattn/go-sqlite3) - [DSN Documentation](https://github.com/mattn/go-sqlite3#connection-string) - -**Basic 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" -``` +Apply the migration: ```bash -export BOLT_DB_DSN="/path/to/database.db" -export BOLT_DB_DRIVER="sqlite3" +bolt up ``` -### Commands - -#### `bolt new` - -```bash -$ bolt help new -new [-message|-m]: - Create a new database migration - -m string - alias for -message (default "autogenerated") - -message string - Message to use for the migration (default "autogenerated") -``` - -#### `bolt up` - -```bash -$ bolt help up -up [-version|-v]: - Apply migrations against the database - -v string - alias for -version - -version string - The version to upgrade up and including to. -``` - -#### `bolt down` - -```bash -$ bolt help down -down [-version|-v]: - Downgrade migrations against the database - -v string - alias for -version - -version string - The version to downgrade down and including to. -``` - -#### `bolt status` - -```bash -$ bolt help status -status: - List the database migrations and their statuses -``` - -#### `bolt version` - -```bash -$ bolt help version -version: - Show the current version of Bolt -``` +## Documentation -### Script Execution Options +For complete documentation, visit **[eugenetriguba.srht.site/bolt](https://eugenetriguba.srht.site/bolt/)** -Bolt provides a way for you to customize how your migration scripts are executed if you need something different than the default behavior. +- [Installation Guide](https://eugenetriguba.srht.site/bolt/installation/) +- [Tutorial](https://eugenetriguba.srht.site/bolt/tutorial/) +- [How-To Guides](https://eugenetriguba.srht.site/bolt/how-to/) +- [Reference](https://eugenetriguba.srht.site/bolt/reference/) +- [Explanation](https://eugenetriguba.srht.site/bolt/explanation/) -You can do this by adding onto the `-- migrate:up` or `-- migrate:down` comments with your own execution option. The options must be in the following format: `-- migrate:up <option1> <option2> <...>` or `-- migrate:down <option1> <option2> <...>`. The following options are available: - -- `transaction:false`: Execute the migration script without a transaction. By default, every migration script will be attempted to be executed within a transaction, however, some SQL commands cannot be executed within a transaction so you'll need to opt out of that behavior in those cases. - -### Version Styles - -The following version styles are supported: -- Timestamp -- Sequential - -## Explanation - -### How Are Migration Scripts Executed? - -Bolt executes upgrade and downgrade migration scripts in a transaction. This ensures that if any errors occur during the execution of any 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 what error has occurred to standard error. However, do note that some databases, like MySQL, commit certain DDL statements immediately even if you're in a transaction. - -### How Does Bolt Know What Migrations Have Been Applied? - -Bolt keeps track of which migrations have been applied to your database by creating a table called `bolt_migrations`. This table contains a single column called `version` which is the version of the migration that was applied. That version is compared to the versions you have locally. - -### How Are Migrations Applied? - -When you run `bolt up`, Bolt will look at your local migration scripts and compares the version part of the migration directory names to the versions that have been inserted into the `bolt_migrations` table. Any versions that aren't in the table will be applied in order, starting with the oldest migration. Applying a migration entails executing the `-- migrate:up` portion of the script in a transaction and inserting in the migration's version into the `bolt_migrations` table. - -### How Are Migrations Reverted? - -When you run `bolt down`, Bolt will look at the `bolt_migrations` table and compare the versions to the versions of your local migration scripts. Any versions that are in the table but not in your local migration scripts will be reverted in order, starting with the newest migration. Reverting a migration entails executing the `-- migrate:down` portion of the script in a transaction and removing the migration's version from the `bolt_migrations` table. - -### What are Migration Version Styles? - -Whenever you create a migration, it'll be prefixed with a "version". This is what is used by Bolt to keep track of what order to apply or revert migrations. Version styles are different supported options for what this prefix will be. - -Bolt supports two different options for this: -- Sequential versions -- Timestamp versions - -Sequential versions are incrementing integers. When you create a migration, it'll be prefixed with a number like "001", "002", and so on. Timestamp versions use the current time on migration creation as the prefix. - -### Why can't I change between version styles? - -The main reason that switching back and forth between "sequential" and "timestamp" versions is not supported is because Bolt will no longer know how to properly sort your migrations in the right order (and therefore, apply or revert them in the right order). If you've been using sequential migrations, such as "001" and "002", and then move over to timestamp migrations, such as "20200101000000", Bolt won't know how to order these correctly when both exist. Furthermore, because the "version" is parsed and sorted according to the version style that is configured, the parsing will fail if a mix of version styles are used. - -This means that if you wanted to switch version styles, you could do it manually by updating your local migrations to use the new version style and update the entries in `bolt_migrations` to match, but there is no tooling support for doing this change. - -### How is the migration message used? - -All migrations are created on the local filesystem in the format `<version>_<message>`. Bolt uses the `<version>` part of the name for keeping track of the migrations and how they should be applied or reverted. The `<message>` part is purely informational so you know what that migration is for. - -### What restrictions are there on the custom migration table? +## Contributing -While you can configure the database table that bolt uses for keeping track of applied migrations, there are restrictions on the name that can be used. It must only contain alphanumeric or underscore characters (e.g. `my_custom_table`). Furthermore, it _may_ contain one dot (`.`) if you would like to specify a different schema (e.g. `different_schema.my_custom_table`). However, do note that using a custom schema is only support with MSSQL and PostgreSQL since MySQL and SQlite3 both don't support schemas. +For information on how to contribute to Bolt, see the [Contributing Guide](https://eugenetriguba.srht.site/bolt/contributing/). -## Contributing +## License -For information on how to contribute to Bolt, see the [Contributing -Guide](./CONTRIBUTING.md). +MIT License - see [LICENSE](LICENSE) file for details. diff --git a/CONTRIBUTING.md b/docs/contributing.md index 00e7363..00e7363 100644 --- a/CONTRIBUTING.md +++ b/docs/contributing.md diff --git a/docs/explanation.md b/docs/explanation.md new file mode 100644 index 0000000..d01eb90 --- /dev/null +++ b/docs/explanation.md @@ -0,0 +1,286 @@ +# 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, particularly 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. Always test your migrations and have a backup strategy. + +### 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 + +### Why Not Use Migration Names? + +Bolt uses only the version portion of the migration filename (e.g., `20240316145038` from `20240316145038_create_users.sql`) for tracking. The descriptive message portion is purely for human readability and 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 +3. **Comparison**: Bolt queries the tracking table to determine which migrations haven't been applied +4. **Sorting**: Pending migrations are sorted by version (oldest first) +5. **Execution**: For each pending migration: + - The file is read and parsed to extract the `-- migrate:up` portion + - A 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 + +### Applying to a Specific Version + +When you specify a target version with `bolt up -v <version>`: + +- Only migrations with versions less than or equal to the target are considered +- Migrations are still applied in order from oldest to newest +- The process stops after applying the target version (or before if an error occurs) + +## 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. **Sorting**: Applied migrations are sorted by version (newest first for reverting) +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 + - 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 +6. **Reporting**: Success or failure is reported for each migration + +### Reverting to a Specific Version + +When you specify a target version with `bolt down -v <version>`: + +- All migrations with versions greater than or equal to the target are reverted +- Migrations are reverted in order from newest to oldest +- The process stops after reverting the target version + +### 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 + + This is one reason why migration files should be committed to version control and never deleted. + +## 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 +- Determine the order in which migrations should be applied or reverted +- Track which migrations have been applied + +Bolt supports two version styles: + +### Timestamp Versions + +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 + +**Best for:** +- Teams with multiple developers +- Distributed development where migrations may be created simultaneously on different branches +- When you want to know when a migration was created + +### Sequential Versions + +Format: Zero-padded integers (e.g., `001`, `002`, `003`) + +The version is simply an incrementing counter. + +**Best for:** +- Solo developers +- Small teams with linear development workflows +- When you prefer simple, easy-to-remember version numbers + +## Why can't I change between version styles? + +Switching between version styles after you have existing migrations is not supported for several important reasons: + +### Sorting Ambiguity + +Bolt needs to sort migrations to determine the correct application order. Consider this scenario: + +``` +001_first_migration.sql +002_second_migration.sql +20240316145038_third_migration.sql +``` + +How should these be sorted? As strings: +- `001` comes before `002` comes before `20240316145038` ✓ + +But what if you had: +``` +001_first_migration.sql +20240316145038_second_migration.sql +002_third_migration.sql +``` + +Now the string sorting would be: +- `001`, then `002`, then `20240316145038` + +But the chronological creation order was: +- `001`, then `20240316145038`, then `002` + +This creates ambiguity about the intended order. + +### Parsing Complexity + +Bolt parses version numbers according to the configured version style: +- **Timestamp style**: Expects exactly 14 digits in `YYYYMMDDHHMMSS` format +- **Sequential style**: Expects an integer (any length) + +If you mix styles, Bolt cannot reliably parse version numbers, leading to potential errors or incorrect ordering. + +### Manual Migration Path + +If you absolutely need to change version styles: + +1. Export your current migration state +2. Rename all migration files to use the new version style +3. Update all version entries in the tracking table to match +4. Update your `bolt.toml` or environment variables +5. Verify the migrations are correctly ordered with `bolt status` + +!!! warning + This is an advanced operation and should be done carefully, preferably with database backups. + +## How is the migration message used? + +When you create a migration with `bolt new -m "create users table"`, the resulting file is named: + +``` +20240316145038_create_users_table.sql +``` + +The format is: `<version>_<message>.sql` + +### Purpose of the Message + +The message serves several purposes: + +1. **Human readability**: Makes it easy to understand what a migration does without opening the file +2. **File organization**: Helps you quickly find migrations in your editor or file browser +3. **Code review**: Makes git diffs and pull requests more understandable +4. **Documentation**: Serves as lightweight documentation of your schema changes + +### What the Message is NOT Used For + +- **Tracking**: Bolt uses only the version portion for tracking applied migrations +- **Ordering**: The message has no impact on migration order +- **Uniqueness**: Two migrations can have the same message (though different versions) + +### Message Formatting + +When you provide a message: +- Spaces are converted to underscores +- Special characters may be sanitized +- The message becomes part of the filename + +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 +- Follow your database's table naming rules + +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 (use databases instead) +- ✗ **SQLite**: Does not support schemas + +### Why These Restrictions? + +These restrictions exist to: +- Ensure cross-database compatibility +- Prevent SQL injection risks +- Avoid parsing ambiguities +- Follow database best practices + +### 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 new file mode 100644 index 0000000..5d59a39 --- /dev/null +++ b/docs/how-to.md @@ -0,0 +1,116 @@ +# 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 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 + +Instead of using a `bolt.toml` file, you can configure Bolt using environment variables. This is particularly useful for CI/CD environments or when you want to keep sensitive information out of configuration files. + +### Available environment variables + +- `BOLT_MIGRATIONS_DIR_PATH` - The directory where your migration scripts are located +- `BOLT_MIGRATIONS_VERSION_STYLE` - The migration versioning style (`timestamp` or `sequential`) +- `BOLT_DB_DSN` - The database connection string (DSN) +- `BOLT_DB_DRIVER` - The database driver (`postgresql`, `mysql`, `mssql`, or `sqlite3`) +- `BOLT_DB_MIGRATIONS_TABLE` - The name of the migrations tracking table + +### Example + +```bash +export BOLT_DB_DSN="postgresql://user:password@localhost:5432/mydb?sslmode=disable" +export BOLT_DB_DRIVER="postgresql" +bolt up +``` + +!!! 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] +dsn = "postgresql://user:password@localhost:5432/mydb" +driver = "postgresql" +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" +``` + +!!! warning "Restrictions" + The migrations table name must only contain alphanumeric characters or underscores (e.g., `my_custom_table`). It may contain one dot (`.`) if specifying a schema, but custom schemas are only supported with PostgreSQL and MSSQL. + +## 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 cannot change version styles once you have existing migrations. Mixing timestamp and sequential versions is not supported. See the [Explanation](explanation.md#why-cant-i-change-between-version-styles) section for more details. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..c14c32c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,90 @@ +# Bolt + + +[](https://builds.sr.ht/~eugenetriguba/bolt/commits/main?) +[](https://godoc.org/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 + +- **Plain SQL migrations** - Schema migrations are written in plain SQL +- **Flexible versioning** - Migrations can be versioned sequentially or by creation timestamp +- **Transactional by default** - All migrations run in transactions by default +- **Bidirectional migrations** - Supports up and down migrations and jumping to any particular schema version +- **Multi-database support** - Supports PostgreSQL, MySQL, SQL Server, and SQLite3 + +## Quick Start + +### Install Bolt + +=== "Go install" + + ```bash + go install git.sr.ht/~eugenetriguba/bolt/cmd/bolt@latest + ``` + + This will install Bolt to your `$GOBIN` directory. Make sure that `$GOBIN` is in your `$PATH`. + +=== "Homebrew" + + ```bash + brew tap eugenetriguba/bolt https://git.sr.ht/~eugenetriguba/homebrew-bolt + brew install bolt + ``` + +### 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 + +- Follow the complete [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 + +## Getting Help + +- Read the [documentation](https://eugenetriguba.srht.site/bolt/) +- Check the [issue tracker](https://todo.sr.ht/~eugenetriguba/bolt) +- View the [source code](https://git.sr.ht/~eugenetriguba/bolt) diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..c089c3e --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,36 @@ +# 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@latest +``` + +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 new file mode 100644 index 0000000..ac3147d --- /dev/null +++ b/docs/reference.md @@ -0,0 +1,346 @@ +# Reference + +This section provides detailed reference information for Bolt's commands, configuration options, and supported databases. + +## Database Compatibility + +Bolt supports the following databases: + +- **PostgreSQL** - All recent versions +- **MySQL** - All recent versions +- **Microsoft SQL Server** - All recent versions +- **SQLite3** - All recent versions + +## 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:** + +``` +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 either a `bolt.toml` configuration file or environment variables. Environment variables take precedence over configuration file settings. + +### 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". +# +# Note: It is not supported to change migration version styles +# i.e. you can't have a mix of sequential and timestamp migrations. +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://pkg.go.dev/github.com/jackc/pgx/v5#hdr-Connection_String_Parameters) + +**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" +``` + +### Security Notes + +!!! warning "Security Best Practices" + - Never commit DSN strings containing passwords to version control + - Use environment variables for sensitive connection information + - For PostgreSQL and MySQL, always use SSL/TLS in production (`sslmode=require` for PostgreSQL, `tls=true` for MySQL) + - Use dedicated database users with minimal required permissions for migrations + +## Script Execution Options + +Bolt provides options to customize how migration scripts are executed. + +Options are added to the `-- migrate:up` or `-- migrate:down` comments: + +```sql +-- migrate:up <option1> <option2> +-- migrate:down <option1> <option2> +``` + +### Available Options + +#### `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; +``` + +**When to use:** +- PostgreSQL `CREATE INDEX CONCURRENTLY` operations +- Operations that cannot run within a transaction in your database +- When you need to handle transactions manually within your script + +## Version Styles + +Bolt supports two migration versioning styles: + +### Timestamp (Default) + +Migrations are versioned using timestamps (e.g., `20240316145038`). + +**Advantages:** +- Works well in teams where multiple developers create migrations simultaneously +- Timestamp indicates when the migration was created +- Less likely to have version conflicts + +**Configuration:** +```toml +[migrations] +version_style = "timestamp" +``` + +### Sequential + +Migrations are versioned using incrementing integers (e.g., `001`, `002`, `003`). + +**Advantages:** +- Simpler, more readable version numbers +- Easier to reference in conversation ("migration 5") +- Works well for solo developers or small teams with linear development + +**Configuration:** +```toml +[migrations] +version_style = "sequential" +``` + +!!! danger "Important" + You cannot change version styles once you have existing migrations. Mixing version styles is not supported. See [Why can't I change between version styles?](explanation.md#why-cant-i-change-between-version-styles) for more details. diff --git a/docs/tutorial.md b/docs/tutorial.md new file mode 100644 index 0000000..73ebbf0 --- /dev/null +++ b/docs/tutorial.md @@ -0,0 +1,192 @@ +# 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 \ + -e POSTGRES_USER=bolt_user \ + -e POSTGRES_PASSWORD=bolt_password \ + -e POSTGRES_DB=bolt_tutorial_db \ + -p 5432:5432 \ + --detach postgres:16.1-alpine3.19 +``` + +## Configuring Bolt + +Bolt can be configured with a `bolt.toml` file or 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. 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) +``` + +## 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/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..8341794 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,52 @@ +site_name: Bolt +site_url: https://eugenetriguba.srht.site/bolt/ +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/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 0000000..1032aa3 --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1 @@ +mkdocs-material==9.6.21 diff --git a/scripts/deploy-docs.sh b/scripts/deploy-docs.sh new file mode 100755 index 0000000..c56bc5b --- /dev/null +++ b/scripts/deploy-docs.sh @@ -0,0 +1,47 @@ +#!/usr/bin/env bash +set -eou pipefail + +source "$(dirname "${BASH_SOURCE[0]}")/lib/log.sh" + +readonly SITE="eugenetriguba.srht.site/bolt" + +usage() { + echo "Usage: $0" + echo "" + echo "Build and deploy documentation to SourceHut Pages" + echo "" + echo "Examples:" + echo " $0 # Build and deploy docs to $SITE" +} + +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() { + if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then + usage + exit 0 + fi + + log_header "Deploying Documentation" + build_docs + package_site + deploy_to_pages +} + +main "$@" |