About dburl

Package dburl provides a standard, URL style mechanism for parsing and opening SQL database connection strings for Go. Provides standardized way to parse and open URLs for popular databases PostgreSQL, MySQL, SQLite3, Oracle Database, Microsoft SQL Server, in addition to most other SQL databases with a publicly available Go driver.

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/oleodbc)
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 is of the form /service/dbname where /service is the service name or SID, and /dbname is optional. Please see below for examples.

Quickstart

Database connection URLs in the above format can be parsed with the dburl.Parse func as such:

import (
    "github.com/xo/dburl"
)

u, err := dburl.Parse("postgresql://user:pass@localhost/mydatabase/?sslmode=disable")
if err != nil { /* ... */ }

Additionally, a simple helper, dburl.Open, is provided that will parse, open, and return a standard sql.DB database connection:

import (
    "github.com/xo/dburl"
)

db, err := dburl.Open("sqlite:mydatabase.sqlite3?loc=auto")
if err != nil { /* ... */ }

Example URLs

The following are example database connection URLs that can be handled by dburl.Parse and dburl.Open:

postgres://user:pass@localhost/dbname
pg://user:pass@localhost/dbname?sslmode=disable
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
sqlite:/path/to/file.db
file:myfile.sqlite3?loc=auto
odbc+postgres://user:pass@localhost:port/dbname?option1=

Database Schemes, Aliases, and Drivers

The following table lists the supported dburl protocol schemes (ie, driver), additional aliases, and the related Go driver:

Database	Scheme / Tag	Scheme Aliases	Driver Package / Notes
PostgreSQL	`postgres`	`pg`, `pgsql`, `postgresql`	github.com/lib/pq
MySQL	`mysql`	`my`, `maria`, `aurora`, `mariadb`, `percona`	github.com/go-sql-driver/mysql
Microsoft SQL Server	`sqlserver`	`ms`, `mssql`, `azuresql`	github.com/microsoft/go-mssqldb
Oracle Database	`oracle`	`or`, `ora`, `oci`, `oci8`, `odpi`, `odpi-c`	github.com/sijms/go-ora/v2
SQLite3	`sqlite3`	`sq`, `sqlite`, `file`	github.com/mattn/go-sqlite3 ^†
ClickHouse	`clickhouse`	`ch`	github.com/ClickHouse/clickhouse-go/v2
CSVQ	`csvq`	`cs`, `csv`, `tsv`, `json`	github.com/mithrandie/csvq-driver

Alibaba MaxCompute	`maxcompute`	`mc`	sqlflow.org/gomaxcompute
Alibaba Tablestore	`ots`	`ot`, `tablestore`	github.com/aliyun/aliyun-tablestore-go-sql-driver
Apache Avatica	`avatica`	`av`, `phoenix`	github.com/apache/calcite-avatica-go/v5
Apache H2	`h2`		github.com/jmrobles/h2go
Apache Hive	`hive`	`hi`, `hive2`	sqlflow.org/gohive
Apache Ignite	`ignite`	`ig`, `gridgain`	github.com/amsokol/ignite-go-client/sql
AWS Athena	`athena`	`s3`, `aws`, `awsathena`	github.com/uber/athenadriver/go
Azure CosmosDB	`cosmos`	`cm`	github.com/btnguyen2k/gocosmos
Cassandra	`cassandra`	`ca`, `scy`, `scylla`, `datastax`, `cql`	github.com/MichaelS11/go-cql-driver
ChaiSQL	`chai`	`ci`, `genji`, `chaisql`	github.com/chaisql/chai/driver
Couchbase	`couchbase`	`n1`, `n1ql`	github.com/couchbase/go_n1ql
Cznic QL	`ql`	`cznic`, `cznicql`	modernc.org/ql
Databend	`databend`	`dd`, `bend`	github.com/datafuselabs/databend-go
Databricks	`databricks`	`br`, `brick`, `bricks`, `databrick`	github.com/databricks/databricks-sql-go
DuckDB	`duckdb`	`dk`, `ddb`, `duck`, `file`	github.com/marcboeker/go-duckdb ^†
DynamoDb	`dynamodb`	`dy`, `dyn`, `dynamo`, `dynamodb`	github.com/btnguyen2k/godynamo
Exasol	`exasol`	`ex`, `exa`	github.com/exasol/exasol-driver-go
Firebird	`firebird`	`fb`, `firebirdsql`	github.com/nakagami/firebirdsql
FlightSQL	`flightsql`	`fl`, `flight`	github.com/apache/arrow/go/v12/arrow/flight/flightsql/driver
Google BigQuery	`bigquery`	`bq`	gorm.io/driver/bigquery/driver
Google Spanner	`spanner`	`sp`	github.com/googleapis/go-sql-spanner
Microsoft ADODB	`adodb`	`ad`, `ado`	github.com/mattn/go-adodb
ModernC SQLite3	`moderncsqlite`	`mq`, `modernsqlite`	modernc.org/sqlite
MySQL MyMySQL	`mymysql`	`zm`, `mymy`	github.com/ziutek/mymysql/godrv
Netezza	`netezza`	`nz`, `nzgo`	github.com/IBM/nzgo/v12
PostgreSQL PGX	`pgx`	`px`	github.com/jackc/pgx/v5/stdlib
Presto	`presto`	`pr`, `prs`, `prestos`, `prestodb`, `prestodbs`	github.com/prestodb/presto-go-client/presto
RamSQL	`ramsql`	`rm`, `ram`	github.com/proullon/ramsql/driver
SAP ASE	`sapase`	`ax`, `ase`, `tds`	github.com/thda/tds
SAP HANA	`saphana`	`sa`, `sap`, `hana`, `hdb`	github.com/SAP/go-hdb/driver
Snowflake	`snowflake`	`sf`	github.com/snowflakedb/gosnowflake
Trino	`trino`	`tr`, `trs`, `trinos`	github.com/trinodb/trino-go-client/trino
Vertica	`vertica`	`ve`	github.com/vertica/vertica-sql-go
VoltDB	`voltdb`	`vo`, `vdb`, `volt`	github.com/VoltDB/voltdb-client-go/voltdbclient
YDB	`ydb`	`yd`, `yds`, `ydbs`	github.com/ydb-platform/ydb-go-sdk/v3

GO DRiver for ORacle	`godror`	`gr`	github.com/godror/godror ^†
ODBC	`odbc`	`od`	github.com/alexbrainman/odbc ^†

Amazon Redshift	`postgres`	`rs`, `redshift`	github.com/lib/pq ^‡
CockroachDB	`postgres`	`cr`, `cdb`, `crdb`, `cockroach`, `cockroachdb`	github.com/lib/pq ^‡
OLE ODBC	`adodb`	`oo`, `ole`, `oleodbc`	github.com/mattn/go-adodb ^‡
SingleStore MemSQL	`mysql`	`me`, `memsql`	github.com/go-sql-driver/mysql ^‡
TiDB	`mysql`	`ti`, `tidb`	github.com/go-sql-driver/mysql ^‡
Vitess Database	`mysql`	`vt`, `vitess`	github.com/go-sql-driver/mysql ^‡

Apache Impala	`impala`	`im`	github.com/bippio/go-impala

^† Requires CGO
^‡ Wire compatible (see respective driver)

Any protocol scheme alias:// can be used in place of protocol://, and will work identically with dburl.Parse and dburl.Open.

Installing

Install in the usual Go fashion:

$ go get github.com/xo/dburl@latest

Using

dburl does not import any of Go's SQL drivers, as it only provides a way to parse and open database URL stylized connection strings. As such, it is necessary to explicitly import the relevant SQL driver:

import (
    // import Microsoft SQL Server driver
    _ "github.com/microsoft/go-mssqldb"
)

See the database schemes table above for a list of the expected Go driver import's.

Additional examples and API details can be found in the dburl package documentation.

URL Parsing Rules

dburl.Parse and dburl.Open rely primarily on Go's standard net/url.URL type, and as such, parsing or opening database connection URLs with dburl are subject to the same rules, conventions, and semantics as Go's net/url.Parse func.

Example

A full example for reference:

// _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

By default on non-Windows systems, dburl will resolve paths on disk, and URLs with file: schemes to an appropriate database driver:

Directories will resolve as postgres: URLs
Unix sockets will resolve as mysql: URLs
Regular files will have their headers checked to determine if they are either sqlite3: or duckdb: files
Non-existent files will test their file extension against well-known sqlite3: and duckdb: file extensions and open with the appropriate scheme

If this behavior is undesired, it can be disabled by providing different implementations for dburl.Stat and dburl.OpenFile, or alternately by setting dburl.ResolveSchemeType to false:

import "github.com/xo/dburl"

func init() {
    dburl.ResolveSchemeType = false
}

About

dburl was built primarily to support these projects:

usql - a universal command-line interface for SQL databases
xo - a command-line tool to generate code for SQL databases