About dburl

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:

^* 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. A parsed URL names the scheme in URL.SchemeName and the name to pass to sql.Open in URL.Driver. The two differ when a scheme opens a driver that another product also uses: tidb opens mysql, postgres, cockroachdb and redshift open pgx, and pq opens postgres, which is the name that github.com/lib/pq registers. dburl.Open passes URL.Driver to sql.Open:

^† Requires CGO
^§ 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:

1. A directory resolves as a postgres: URL.
2. A Unix socket resolves as a mysql: URL.
3. For a file that exists, dburl reads the file header and resolves it as a sqlite3: or a duckdb: URL.
4. For a file that does not exist, dburl matches the file extension against the known sqlite3: and duckdb: 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:

• usql - a universal command-line interface for SQL databases
• dbtpl - a command-line tool to generate code for SQL databases
• dbmeta - a Go package that reads metadata from SQL databases