From 5264264333f211c9d40108955e167d28fa73f77d Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Wed, 23 Jul 2025 21:39:11 -0400 Subject: Use DSN for handling connection parameters --- README.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 143 insertions(+), 25 deletions(-) (limited to 'README.md') 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` -- cgit v1.2.3