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.

bolt new [-message|-m] <message>

Options:

-message <message> - Message to use for the migration (default: "autogenerated")
-m <message> - Alias for -message

Example:

bolt new -m "create users table"

`bolt up`¶

Apply migrations against the database.

bolt up [-version|-v] <version>

Options:

-version <version> - The version to upgrade up to and including (optional)
-v <version> - Alias for -version

Examples:

# 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.

bolt down [-version|-v] <version>

Options:

-version <version> - The version to downgrade down to and including (optional)
-v <version> - Alias for -version

Examples:

# 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.

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.

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:

[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:

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

DSN Documentation

Format:

postgresql://username:password@hostname:port/database?option1=value1&option2=value2

Examples:

# 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

DSN Documentation

Format:

username:password@tcp(hostname:port)/database?option1=value1&option2=value2

Examples:

# 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

DSN Documentation

Format:

sqlserver://username:password@hostname:port?database=database&option1=value1&option2=value2

Examples:

# 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

DSN Documentation

Format:

/path/to/database.db?option1=value1&option2=value2

Examples:

# 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:

-- 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):

-- migrate:up
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255)
);

-- migrate:down
DROP TABLE users;

Single dependency:

-- 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:

-- 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:

bolt new -m "create users"
# Generated file has no -- depends: line

Second migration:

bolt new -m "create posts"
# Generated file has: -- depends: 20240316145038

After parallel migrations merge:

# If migrations A and B both exist and neither depends on the other
bolt new -m "create feature needing both"
# Generated file has: -- depends: <version_A>, <version_B>

`-- migrate:up` and `-- migrate:down`¶

These directives separate the upgrade and downgrade portions of your migration.

Syntax:

-- migrate:up [option1] [option2]
-- migrate:down [option1] [option2]

Example:

-- 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:

-- 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:

[migrations]
version_style = "timestamp"

Sequential¶

Migrations are versioned using incrementing integers (e.g., 001, 002, 003).

Configuration:

[migrations]
version_style = "sequential"

Reference¶

Database Compatibility¶

Commands¶

bolt new¶

bolt up¶

bolt down¶

bolt status¶

bolt version¶

Configuration¶

Configuration File¶

Environment Variables¶

Database Connection (DSN)¶

What is a DSN?¶

PostgreSQL¶

MySQL¶

SQL Server (MSSQL)¶

SQLite¶

Migration Script Directives¶

-- depends:¶

-- migrate:up and -- migrate:down¶

Available Options¶

transaction:false¶

Version Styles¶

Timestamp (Default)¶

Sequential¶

`bolt new`¶

`bolt up`¶

`bolt down`¶

`bolt status`¶

`bolt version`¶

`-- depends:`¶

`-- migrate:up` and `-- migrate:down`¶

`transaction:false`¶