Giter VIP home page Giter VIP logo

dburl's Introduction

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:[email protected]/dbname
   mssql://user:[email protected]/instance/dbname
   ms://user:[email protected]:port/instance/dbname?keepAlive=10
   oracle://user:[email protected]/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 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:

Database (driver) Package
Microsoft SQL Server (mssql) github.com/denisenkom/go-mssqldb
MySQL (mysql) github.com/go-sql-driver/mysql
Oracle (ora) gopkg.in/rana/ora.v4
PostgreSQL (postgres) github.com/lib/pq
SQLite3 (sqlite3) github.com/mattn/go-sqlite3
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
Google Spanner (spanner) github.com/xo/spanner (not yet public)
MySQL (mymysql) github.com/ziutek/mymysql/godrv
PostgreSQL (pgx) github.com/jackc/pgx/stdlib
Apache Avatica (avatica) github.com/Boostport/avatica
Apache Ignite (ignite) github.com/amsokol/ignite-go-client/sql
Cassandra (cql) github.com/MichaelS11/go-cql-driver
ClickHouse (clickhouse) github.com/kshvakov/clickhouse
Couchbase (n1ql) github.com/couchbase/go_n1ql
Cznic QL (ql) github.com/cznic/ql
Firebird SQL (firebirdsql) github.com/nakagami/firebirdsql
Microsoft ADODB (adodb) github.com/mattn/go-adodb
ODBC (odbc) github.com/alexbrainman/odbc
OLE ODBC (oleodbc) github.com/mattn/go-adodb
Presto (presto) github.com/prestodb/presto-go-client/presto
SAP HANA (hdb) github.com/SAP/go-hdb/driver
Snowflake (snowflake) github.com/snowflakedb/gosnowflake
VoltDB (voltdb) github.com/VoltDB/voltdb-client-go/voltdbclient

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:

  • usql - a universal command-line interface for SQL databases
  • xo - a command-line tool to generate Go code from a database schema

dburl's People

Watchers

 avatar  avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.