diff options
Diffstat (limited to 'docs/reference.md')
| -rw-r--r-- | docs/reference.md | 446 |
1 files changed, 0 insertions, 446 deletions
diff --git a/docs/reference.md b/docs/reference.md deleted file mode 100644 index 595a0a4..0000000 --- a/docs/reference.md +++ /dev/null @@ -1,446 +0,0 @@ -# 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] <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:** - -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: <version_A>, <version_B> -``` - -### `-- 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" -``` |