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

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:

^* 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:

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:

Please see the dburl GoDoc listing 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
    err = db.QueryRow(`SELECT name FROM mytable WHERE id=10`).Scan(&name)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf(">> got: %s\n", 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 Go code from a database schema