11 KiB
About dburl
Package dburl provides a standard, URL style mechanism for parsing and opening SQL database connection strings for Go, supporting standard URLs for the standard databases PostgreSQL, MySQL, SQLite3, Oracle, Microsoft SQL Server, and most other databases with a publicly available Go driver.
Database URL Connection Strings
Supported database 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, the syntax to supply an
instance and database name is /instance/dbname, where /instance is
optional. For Oracle databases, /dbname is the unique database ID (SID).
Please see below for examples.
Quickstart
Database connection URLs (as described below) can be parsed with Parse as such:
u, err := dburl.Parse("postgresql://user:pass@localhost/mydatabase/?sslmode=disable")
if err != nil { /* ... */ }
Additionally, a simple helper func Open, is available to quickly parse, open,
and return a standard SQL database connection:
db, err := dburl.Open("sqlite:mydatabase.sqlite3?loc=auto")
if err != nil { /* ... */ }
Example URLs
The following are URLs that can be handled with a call to Open or Parse:
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/oracledb
sap://user:pass@localhost/dbname
sqlite:/path/to/file.db
file:myfile.sqlite3?loc=auto
odbc+postgres://user:pass@localhost:port/dbname?option1=
Protocol Schemes and Aliases
The following protocols schemes (ie, driver) and their associated aliases are supported out of the box:
| Database (scheme/driver) | Protocol Aliases [real driver] |
|---|---|
| Microsoft SQL Server (mssql) | ms, sqlserver |
| MySQL (mysql) | my, mariadb, maria, percona, aurora |
| Oracle (ora) | or, oracle, oci8, oci |
| PostgreSQL (postgres) | pg, postgresql, pgsql |
| SQLite3 (sqlite3) | sq, sqlite, file |
| Amazon Redshift (redshift) | rs [postgres] |
| CockroachDB (cockroachdb) | cr, cockroach, crdb, cdb [postgres] |
| MemSQL (memsql) | me [mysql] |
| TiDB (tidb) | ti [mysql] |
| Vitess (vitess) | vt [mysql] |
| Google Spanner (spanner) | gs, google, span (not yet public) |
| MySQL (mymysql) | zm, mymy |
| PostgreSQL (pgx) | px |
| Apache Avatica (avatica) | av, phoenix |
| Apache Ignite (ignite) | ig, gridgain |
| Cassandra (cql) | ca, cassandra, datastax, scy, scylla |
| ClickHouse (clickhouse) | ch |
| Couchbase (n1ql) | n1, couchbase |
| Cznic QL (ql) | ql, cznic, cznicql |
| Firebird SQL (firebirdsql) | fb, firebird |
| Microsoft ADODB (adodb) | ad, ado |
| 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 |
| VoltDB (voltdb) | vo, volt, vdb |
Any protocol scheme alias:// can be used in place of protocol://, and will work
identically with Parse/Open.
Installation
Install in the usual Go fashion:
go get -u github.com/xo/dburl
Usage
Please note that the dburl package 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 GoDoc API page for a full API listing.
URL Parsing Rules
Parse and Open rely heavily on the standard net/url.URL type, as such
parsing rules have the same conventions/semantics as any URL parsed by the
standard library's net/url.Parse.
Full Example
A full example for reference:
// _example/example.go
package main
import (
"fmt"
"log"
_ "github.com/denisenkom/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
err = db.QueryRow(`SELECT name FROM mytable WHERE id=10`).Scan(&name)
if err != nil {
log.Fatal(err)
}
fmt.Printf(">> got: %s\n", name)
}
Related Projects
The dburl package was built primarily to support these projects: