aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2025-07-23 21:39:11 -0400
committerEugene Triguba <hello@eugenetriguba.com>2025-07-23 21:39:11 -0400
commit5264264333f211c9d40108955e167d28fa73f77d (patch)
tree6801a3d0460360bff5bc0b76ac482fa774e97043 /README.md
parentFix contributing link (diff)
downloadcli-5264264333f211c9d40108955e167d28fa73f77d.zip
Use DSN for handling connection parameters
Diffstat (limited to 'README.md')
-rw-r--r--README.md168
1 files changed, 143 insertions, 25 deletions
diff --git a/README.md b/README.md
index c3022ae..0214c04 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,13 @@ It is distributed as a standalone binary, making it easy to run anywhere without
- [Configuration](#configuration)
- [Configuration File](#configuration-file)
- [Environment Variables](#environment-variables)
+ - [Database Connection (DSN)](#database-connection-dsn)
+ - [What is a DSN?](#what-is-a-dsn)
+ - [DSN Format Examples](#dsn-format-examples)
+ - [Environment Variable Examples](#environment-variable-examples)
+ - [Driver-Specific Considerations](#driver-specific-considerations)
+ - [Security Notes](#security-notes)
+ - [Migration from Individual Parameters](#migration-from-individual-parameters)
- [Commands](#commands)
- [`bolt new`](#bolt-new)
- [`bolt up`](#bolt-up)
@@ -175,11 +182,7 @@ $ touch bolt.toml
```toml
[database]
-host = "localhost"
-port = "5432"
-user = "bolt_user"
-password = "bolt_password"
-dbname = "bolt_tutorial_db"
+dsn = "postgresql://bolt_user:bolt_password@localhost:5432/bolt_tutorial_db?sslmode=disable"
driver = "postgresql"
```
@@ -300,24 +303,14 @@ directory_path = "migrations"
# i.e. you can't have a mix of sequential and timestamp migrations.
version_style = "timestamp"
-# Connection parameters for the database Bolt will be
-# applying migrations to. All connection parameters are
-# required.
+# Connection parameters for the database Bolt will be applying
+# migrations to.
[database]
-# The host to use to connect to your database.
-host =
-# The port to use to connect to your database.
-port =
-# The user to use to connect to your database.
-user =
-# The password to use to connect to your database.
-password =
-# The name of the database within your DBMS. If you're
-# using sqlite3, this is the filesystem path to the db.
-dbname =
+# 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 =
+driver = "postgresql"
# The name of the database table to create for managing
# the applied migration versions. Defaults to "bolt_migrations".
migrations_table = "bolt_migrations"
@@ -329,14 +322,139 @@ All configuration file settings have corresponding environment variables.
- `BOLT_MIGRATIONS_DIR_PATH`
- `BOLT_MIGRATIONS_VERSION_STYLE`
-- `BOLT_DB_HOST`
-- `BOLT_DB_PORT`
-- `BOLT_DB_USER`
-- `BOLT_DB_PASSWORD`
-- `BOLT_DB_NAME`
+- `BOLT_DB_DSN`
- `BOLT_DB_DRIVER`
- `BOLT_DB_MIGRATIONS_TABLE`
+### 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.
+
+#### DSN Format Examples
+
+##### PostgreSQL
+
+**Driver**: [pgx](https://github.com/jackc/pgx) - [DSN Documentation](https://pkg.go.dev/github.com/jackc/pgx/v5#hdr-Connection_String_Parameters)
+
+**Basic 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"
+```
+
+```bash
+export BOLT_DB_DSN="postgresql://user:password@localhost:5432/mydb?sslmode=disable"
+export BOLT_DB_DRIVER="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)
+
+**Basic 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"
+```
+
+```bash
+export BOLT_DB_DSN="user:password@tcp(localhost:3306)/mydb?parseTime=true"
+export BOLT_DB_DRIVER="mysql"
+```
+
+##### 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)
+
+**Basic 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"
+```
+
+```bash
+export BOLT_DB_DSN="sqlserver://user:password@localhost:1433?database=mydb"
+export BOLT_DB_DRIVER="mssql"
+```
+
+##### SQLite
+
+**Driver**: [mattn/go-sqlite3](https://github.com/mattn/go-sqlite3) - [DSN Documentation](https://github.com/mattn/go-sqlite3#connection-string)
+
+**Basic 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"
+```
+
+```bash
+export BOLT_DB_DSN="/path/to/database.db"
+export BOLT_DB_DRIVER="sqlite3"
+```
+
### Commands
#### `bolt new`