Bolt

Bolt is a command-line tool designed to simplify and streamline your database migration process. 🌟 Key Features: - **SQL-Powered Flexibility**: 🧩 - Write your migration scripts in plain SQL. This gives you the full power and familiarity of SQL, ensuring that you're not limited by the constraints of a specific DSL (Domain Specific Language). - **Bidirectional Migrations**: 🔀 - With support for both 'up' (migrating) and 'down' (downgrading) migrations, Bolt provides complete control over your database versions. This feature is essential for maintaining database integrity and for executing seamless rollbacks whenever necessary. - **Time-Travel with Ease**: ⏳ - Migrate or downgrade to any specific point in time. Bolt allows you to specify a specific migration version to migrate or downgrade to, allowing you to easily time-travel to any point in your database's history. - **Safe and Reliable**: 🛡️ - Built with safety and reliability in mind, Bolt ensures your migrations are executed smoothly, with clear logging and error handling. ## Table of Contents - [Installation](#installation) - [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) - [Commands](#commands) - [`bolt new`](#bolt-new) - [`bolt up`](#bolt-up) - [`bolt down`](#bolt-down) - [`bolt status`](#bolt-status) - [Script Execution Options](#script-execution-options) - [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) ## Installation To install Bolt, run the following command: ```bash $ go install github.com/eugenetriguba/bolt@latest ``` This will install Bolt to your `$GOBIN` directory. Make sure that `$GOBIN` is in your `$PATH`. ## 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: ```bash $ bolt new -m "my first migration" ``` Upon completion, a migrations directory will be created with the following structure: ```bash migrations/ └── 20240113162817_my_first_migration ├── downgrade.sql └── upgrade.sql 1 directories, 2 files ``` 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 `upgrade.sql` for applying migrations and `downgrade.sql` for reverting them. 1. Write the Upgrade Script Edit `upgrade.sql` with the following SQL command to create a new table: ```sql 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() ); ``` 2. Write the Downgrade Script Edit `downgrade.sql` with the following SQL command to remove the table: ```sql 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 [bolt.db.connection] host = "localhost" port = 5432 user = "bolt_user" password = "bolt_password" dbname = "bolt_tutorial_db" driver = "postgres" ``` ### Applying your migration Apply your migration, which will execute the `upgrade.sql` script: ```bash $ bolt up Applying migration 20240113162817_my_first_migration.. Successfully applied migration 20240113162817_my_first_migration! ``` ### Checking Migration Status To view the status of your migration: ```bash $ bolt status Version Message Applied 20240113162817 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 20240113162817_my_first_migration.. Successfully reverted migration 20240113162817_my_first_migration! ``` ### 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 [Reference](#reference) or [Explanation](#explanation) section. ## How-to ### How to execute a migration script without a transaction In your `upgrade.sql` or `downgrade.sql`, add the following line as the first line of your script: ```sql -- bolt: no-transaction ``` ## Reference ### Database Compatibility At the moment, only PostgreSQL is supported. You're welcome to contribute support for other databases. ### 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 take precedence. #### Configuration File Bolt attempts to find a `bolt.toml` file in your current working directory or in any parent directory. ```toml [bolt.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" # Connection parameters for the database Bolt will be # applying migrations to. All connection parameters are # required. [bolt.db.connection] # The host to use to connect to your database. host = # The port to use to connect to your database. # Note: This should be an integer. port = # The user to use to connect to your database. user = # The password to use to connect to your database. password = # The name of the database within your DBMS. dbname = # The name of the database driver to use to connect to # the database. At the moment, only "postgres" is supported. driver = ``` #### Environment Variables All configuration file settings have corresponding environment variables. - `BOLT_MIGRATIONS_DIR_PATH` - `BOLT_DB_CONN_HOST` - `BOLT_DB_CONN_PORT` - `BOLT_DB_CONN_USER` - `BOLT_DB_CONN_PASSWORD` - `BOLT_DB_CONN_DBNAME` - `BOLT_DB_CONN_DRIVER` ### 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 up 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 ``` ### Script Execution Options Bolt provides a way for you to customize how your migration scripts are executed if you need something different than the default behavior. You can do this by adding a comment to the top of your migration script. The comment must be in the following format: `-- bolt: