Skip to content

Commit

Permalink
General maintenance, changing preferred oracle driver
Browse files Browse the repository at this point in the history 
1. Changing from unmaintained ora.v4 driver to goracle.v2 driver for
Oracle Database support
2. Documentation cleanup
3. Updates to travis configuration
4. Changes/fixes to unit tests
  • Loading branch information
Kenneth Shaw committed Aug 14, 2019
1 parent 98997a0 commit 13f573b
Show file tree
Hide file tree
Showing 6 changed files with 233 additions and 175 deletions.
9 changes: 4 additions & 5 deletions .travis.yml
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
language: go
go:
- 1.10.x
- 1.11.x
- 1.12.x
- tip
before_install:
- go get github.com/mattn/goveralls
services:
- mysql
- postgresql
script:
- go test -v -coverprofile=coverage.out
- goveralls -service=travis-ci -coverprofile=coverage.out
181 changes: 109 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,30 @@
# About dburl
# dburl [![GoDoc][godoc]][godoc-link] [![Build Status][travis-ci]][travis-ci-link]

Package dburl provides a standard, URL style mechanism for parsing and
opening SQL database connection strings for [Go](https://golang.org/project),
supporting standard URLs for the standard databases PostgreSQL, MySQL, SQLite3,
Oracle, Microsoft SQL Server, and most other databases with a publicly
available Go driver.
Package `dburl` provides a standard, URL style mechanism for parsing and
opening SQL database connection strings for [Go][go-project]. Provides
standardized way to [parse][godoc-parse] and [open][godoc-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 URL Connection Strings
[godoc]: https://godoc.org/github.com/xo/dburl?status.svg (GoDoc)
[travis-ci]: https://travis-ci.org/xo/dburl.svg?branch=master (Travis CI)
[godoc-link]: https://godoc.org/github.com/xo/dburl
[travis-ci-link]: https://travis-ci.org/xo/dburl

Supported database URLs are of the form:
[Overview][] | [Quickstart][] | [Examples][] | [Schemes][] | [Installing][] | [Using][] | [About][]

[Overview]: #database-connection-url-overview (Database Connection URL Overview)
[Quickstart]: #quickstart (Quickstart)
[Examples]: #example-urls (Example URLs)
[Schemes]: #protocol-schemes-and-aliases (Protocol Schemes and Aliases)
[Installing]: #installing (Installing)
[Using]: #using (Using)
[About]: #about (About)

## Database Connection URL Overview

Supported database connection URLs are of the form:

```
protocol+transport://user:pass@host/dbname?opt1=a&opt2=b
Expand All @@ -27,31 +43,40 @@ Where:
| dbname<sup>*</sup> | database, instance, or service name/ID to connect to |
| ?opt1=... | additional database driver options (see respective SQL driver for available options) |

<i><sup><b>*</b></sup> 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.</i>
<i><sup><b>*</b></sup> 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.</i>

## Quickstart

Database connection URLs (as described below) can be parsed with `Parse` as such:
Database connection URLs in the above format can be parsed with the
[`dburl.Parse` func][godoc-parse] as such:

```go
import (
"github.com/xo/dburl"
)
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:
Additionally, a simple helper, [`dburl.Open`][godoc-open], is provided that
will parse, open, and return a [standard `sql.DB` database][godoc-sql-db]
connection:

```go
import (
"github.com/xo/dburl"
)
db, err := dburl.Open("sqlite:mydatabase.sqlite3?loc=auto")
if err != nil { /* ... */ }
```

## Example URLs ##
## Example URLs

The following are URLs that can be handled with a call to `Open` or `Parse`:
The following are example database connection URLs that can be handled by
[`dburl.Parse`][godoc-parse] and [`dburl.Open`][godoc-open]:

```
postgres://user:pass@localhost/dbname
Expand All @@ -61,7 +86,7 @@ if err != nil { /* ... */ }
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/oracledb
oracle://user:pass@somehost.com/sid
sap://user:pass@localhost/dbname
sqlite:/path/to/file.db
file:myfile.sqlite3?loc=auto
Expand All @@ -73,56 +98,57 @@ if err != nil { /* ... */ }
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 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`/`Open`.

## Installation
| Database (scheme/driver) | Protocol Aliases [real driver] |
|------------------------------|-------------------------------------------|
| Microsoft SQL Server (mssql) | ms, sqlserver |
| MySQL (mysql) | my, mariadb, maria, percona, aurora |
| Oracle (goracle) | or, ora, oracle, 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 [`dburl.Parse`][godoc-parse] and [`dburl.Open`][godoc-open].

## Installing

Install in the usual Go fashion:

```sh
go get -u github.com/xo/dburl
```

## Usage
## 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.
Please note that `dburl` does not import actual SQL drivers, and only provides
a standard way to [parse][godoc-parse]/[open][godoc-open] respective database
connection URLs.

For reference, these are the following "expected" SQL drivers that would need
to be imported:
Expand All @@ -131,7 +157,7 @@ to be imported:
|------------------------------|---------------------------------------------------------------------------------------------|
| Microsoft SQL Server (mssql) | [github.com/denisenkom/go-mssqldb](https://github.com/denisenkom/go-mssqldb) |
| MySQL (mysql) | [github.com/go-sql-driver/mysql](https://github.com/go-sql-driver/mysql) |
| Oracle (ora) | [gopkg.in/rana/ora.v4](https://gopkg.in/rana/ora.v4) |
| Oracle (goracle) | [gopkg.in/goracle.v2](https://gopkg.in/goracle.v2) |
| PostgreSQL (postgres) | [github.com/lib/pq](https://github.com/lib/pq) |
| SQLite3 (sqlite3) | [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3) |
| | |
Expand Down Expand Up @@ -162,18 +188,19 @@ to be imported:
| Snowflake (snowflake) | [github.com/snowflakedb/gosnowflake](https://github.com/snowflakedb/gosnowflake) |
| VoltDB (voltdb) | [github.com/VoltDB/voltdb-client-go/voltdbclient](github.com/VoltDB/voltdb-client-go]) |

Please see [the GoDoc API page](http://godoc.org/github.com/xo/dburl) for a
full API listing.
Please see [the `dburl` GoDoc listing][godoc-dburl] for the full API
documentation.

### 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`.
[`dburl.Parse`][godoc-parse] and [`dburl.Open`][godoc-open] rely primarily on
Go's standard [`net/url.URL`][godoc-net-url] type, and as such, `dburl`'s URL
parsing shares/follows the same rules, conventions, and semantics for database
connection URLs as Go's standard [`net/url.Parse` func][godoc-net-url-parse].

## Full Example
## Example

A full example for reference:
A [full example](_example/example.go) for reference:

```go
// _example/example.go
Expand Down Expand Up @@ -203,9 +230,19 @@ func main() {
}
```

## Related Projects
## About

`dburl` was built primarily to support these projects:

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

The dburl package was built primarily to support these projects:
[go-project]: https://golang.org/project
[godoc-open]: https://godoc.org/github.com/xo/dburl#Open
[godoc-parse]: https://godoc.org/github.com/xo/dburl#Parse
[godoc-sql-db]: https://godoc.org/database/sql#DB
[godoc-net-url]: https://godoc.org/net/url#URL
[godoc-net-url-parse]: https://godoc.org/net/url#URL.Parse

* [usql](https://github.com/xo/usql) - a universal command-line interface for SQL databases
* [xo](https://github.com/xo/xo) - a command-line tool to generate Go code from a database schema
[usql]: https://github.com/xo/usql
[xo]: https://github.com/xo/xo
51 changes: 31 additions & 20 deletions dburl.go
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
// Package dburl provides a standard, URL style mechanism for parsing and
// opening SQL database connection strings.
// 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 URL Connection Strings
// Database Connection URL Overview
//
// Supported database URLs are of the form:
// Supported database connection URLs are of the form:
//
// protocol+transport://user:pass@host/dbname?opt1=a&opt2=b
// protocol:/path/to/file
Expand All @@ -19,26 +22,34 @@
// ?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.
// * 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
//
// URLs in the above format can be parsed with Parse as such:
// 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 func, Open, is available to quickly parse,
// open, and return a standard SQL database connection:
// 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 URLs that can be handled with a call to Open or Parse:
// 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
Expand All @@ -47,7 +58,7 @@
// 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/oracledb
// oracle://user:pass@somehost.com/sid
// sap://user:pass@localhost/dbname
// sqlite:/path/to/file.db
// file:myfile.sqlite3?loc=auto
Expand All @@ -59,24 +70,24 @@
// 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
// Oracle (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
Expand All @@ -94,9 +105,9 @@
// VoltDB (voltdb) | vo, volt, vdb
//
// Any protocol scheme alias:// can be used in place of protocol://, and will
// work identically with Parse/Open.
// work identically with Parse and Open.
//
// Usage
// 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.
Expand All @@ -108,7 +119,7 @@
// -----------------------------|-------------------------------------------------
// Microsoft SQL Server (mssql) | github.com/denisenkom/go-mssqldb
// MySQL (mysql) | github.com/go-sql-driver/mysql
// Oracle (ora) | gopkg.in/rana/ora.v4
// Oracle (goracle) | gopkg.in/goracle.v2
// PostgreSQL (postgres) | github.com/lib/pq
// SQLite3 (sqlite3) | github.com/mattn/go-sqlite3
// -----------------------------|-------------------------------------------------
Expand Down
Loading

0 comments on commit 13f573b

Please sign in to comment.