diff options
Diffstat (limited to 'docs/reference.md')
| -rw-r--r-- | docs/reference.md | 346 |
1 files changed, 346 insertions, 0 deletions
diff --git a/docs/reference.md b/docs/reference.md new file mode 100644 index 0000000..ac3147d --- /dev/null +++ b/docs/reference.md @@ -0,0 +1,346 @@ +# 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] <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:** + +``` +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 <option1> <option2> +-- migrate:down <option1> <option2> +``` + +### 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. |