Skip to content
/ dburl Public

Package dburl provides a standard, URL style mechanism for parsing and opening SQL database connection strings

License

Notifications You must be signed in to change notification settings

xo/dburl

Repository files navigation

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

Unit Tests Go Reference Discord Discussion

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

  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

About

Package dburl provides a standard, URL style mechanism for parsing and opening SQL database connection strings

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages