aboutsummaryrefslogtreecommitdiffstats
path: root/man/bolt-databases.7
blob: 5526bba9178b8046acf501f87dc362f292715eee (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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