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
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.
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 { /* ... */ }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=
The following protocols schemes (ie, driver) and their associated aliases are supported out of the box:
| Database (scheme/driver) | Protocol Aliases [real driver] |
|---|---|
| MySQL (mysql) | my, mariadb, maria, percona, aurora |
| Oracle Database (oracle) | or, ora, oracle, oci, oci8, odpi, odpi-c |
| PostgreSQL (postgres) | pg, postgresql, pgsql |
| SQLite3 (sqlite3) | sq, sqlite, file |
| Microsoft SQL Server (sqlserver) | ms, mssql, azuresql |
| Amazon Redshift (redshift) | rs [postgres] |
| CockroachDB (cockroachdb) | cr, cockroach, crdb, cdb [postgres] |
| MemSQL (memsql) | me [mysql] |
| TiDB (tidb) | ti [mysql] |
| Vitess (vitess) | vt [mysql] |
| MySQL (mymysql) | zm, mymy |
| Oracle Database (godror) | gr |
| PostgreSQL (pgx) | px |
| Alibaba MaxCompute (maxcompute) | mc |
| Alibaba Tablestore (ots) | ot, ots, tablestore |
| Apache Avatica (avatica) | av, phoenix |
| Apache H2 (h2) | h2 |
| Apache Hive (hive) | hi |
| Apache Ignite (ignite) | ig, gridgain |
| Apache Impala (impala) | im |
| AWS Athena (awsathena) | s3, aws, athena |
| Azure Cosmos (cosmos) | cm |
| Cassandra (cql) | ca, cassandra, datastax, scy, scylla |
| ClickHouse (clickhouse) | ch |
| Couchbase (n1ql) | n1, couchbase |
| Cznic QL (ql) | ql, cznic, cznicql |
| CSVQ (csvq) | csv, tsv, json |
| Databend (databend) | dd, bend |
| Exasol (exasol) | ex, exa |
| Firebird SQL (firebirdsql) | fb, firebird |
| Genji (genji) | gj |
| Google BigQuery (bigquery) | bq |
| Google Spanner (spanner) | sp |
| IBM Netezza (nzgo) | nz, netezza |
| Microsoft ADODB (adodb) | ad, ado |
| ModernC SQLite (moderncsqlite) | mq, modernsqlite |
| ODBC (odbc) | od |
| OLE ODBC (oleodbc) | oo, ole, oleodbc [adodb] |
| Presto (presto) | pr, prestodb, prestos, prs, prestodbs |
| SAP ASE (tds) | ax, ase, sapase |
| SAP HANA (hdb) | sa, saphana, sap, hana |
| Snowflake (snowflake) | sf |
| Trino (trino) | tr, trino, trinos, trs |
| Vertica (vertica) | ve |
| VoltDB (voltdb) | vo, volt, vdb |
Any protocol scheme alias:// can be used in place of protocol://, and will
work identically with dburl.Parse and dburl.Open.
Install in the usual Go fashion:
$ go get -u github.com/xo/dburlPlease note that dburl does not import actual SQL drivers, and only provides
a standard way to parse/open respective database
connection URLs.
For reference, these are the following "expected" SQL drivers that would need to be imported:
Please see [the dburl Go Reference][goref-link] for the full API
documentation.
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.
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)
}dburl was built primarily to support these projects: