About dburl

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][goref-parse] and [open][goref-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: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) |

<i>^<b>*</b> 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 in the above format can be parsed with the [dburl.Parse func][goref-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, [dburl.Open][goref-open], is provided that will parse, open, and return a [standard sql.DB database][goref-sql-db] 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][goref-parse] and [dburl.Open][goref-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=

Database Schemes, Aliases, and Drivers

The following table lists the supported dburl protocol schemes (ie, driver), additional aliases, and the related Go driver:

<!-- DRIVER DETAILS START -->

| Database | Scheme / Tag | Scheme Aliases | Driver Package / Notes | | -------------------- | --------------- | ----------------------------------------------- | --------------------------------------------------------------------------- | | PostgreSQL | postgres | pg, pgsql, postgresql | [github.com/lib/pq][d-postgres] | | MySQL | mysql | my, maria, aurora, mariadb, percona | [github.com/go-sql-driver/mysql][d-mysql] | | Microsoft SQL Server | sqlserver | ms, mssql, azuresql | [github.com/microsoft/go-mssqldb][d-sqlserver] | | Oracle Database | oracle | or, ora, oci, oci8, odpi, odpi-c | [github.com/sijms/go-ora/v2][d-oracle] | | SQLite3 | sqlite3 | sq, sqlite, file | [github.com/mattn/go-sqlite3][d-sqlite3] ^[†][f-cgo] | | ClickHouse | clickhouse | ch | [github.com/ClickHouse/clickhouse-go/v2][d-clickhouse] | | CSVQ | csvq | cs, csv, tsv, json | [github.com/mithrandie/csvq-driver][d-csvq] | | | | | | | Alibaba MaxCompute | maxcompute | mc | [sqlflow.org/gomaxcompute][d-maxcompute] | | Alibaba Tablestore | ots | ot, tablestore | [github.com/aliyun/aliyun-tablestore-go-sql-driver][d-ots] | | Apache Avatica | avatica | av, phoenix | [github.com/apache/calcite-avatica-go/v5][d-avatica] | | Apache H2 | h2 | | [github.com/jmrobles/h2go][d-h2] | | Apache Hive | hive | hi, hive2 | [sqlflow.org/gohive][d-hive] | | Apache Ignite | ignite | ig, gridgain | [github.com/amsokol/ignite-go-client/sql][d-ignite] | | Apache Impala | impala | im | [github.com/sclgo/impala-go][d-impala] | | AWS Athena | athena | s3, aws, awsathena | [github.com/uber/athenadriver/go][d-athena] | | Azure CosmosDB | cosmos | cm, gocosmos | [github.com/btnguyen2k/gocosmos][d-cosmos] | | Cassandra | cassandra | ca, scy, scylla, datastax, cql | [github.com/MichaelS11/go-cql-driver][d-cassandra] | | ChaiSQL | chai | ci, genji, chaisql | [github.com/chaisql/chai][d-chai] | | Couchbase | couchbase | n1, n1ql | [github.com/couchbase/go_n1ql][d-couchbase] | | Cznic QL | ql | cznic, cznicql | [modernc.org/ql][d-ql] | | Databend | databend | dd, bend | [github.com/datafuselabs/databend-go][d-databend] | | Databricks | databricks | br, brick, bricks, databrick | [github.com/databricks/databricks-sql-go][d-databricks] | | DuckDB | duckdb | dk, ddb, duck, file | [github.com/duckdb/duckdb-go/v2][d-duckdb] ^[†][f-cgo] | | DynamoDb | dynamodb | dy, dyn, dynamo, dynamodb | [github.com/btnguyen2k/godynamo][d-dynamodb] | | Exasol | exasol | ex, exa | [github.com/exasol/exasol-driver-go][d-exasol] | | Firebird | firebird | fb, firebirdsql | [github.com/nakagami/firebirdsql][d-firebird] | | FlightSQL | flightsql | fl, flight | [github.com/apache/arrow/go/v17/arrow/flight/flightsql/driver][d-flightsql] | | Google BigQuery | bigquery | bq | [gorm.io/driver/bigquery/driver][d-bigquery] | | Google Spanner | spanner | sp | [github.com/googleapis/go-sql-spanner][d-spanner] | | Microsoft ADODB | adodb | ad, ado | [github.com/mattn/go-adodb][d-ado