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:

Component	Description
protocol	driver name or alias (see below)
transport	"tcp", "udp", "unix", "http", "https", or a driver name for 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. 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:

Database	Scheme / Tag	Scheme Aliases	Driver Package / Notes
PostgreSQL	postgres	pg, pgsql, postgresql	github.com/jackc/pgx/v5/stdlib
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/v3
SQLite3	sqlite3	sq, sqlite, file	github.com/mattn/go-sqlite3 † §
DuckDB	duckdb	dk, ddb, duck, file	github.com/duckdb/duckdb-go/v2 † §
ClickHouse	clickhouse	ch	github.com/ClickHouse/clickhouse-go/v2
CSVQ	csvq	cs, csv, tsv, json	github.com/mithrandie/csvq-driver §
Alibaba MaxCompute	maxcompute	mc	github.com/aliyun/aliyun-odps-go-sdk/sqldriver ¶
Alibaba Tablestore	ots	ot, tablestore	github.com/aliyun/aliyun-tablestore-go-sql-driver ¶
Amazon Redshift	redshift	rs	github.com/jackc/pgx/v5/stdlib ¶
Apache Avatica	avatica	av, phoenix	github.com/apache/calcite-avatica-go/v5
Apache H2	h2		github.com/jmrobles/h2go
Apache Hive	hive	hi, hive2	github.com/beltran/gohive/v2
Apache Impala	impala	im	github.com/sclgo/impala-go
Apache Pinot	pinot	pi	github.com/xo/dbimp/pinot
ArangoDB	arangodb	ar, arango	github.com/xo/dbimp/arangodb
AWS Athena	awsathena	s3, aws, athena	github.com/uber/athenadriver/go ¶
Azure CosmosDB	cosmos	cm, gocosmos	github.com/btnguyen2k/gocosmos ¶
Cassandra	cql	ca, scy, scylla, datastax, cassandra	github.com/xo/cql
ChaiSQL	chai	ci, genji, chaisql	github.com/chaisql/chai §
CockroachDB	cockroachdb	cr, cdb, crdb, cockroach	github.com/jackc/pgx/v5/stdlib
Couchbase	couchbase	n1, n1ql	github.com/xo/dbimp/couchbase
CrateDB	cratedb	ct, crate	github.com/jackc/pgx/v5/stdlib
Databend	databend	dd, bend	github.com/xo/dbimp/databend
Databricks	databricks	br, brick, bricks, databrick	github.com/databricks/databricks-sql-go ¶
DynamoDb	godynamo	dy, dyn, dynamo, dynamodb	github.com/btnguyen2k/godynamo ¶
Exasol	exasol	ex, exa	github.com/exasol/exasol-driver-go
Firebird	firebirdsql	fb, firebird	github.com/nakagami/firebirdsql
FlightSQL	flightsql	fl, flight	github.com/apache/arrow-go/v18/arrow/flight/flightsql/driver
GizmoSQL	gizmosql	gz, gizmo	github.com/apache/arrow-go/v18/arrow/flight/flightsql/driver
GO DRiver for ORacle	godror	gr	github.com/godror/godror †
Google BigQuery	bigquery	bq	gorm.io/driver/bigquery/driver ¶
Google Spanner	spanner	sp	github.com/googleapis/go-sql-spanner ¶
InfluxDB	influxdb	in, influx	github.com/xo/dbimp/influxdb
InfluxDB InfluxQL	influxql	iq	github.com/xo/dbimp/influxdb
libSQL	libsql	ls, turso	github.com/xo/dbimp/libsql
ModernC SQLite3	moderncsqlite	mq, modernsqlite	modernc.org/sqlite §
Neo4j	neo4j	nj, neo, n4j	github.com/xo/dbimp/neo4j
ODBC	odbc	od	github.com/alexbrainman/odbc †
PostgreSQL lib/pq	pq	libpq	github.com/lib/pq
PostgreSQL PGX	pgx	px	github.com/jackc/pgx/v5/stdlib
Presto	presto	pr, prestodb	github.com/prestodb/presto-go-client/v2
QuestDB	questdb	qs	github.com/jackc/pgx/v5/stdlib
rqlite	rqlite	rq	github.com/xo/dbimp/rqlite
SAP HANA	hdb	sa, sap, hana, saphana	github.com/SAP/go-hdb/driver
SingleStore MemSQL	memsql	me	github.com/go-sql-driver/mysql
Snowflake	snowflake	sf	github.com/snowflakedb/gosnowflake/v2 ¶
SurrealDB	surrealdb	sr, sur, surreal	github.com/xo/dbimp/surrealdb
TiDB	tidb	ti	github.com/go-sql-driver/mysql
Trino	trino	tr, trs, trinos	github.com/trinodb/trino-go-client/trino
Vertica	vertica	ve	github.com/vertica/vertica-sql-go
Vitess Database	vitess	vt	github.com/go-sql-driver/mysql
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

^† 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

usql | dburl | dbmeta | dbimp | cql | dbtpl | tblfmt | rline | transit