About dburl
September 27, 2026 · View on GitHub
Package dburl parses and opens SQL database
connection strings for Go, in a standard URL style. It handles
the URL formats of PostgreSQL, MySQL, SQLite3, Oracle Database and Microsoft
SQL Server. It also handles most other SQL databases that have a public Go
driver.
Overview | Quickstart | Examples | Schemes | Installing | Using | About
Database Connection URL Overview
Supported database connection URLs are of the form:
protocol+transport://user:pass@host/dbname?opt1=a&opt2=b
protocol:/path/to/file
Where:
| Component | Description |
|---|---|
| protocol | driver name or alias (see below) |
| transport | "tcp", "udp", "unix" or driver name (odbc) |
| user | username |
| pass | password |
| host | host |
| dbname* | database, instance, or service name/ID to connect to |
| ?opt1=... | additional database driver options (see respective SQL driver for available options) |
* For Microsoft SQL Server, /dbname can be
/instance/dbname, where /instance is optional. For Oracle Database,
/dbname takes the form /service/dbname. Here /service is the service
name or SID, and /dbname is optional. See the examples below.
Quickstart
The dburl.Parse func parses a database connection URL in the
format above:
import (
"github.com/xo/dburl"
)
u, err := dburl.Parse("postgresql://user:pass@localhost/mydatabase/?sslmode=disable")
if err != nil { /* ... */ }
dburl.Open parses the URL and returns an open
standard sql.DB database connection:
import (
"github.com/xo/dburl"
)
db, err := dburl.Open("sqlite:mydatabase.sqlite3?loc=auto")
if err != nil { /* ... */ }
Example URLs
dburl.Parse and dburl.Open handle database
connection URLs such as these:
postgres://user:pass@localhost/dbname
pg://user:pass@localhost/dbname?sslmode=disable
pq://user:pass@localhost/dbname
mysql://user:pass@localhost/dbname
mysql:/var/run/mysqld/mysqld.sock
sqlserver://user:pass@remote-host.com/dbname
mssql://user:pass@remote-host.com/instance/dbname
ms://user:pass@remote-host.com:port/instance/dbname?keepAlive=10
oracle://user:pass@somehost.com/sid
sap://user:pass@localhost/dbname
cassandra://user:pass@localhost/keyspace?consistency=localQuorum
sqlite:/path/to/file.db
file:myfile.sqlite3?loc=auto
odbc+postgres://user:pass@localhost:port/dbname?option1=
Database Schemes, Aliases, and Drivers
The table lists every supported dburl protocol scheme, with its aliases and
its Go driver. The scheme is usually also the driver name that dburl returns.
A row marked ‡ uses the driver of another row, and pq returns postgres,
which is the name that github.com/lib/pq registers:
† Requires CGO
‡ Uses the driver of another row, as a wire compatible database does
§ Embedded, with no server to run
¶ Hosted service, with no server you can run
You can write any alias as alias:// in place of protocol://.
dburl.Parse and dburl.Open treat the two the
same.
Installing
Install dburl with go get:
$ go get github.com/xo/dburl@latest
Using
dburl does not import any Go SQL driver. It only parses and
opens database connection URLs, so you must import the SQL
driver yourself:
import (
// import Microsoft SQL Server driver
_ "github.com/microsoft/go-mssqldb"
)
See the database schemes table above for the Go driver that each scheme expects.
The dburl package documentation has more examples and the API
details.
URL Parsing Rules
dburl.Parse and dburl.Open build on Go's
standard net/url.URL type. The same rules and conventions
apply as for Go's net/url.Parse func.
Example
A full example:
// _example/example.go
package main
import (
"fmt"
"log"
_ "github.com/microsoft/go-mssqldb"
"github.com/xo/dburl"
)
func main() {
db, err := dburl.Open("sqlserver://user:pass@localhost/dbname")
if err != nil {
log.Fatal(err)
}
var name string
if err := db.QueryRow(`SELECT name FROM mytable WHERE id=10`).Scan(&name); err != nil {
log.Fatal(err)
}
fmt.Println("name:", name)
}
Scheme Resolution
On systems other than Windows, dburl resolves a path on disk, or a URL with
a file: scheme, to a database driver:
- A directory resolves as a
postgres:URL. - A Unix socket resolves as a
mysql:URL. - For a file that exists,
dburlreads the file header and resolves it as asqlite3:or aduckdb:URL. - For a file that does not exist,
dburlmatches the file extension against the knownsqlite3:andduckdb:extensions.
To turn this off, set dburl.ResolveSchemeType to false.
You can also supply your own dburl.Stat and
dburl.OpenFile funcs instead:
import "github.com/xo/dburl"
func init() {
dburl.ResolveSchemeType = false
}
About
dburl exists to support these projects: