aboutsummaryrefslogtreecommitdiffstats
path: root/docs/reference.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/reference.md')
-rw-r--r--docs/reference.md192
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.