217 lines
9.3 KiB
Go
217 lines
9.3 KiB
Go
|
// 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.
|
||
|
|
//
|
||
|
|
// Database Connection URL Overview
|
||
|
|
//
|
||
|
|
// Supported database connection URLs are of the form:
|
||
|
|
//
|
||
|
|
// protocol+transport://user:pass@host/dbname?opt1=a&opt2=b
|
||
|
|
// protocol:/path/to/file
|
||
|
|
//
|
||
|
|
// Where:
|
||
|
|
//
|
||
|
|
// 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 Parse 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, 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
|
||
|
|
// Parse and 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: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/sid
|
||
|
|
// 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 Database (goracle) | or, ora, goracle, oci, oci8, odpi, odpi-c
|
||
|
|
// 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 and Open.
|
||
|
|
//
|
||
|
|
// Using
|
||
|
|
//
|
||
|
|
// 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 (scheme/driver) | Package
|
||
|
|
// -----------------------------|-------------------------------------------------
|
||
|
|
// Microsoft SQL Server (mssql) | github.com/denisenkom/go-mssqldb
|
||
|
|
// MySQL (mysql) | github.com/go-sql-driver/mysql
|
||
|
|
// Oracle Database (goracle) | gopkg.in/goracle.v2
|
||
|
|
// 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
|
||
|
|
// SAP ASE (tds) | github.com/thda/tds
|
||
|
|
// SAP HANA (hdb) | github.com/SAP/go-hdb/driver
|
||
|
|
// Snowflake (snowflake) | github.com/snowflakedb/gosnowflake
|
||
|
|
// VoltDB (voltdb) | github.com/VoltDB/voltdb-client-go/voltdbclient
|
||
|
|
//
|
||
|
|
// * OLE ODBC is a special alias for using the "MSDASQL.1" OLE provider with the
|
||
|
|
// ADODB driver on Windows. oleodbc:// URLs will be converted to the equivalent
|
||
|
|
// ADODB DSN with "Extended Properties" having the respective ODBC parameters,
|
||
|
|
// including the underlying transport prootocol. As such, oleodbc+protocol://user:pass@host/dbname
|
||
|
|
// URLs are equivalent to adodb://MSDASQL.1/?Extended+Properties=.... on
|
||
|
|
// Windows. See GenOLEODBC for information regarding how URL components are
|
||
|
|
// mapped and passed to ADODB's Extended Properties parameter.
|
||
|
|
//
|
||
|
|
// 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.
|
||
|
|
//
|
||
|
|
// Related Projects
|
||
|
|
//
|
||
|
|
// This package was written mainly to support xo (https://github.com/xo/xo)
|
||
|
|
// and usql (https://github.com/xo/usql).
|
||
|
|
package dburl
|
||
|
|
|
||
|
|
import (
|
||
|
|
"database/sql"
|
||
|
|
)
|
||
|
|
|
||
|
|
// Error is a dburl error.
|
||
|
|
type Error string
|
||
|
|
|
||
|
|
// Error satisfies the error interface.
|
||
|
|
func (err Error) Error() string {
|
||
|
|
return string(err)
|
||
|
|
}
|
||
|
|
|
||
|
|
const (
|
||
|
|
// ErrInvalidDatabaseScheme is the invalid database scheme error.
|
||
|
|
ErrInvalidDatabaseScheme Error = "invalid database scheme"
|
||
|
|
|
||
|
|
// ErrUnknownDatabaseScheme is the unknown database type error.
|
||
|
|
ErrUnknownDatabaseScheme Error = "unknown database scheme"
|
||
|
|
|
||
|
|
// ErrInvalidTransportProtocol is the invalid transport protocol error.
|
||
|
|
ErrInvalidTransportProtocol Error = "invalid transport protocol"
|
||
|
|
|
||
|
|
// ErrRelativePathNotSupported is the relative paths not supported error.
|
||
|
|
ErrRelativePathNotSupported Error = "relative path not supported"
|
||
|
|
|
||
|
|
// ErrMissingHost is the missing host error.
|
||
|
|
ErrMissingHost Error = "missing host"
|
||
|
|
|
||
|
|
// ErrMissingPath is the missing path error.
|
||
|
|
ErrMissingPath Error = "missing path"
|
||
|
|
)
|
||
|
|
|
||
|
|
// Open takes a urlstr like "protocol+transport://user:pass@host/dbname?option1=a&option2=b"
|
||
|
|
// and creates a standard sql.DB connection.
|
||
|
|
//
|
||
|
|
// See Parse for information on formatting URLs to work properly with Open.
|
||
|
|
func Open(urlstr string) (*sql.DB, error) {
|
||
|
|
u, err := Parse(urlstr)
|
||
|
|
if err != nil {
|
||
|
|
return nil, err
|
||
|
|
}
|
||
|
|
|
||
|
|
return sql.Open(u.Driver, u.DSN)
|
||
|
|
}
|