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:[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=
The following table lists the supported dburl protocol schemes (ie, driver),
additional aliases, and the related Go driver:
† 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.
Install in the usual Go fashion:
$ go get github.com/xo/dburl@latestdburl 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.
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)
}By default on non-Windows systems, dburl will resolve paths on disk, and URLs
with file: schemes to an appropriate database driver:
- Directories will resolve as
postgres:URLs - Unix sockets will resolve as
mysql:URLs - Regular files will have their headers checked to determine if they are
either
sqlite3:orduckdb:files - Non-existent files will test their file extension against well-known
sqlite3:andduckdb: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
}dburl was built primarily to support these projects: