Need help with dburl?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

xo
157 Stars 17 Forks MIT License 116 Commits 1 Opened issues

Description

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

Services available

!
?

Need anything else?

Contributors list

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:[email protected]/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:[email protected]/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:[email protected]/dbname
pg://user:[email protected]/dbname?sslmode=disable
mysql://user:[email protected]/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:[email protected]/dbname
sqlite:/path/to/file.db
file:myfile.sqlite3?loc=auto
odbc+postgres://user:[email protected]: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] | |----------------------------------|------------------------------------------| | 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 | | | | | 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 | | Apache Avatica (avatica) | av, phoenix | | Apache H2 (h2) | h2 | | Apache Hive (hive) | hi | | Apache Ignite (ignite) | ig, gridgain | | Apache Impala (impala) | im | | AWS Athena (athena) | s3 | | 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 | | 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 | <!-- END SCHEME TABLE -->

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 -u github.com/xo/dburl

Using

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

| Database (driver) | Package | |----------------------------------|---------------------------------------------------------------------------------------------| | MySQL (mysql) | github.com/go-sql-driver/mysql | | Oracle Database (oracle) | github.com/sijms/go-ora | | PostgreSQL (postgres) | github.com/lib/pq | | SQLite3 (sqlite3) | github.com/mattn/go-sqlite3 | | Microsoft SQL Server (sqlserver) | github.com/denisenkom/go-mssqldb | | | | | Amazon Redshift (redshift) | github.com/lib/pq | | CockroachDB (cockroachdb) | github.com/lib/pq | | MemSQL (memsql) | github.com/go-sql-driver/mysql | | TiDB (tidb) | github.com/go-sql-driver/mysql | | Vitess (vitess) | github.com/go-sql-driver/mysql | | | | | MySQL (mymysql) | github.com/ziutek/mymysql/godrv | | Oracle Database (godror) | github.com/godror/godror | | PostgreSQL (pgx) | github.com/jackc/pgx/stdlib | | | | | Alibaba MaxCompute (maxcompute) | sqlflow.org/gomaxcompute | | Apache Avatica (avatica) | github.com/Boostport/avatica | | Apache H2 (h2) | github.com/jmrobles/h2go | | Apache Hive (hive) | sqlflow.org/gohive | | Apache Ignite (ignite) | github.com/amsokol/ignite-go-client/sql | | Apache Impala (impala) | github.com/bippio/go-impala | | AWS Athena (athena) | github.com/uber/athenadriver/go | | Azure Cosmos (cosmos) | github.com/btnguyen2k/gocosmos | | Cassandra (cql) | github.com/MichaelS11/go-cql-driver | | ClickHouse (clickhouse) | github.com/ClickHouse/clickhouse-go | | Couchbase (n1ql) | github.com/couchbase/go_n1ql | | Cznic QL (ql) | modernc.org/ql | | CSVQ (csvq) | github.com/mithrandie/csvq | | Exasol (exasol) | github.com/exasol/exasol-driver-go | | Firebird SQL (firebirdsql) | github.com/nakagami/firebirdsql | | Genji (genji) | github.com/genjidb/genji/sql/driver | | Google BigQuery (bigquery) | gorm.io/driver/bigquery/driver | | Google Spanner (spanner) | github.com/rakyll/go-sql-driver-spanner | | IBM Netezza (nzgo) | github.com/IBM/nzgo | | Microsoft ADODB (adodb) | github.com/mattn/go-adodb | | ModernC SQLite (moderncsqlite) | modernc.org/sqlite | | ODBC (odbc) | github.com/alexbrainman/odbc | | OLE ODBC (oleodbc) | github.com/mattn/go-adodb | | Presto (presto) | github.com/prestodb/presto-go-client/presto | | SAP ASE (tds) | github.com/thda/tds | | SAP HANA (hdb) | github.com/SAP/go-hdb/driver | | Snowflake (snowflake) | github.com/snowflakedb/gosnowflake | | Trino (trino) | github.com/trinodb/trino-go-client/trino | | Vertica (vertica) | github.com/vertica/vertica-sql-go | | VoltDB (voltdb) | github.com/VoltDB/voltdb-client-go/voltdbclient | <!-- END DRIVER TABLE -->

Please see [the

dburl
Go Reference][goref-link] for the full API 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/denisenkom/go-mssqldb"
"github.com/xo/dburl"

)

func main() { db, err := dburl.Open("sqlserver://user:[email protected]/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) }

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.