aboutsummaryrefslogtreecommitdiffstats
path: root/man/bolt-databases.7
diff options
context:
space:
mode:
Diffstat (limited to 'man/bolt-databases.7')
-rw-r--r--man/bolt-databases.7145
1 files changed, 145 insertions, 0 deletions
diff --git a/man/bolt-databases.7 b/man/bolt-databases.7
new file mode 100644
index 0000000..5526bba
--- /dev/null
+++ b/man/bolt-databases.7
@@ -0,0 +1,145 @@
+.Dd February 12, 2026
+.Dt BOLT-DATABASES 7
+.Os
+.Sh NAME
+.Nm bolt-databases
+.Nd database drivers and connection strings
+.Sh DESCRIPTION
+.Xr bolt 1
+uses Data Source Name (DSN) strings for database connections. A DSN 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.
+.Pp
+This document describes the supported databases and their connection string formats.
+.Sh COMPATIBILITY
+.Bl -tag -width 2Ds
+.It PostgreSQL
+Version 13 and later.
+.It MySQL
+Version 5.7 and later.
+.It SQL Server
+Version 2017 and later.
+.It SQLite
+Latest version.
+.Pp
+For SQLite, we only explicitly run our test suite against the latest version of
+SQLite, so I find it hard to claim support for anything more. That said, SQLite
+is an incredibly stable piece of software, and I'd find it unlikely any recent
+version would have any issue. If you have an issue on any version, please file
+a bug report.
+.El
+.Sh POSTGRESQL
+.Ss Driver:
+.Lk https://github.com/jackc/pgx pgx
+.Pp
+The connection string follows the libpq format. For a complete list of supported
+options, see the PostgreSQL libpq documentation:
+.Lk https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS
+.Pp
+.Ss Format:
+.Pp
+postgresql://username:password@hostname:port/database?options
+.Pp
+The keyword=value format is also supported:
+.Bd -literal -offset indent -compact
+host=hostname port=5432 dbname=database user=username password=password
+.Ed
+.Pp
+.Ss Examples:
+.Bl -ohang
+.It Sy Basic connection
+.Li postgresql://user:password@localhost:5432/mydb
+.It Sy With SSL disabled
+.Li postgresql://user:password@localhost:5432/mydb?sslmode=disable
+.It Sy With multiple options
+.Li postgresql://user:password@localhost:5432/mydb?sslmode=require&connect_timeout=10&application_name=bolt
+.It Sy Using Unix socket
+.Li postgresql://user:password@/mydb?host=/var/run/postgresql
+.El
+.Sh MYSQL
+.Ss Driver:
+.Lk https://github.com/go-sql-driver/mysql go-sql-driver/mysql
+.Pp
+For a complete list of supported options, see the driver DSN documentation:
+.Lk https://github.com/go-sql-driver/mysql#dsn-data-source-name
+.Pp
+.Ss Format:
+.Pp
+username:password@protocol(address)/database?options
+.Pp
+.Ss Examples:
+.Bl -ohang
+.It Sy Basic connection
+.Li user:password@tcp(localhost:3306)/mydb
+.It Sy With parse time and charset
+.Li user:password@tcp(localhost:3306)/mydb?parseTime=true&charset=utf8mb4
+.It Sy With connection timeout and TLS
+.Li user:password@tcp(localhost:3306)/mydb?timeout=10s&tls=true
+.It Sy Using Unix socket
+.Li user:password@unix(/tmp/mysql.sock)/mydb
+.El
+.Sh SQL SERVER
+.Ss Driver:
+.Lk https://github.com/microsoft/go-mssqldb go-mssqldb
+.Pp
+For a complete list of supported parameters, see the driver documentation:
+.Lk https://github.com/microsoft/go-mssqldb#connection-parameters-and-dsn
+.Pp
+.Ss Format:
+.Pp
+sqlserver://username:password@hostname:port?database=database&options
+.Pp
+.Ss Examples:
+.Bl -ohang
+.It Sy Basic connection
+.Li sqlserver://user:password@localhost:1433?database=mydb
+.It Sy With encryption and timeout
+.Li sqlserver://user:password@localhost:1433?database=mydb&encrypt=disable&connection+timeout=30
+.It Sy With instance name
+.Li sqlserver://user:password@localhost/SQL_EXPRESS?database=mydb
+.It Sy Windows authentication
+.Li sqlserver://localhost:1433?database=mydb&trusted_connection=yes
+.El
+.Sh SQLITE
+.Ss Driver:
+.Lk https://github.com/mattn/go-sqlite3 go-sqlite3
+.Pp
+For a complete list of supported parameters, see the driver documentation:
+.Lk https://github.com/mattn/go-sqlite3#connection-string
+.Pp
+.Ss Format:
+.Pp
+/path/to/database.db?options
+.Pp
+.Ss Examples:
+.Bl -ohang
+.It Sy File-based database
+.Li /path/to/mydatabase.db
+.It Sy In-memory database
+.Li :memory:
+.It Sy Read-only mode
+.Li /path/to/mydatabase.db?mode=ro
+.It Sy With foreign keys enabled
+.Li /path/to/mydatabase.db?_foreign_keys=on
+.El
+.Sh CONFIGURATION
+Set the DSN and driver in
+.Pa bolt.toml :
+.Bd -literal -offset indent
+[database]
+dsn = "postgresql://user:password@localhost:5432/mydb"
+driver = "postgresql"
+.Ed
+.Pp
+Or via environment variables:
+.Bd -literal -offset indent
+export BOLT_DB_DSN="postgresql://user:password@localhost:5432/mydb"
+export BOLT_DB_DRIVER="postgresql"
+.Ed
+.Sh SEE ALSO
+.Xr bolt 1 ,
+.Xr bolt.toml 5 ,
+.Xr psql 1 ,
+.Xr mysql 1 ,
+.Xr sqlite3 1
+