# 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" ```