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