diff options
Diffstat (limited to 'docs/reference.md')
| -rw-r--r-- | docs/reference.md | 192 |
1 files changed, 146 insertions, 46 deletions
diff --git a/docs/reference.md b/docs/reference.md index ac3147d..595a0a4 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1,15 +1,17 @@ # Reference -This section provides detailed reference information for Bolt's commands, configuration options, and supported databases. +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 +- **PostgreSQL** - 13+ +- **MySQL** - 5.7+ +- **Microsoft SQL Server** - 2017+ +- **SQLite3** - All recent versions. We explicitly test against the latest + version. ## Commands @@ -88,6 +90,9 @@ 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 @@ -104,11 +109,14 @@ 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. +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. +Bolt searches for a `bolt.toml` file in your current working directory or any +parent directory. **Complete example:** @@ -122,9 +130,6 @@ 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] @@ -162,15 +167,20 @@ 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. +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. +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) +**Driver:** [pgx](https://github.com/jackc/pgx) + +[DSN Documentation](https://github.com/jackc/pgx/blob/v5.7.6/pgxpool/pool.go#L352) **Format:** ``` @@ -195,7 +205,9 @@ 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) +**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:** ``` @@ -220,7 +232,9 @@ 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) +**Driver:** [microsoft/go-mssqldb](https://github.com/microsoft/go-mssqldb) + +[DSN Documentation](https://github.com/microsoft/go-mssqldb#connection-parameters-and-dsn) **Format:** ``` @@ -245,7 +259,9 @@ 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) +**Driver:** [mattn/go-sqlite3](https://github.com/mattn/go-sqlite3) + +[DSN Documentation](https://github.com/mattn/go-sqlite3#connection-string) **Format:** ``` @@ -268,30 +284,132 @@ dsn = "/path/to/mydatabase.db?mode=ro" dsn = "/path/to/mydatabase.db?_foreign_keys=on" ``` -### Security Notes +## 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 +``` -!!! 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 +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> +``` -## Script Execution Options +### `-- migrate:up` and `-- migrate:down` -Bolt provides options to customize how migration scripts are executed. +These directives separate the upgrade and downgrade portions of your migration. -Options are added to the `-- migrate:up` or `-- migrate:down` comments: +**Syntax:** +```sql +-- migrate:up [option1] [option2] +-- migrate:down [option1] [option2] +``` +**Example:** ```sql --- migrate:up <option1> <option2> --- migrate:down <option1> <option2> +-- 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. +Execute the migration script without a transaction. By default, every +migration script is executed within a transaction. **Example:** @@ -303,11 +421,6 @@ CREATE INDEX CONCURRENTLY idx_users_email ON users(email); 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: @@ -316,11 +429,6 @@ Bolt supports two migration versioning styles: 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] @@ -331,16 +439,8 @@ version_style = "timestamp" 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. |