# 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] ``` **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:** ``` 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 -- migrate:down ``` ### 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.