README.md

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.

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/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:[email protected]/dbname
mssql://user:[email protected]/instance/dbname
ms://user:[email protected]:port/instance/dbname?keepAlive=10
oracle://user:[email protected]/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/v17/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:

1. Directories will resolve as postgres: URLs
2. Unix sockets will resolve as mysql: URLs
3. Regular files will have their headers checked to determine if they are either sqlite3: or duckdb: files
4. 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