{"id":13564625,"url":"https://github.com/xo/dburl","last_synced_at":"2025-05-14T08:07:20.209Z","repository":{"id":39898270,"uuid":"58427113","full_name":"xo/dburl","owner":"xo","description":"Package dburl provides a standard, URL style mechanism for parsing and opening SQL database connection strings","archived":false,"fork":false,"pushed_at":"2025-04-06T21:12:02.000Z","size":182,"stargazers_count":277,"open_issues_count":0,"forks_count":39,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-15T01:54:19.058Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-05-10T03:30:15.000Z","updated_at":"2025-04-06T21:12:05.000Z","dependencies_parsed_at":"2024-01-06T11:21:35.818Z","dependency_job_id":"ebb6ed95-664c-4c9d-987b-ae644cc7152a","html_url":"https://github.com/xo/dburl","commit_stats":{"total_commits":161,"total_committers":11,"mean_commits":"14.636363636363637","dds":0.3726708074534162,"last_synced_commit":"2a988958748680723708356764670b51ac1f7f83"},"previous_names":["knq/dburl"],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xo%2Fdburl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xo%2Fdburl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xo%2Fdburl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xo%2Fdburl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xo","download_url":"https://codeload.github.com/xo/dburl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254101617,"owners_count":22014909,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T13:01:33.801Z","updated_at":"2025-05-14T08:07:15.354Z","avatar_url":"https://github.com/xo.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# About dburl\n\nPackage `dburl` provides a standard, URL style mechanism for parsing and\nopening SQL database connection strings for [Go][go-project]. Provides\nstandardized way to [parse][goref-parse] and [open][goref-open] URLs for\npopular databases PostgreSQL, MySQL, SQLite3, Oracle Database, Microsoft SQL\nServer, in addition to most other SQL databases with a publicly available Go\ndriver.\n\n[Overview][] | [Quickstart][] | [Examples][] | [Schemes][] | [Installing][] | [Using][] | [About][]\n\n[Overview]: #database-connection-url-overview \"Database Connection URL Overview\"\n[Quickstart]: #quickstart \"Quickstart\"\n[Examples]: #example-urls \"Example URLs\"\n[Schemes]: #database-schemes-aliases-and-drivers \"Database Schemes, Aliases, and Drivers\"\n[Installing]: #installing \"Installing\"\n[Using]: #using \"Using\"\n[About]: #about \"About\"\n\n[![Unit Tests][dburl-ci-status]][dburl-ci]\n[![Go Reference][goref-dburl-status]][goref-dburl]\n[![Discord Discussion][discord-status]][discord]\n\n[dburl-ci]: https://github.com/xo/dburl/actions/workflows/test.yml\n[dburl-ci-status]: https://github.com/xo/dburl/actions/workflows/test.yml/badge.svg\n[goref-dburl]: https://pkg.go.dev/github.com/xo/dburl\n[goref-dburl-status]: https://pkg.go.dev/badge/github.com/xo/dburl.svg\n[discord]: https://discord.gg/yJKEzc7prt \"Discord Discussion\"\n[discord-status]: https://img.shields.io/discord/829150509658013727.svg?label=Discord\u0026logo=Discord\u0026colorB=7289da\u0026style=flat-square \"Discord Discussion\"\n\n## Database Connection URL Overview\n\nSupported database connection URLs are of the form:\n\n```text\nprotocol+transport://user:pass@host/dbname?opt1=a\u0026opt2=b\nprotocol:/path/to/file\n```\n\nWhere:\n\n| Component           | Description                                                                          |\n| ------------------- | ------------------------------------------------------------------------------------ |\n| protocol            | driver name or alias (see below)                                                     |\n| transport           | \"tcp\", \"udp\", \"unix\" or driver name (odbc/oleodbc)                                   |\n| user                | username                                                                             |\n| pass                | password                                                                             |\n| host                | host                                                                                 |\n| dbname\u003csup\u003e\\*\u003c/sup\u003e | database, instance, or service name/ID to connect to                                 |\n| ?opt1=...           | additional database driver options (see respective SQL driver for available options) |\n\n\u003ci\u003e\u003csup\u003e\u003cb\u003e\\*\u003c/b\u003e\u003c/sup\u003e for Microsoft SQL Server, `/dbname` can be\n`/instance/dbname`, where `/instance` is optional. For Oracle Database,\n`/dbname` is of the form `/service/dbname` where `/service` is the service name\nor SID, and `/dbname` is optional. Please see below for examples.\u003c/i\u003e\n\n## Quickstart\n\nDatabase connection URLs in the above format can be parsed with the\n[`dburl.Parse` func][goref-parse] as such:\n\n```go\nimport (\n    \"github.com/xo/dburl\"\n)\n\nu, err := dburl.Parse(\"postgresql://user:pass@localhost/mydatabase/?sslmode=disable\")\nif err != nil { /* ... */ }\n```\n\nAdditionally, a simple helper, [`dburl.Open`][goref-open], is provided that\nwill parse, open, and return a [standard `sql.DB` database][goref-sql-db]\nconnection:\n\n```go\nimport (\n    \"github.com/xo/dburl\"\n)\n\ndb, err := dburl.Open(\"sqlite:mydatabase.sqlite3?loc=auto\")\nif err != nil { /* ... */ }\n```\n\n## Example URLs\n\nThe following are example database connection URLs that can be handled by\n[`dburl.Parse`][goref-parse] and [`dburl.Open`][goref-open]:\n\n```text\npostgres://user:pass@localhost/dbname\npg://user:pass@localhost/dbname?sslmode=disable\nmysql://user:pass@localhost/dbname\nmysql:/var/run/mysqld/mysqld.sock\nsqlserver://user:pass@remote-host.com/dbname\nmssql://user:pass@remote-host.com/instance/dbname\nms://user:pass@remote-host.com:port/instance/dbname?keepAlive=10\noracle://user:pass@somehost.com/sid\nsap://user:pass@localhost/dbname\nsqlite:/path/to/file.db\nfile:myfile.sqlite3?loc=auto\nodbc+postgres://user:pass@localhost:port/dbname?option1=\n```\n\n## Database Schemes, Aliases, and Drivers\n\nThe following table lists the supported `dburl` protocol schemes (ie, driver),\nadditional aliases, and the related Go driver:\n\n\u003c!-- DRIVER DETAILS START --\u003e\n\n| Database             | Scheme / Tag    | Scheme Aliases                                  | Driver Package / Notes                                                      |\n| -------------------- | --------------- | ----------------------------------------------- | --------------------------------------------------------------------------- |\n| PostgreSQL           | `postgres`      | `pg`, `pgsql`, `postgresql`                     | [github.com/lib/pq][d-postgres]                                             |\n| MySQL                | `mysql`         | `my`, `maria`, `aurora`, `mariadb`, `percona`   | [github.com/go-sql-driver/mysql][d-mysql]                                   |\n| Microsoft SQL Server | `sqlserver`     | `ms`, `mssql`, `azuresql`                       | [github.com/microsoft/go-mssqldb][d-sqlserver]                              |\n| Oracle Database      | `oracle`        | `or`, `ora`, `oci`, `oci8`, `odpi`, `odpi-c`    | [github.com/sijms/go-ora/v2][d-oracle]                                      |\n| SQLite3              | `sqlite3`       | `sq`, `sqlite`, `file`                          | [github.com/mattn/go-sqlite3][d-sqlite3] \u003csup\u003e[†][f-cgo]\u003c/sup\u003e              |\n| ClickHouse           | `clickhouse`    | `ch`                                            | [github.com/ClickHouse/clickhouse-go/v2][d-clickhouse]                      |\n| CSVQ                 | `csvq`          | `cs`, `csv`, `tsv`, `json`                      | [github.com/mithrandie/csvq-driver][d-csvq]                                 |\n|                      |                 |                                                 |                                                                             |\n| Alibaba MaxCompute   | `maxcompute`    | `mc`                                            | [sqlflow.org/gomaxcompute][d-maxcompute]                                    |\n| Alibaba Tablestore   | `ots`           | `ot`, `tablestore`                              | [github.com/aliyun/aliyun-tablestore-go-sql-driver][d-ots]                  |\n| Apache Avatica       | `avatica`       | `av`, `phoenix`                                 | [github.com/apache/calcite-avatica-go/v5][d-avatica]                        |\n| Apache H2            | `h2`            |                                                 | [github.com/jmrobles/h2go][d-h2]                                            |\n| Apache Hive          | `hive`          | `hi`, `hive2`                                   | [sqlflow.org/gohive][d-hive]                                                |\n| Apache Ignite        | `ignite`        | `ig`, `gridgain`                                | [github.com/amsokol/ignite-go-client/sql][d-ignite]                         |\n| Apache Impala        | `impala`        | `im`                                            | [github.com/sclgo/impala-go][d-impala]                                      |\n| AWS Athena           | `athena`        | `s3`, `aws`, `awsathena`                        | [github.com/uber/athenadriver/go][d-athena]                                 |\n| Azure CosmosDB       | `cosmos`        | `cm`, `gocosmos`                                | [github.com/btnguyen2k/gocosmos][d-cosmos]                                  |\n| Cassandra            | `cassandra`     | `ca`, `scy`, `scylla`, `datastax`, `cql`        | [github.com/MichaelS11/go-cql-driver][d-cassandra]                          |\n| ChaiSQL              | `chai`          | `ci`, `genji`, `chaisql`                        | [github.com/chaisql/chai/driver][d-chai]                                    |\n| Couchbase            | `couchbase`     | `n1`, `n1ql`                                    | [github.com/couchbase/go_n1ql][d-couchbase]                                 |\n| Cznic QL             | `ql`            | `cznic`, `cznicql`                              | [modernc.org/ql][d-ql]                                                      |\n| Databend             | `databend`      | `dd`, `bend`                                    | [github.com/datafuselabs/databend-go][d-databend]                           |\n| Databricks           | `databricks`    | `br`, `brick`, `bricks`, `databrick`            | [github.com/databricks/databricks-sql-go][d-databricks]                     |\n| DuckDB               | `duckdb`        | `dk`, `ddb`, `duck`, `file`                     | [github.com/marcboeker/go-duckdb/v2][d-duckdb] \u003csup\u003e[†][f-cgo]\u003c/sup\u003e        |\n| DynamoDb             | `dynamodb`      | `dy`, `dyn`, `dynamo`, `dynamodb`               | [github.com/btnguyen2k/godynamo][d-dynamodb]                                |\n| Exasol               | `exasol`        | `ex`, `exa`                                     | [github.com/exasol/exasol-driver-go][d-exasol]                              |\n| Firebird             | `firebird`      | `fb`, `firebirdsql`                             | [github.com/nakagami/firebirdsql][d-firebird]                               |\n| FlightSQL            | `flightsql`     | `fl`, `flight`                                  | [github.com/apache/arrow/go/v17/arrow/flight/flightsql/driver][d-flightsql] |\n| Google BigQuery      | `bigquery`      | `bq`                                            | [gorm.io/driver/bigquery/driver][d-bigquery]                                |\n| Google Spanner       | `spanner`       | `sp`                                            | [github.com/googleapis/go-sql-spanner][d-spanner]                           |\n| Microsoft ADODB      | `adodb`         | `ad`, `ado`                                     | [github.com/mattn/go-adodb][d-adodb]                                        |\n| ModernC SQLite3      | `moderncsqlite` | `mq`, `modernsqlite`                            | [modernc.org/sqlite][d-moderncsqlite]                                       |\n| MySQL MyMySQL        | `mymysql`       | `zm`, `mymy`                                    | [github.com/ziutek/mymysql/godrv][d-mymysql]                                |\n| Netezza              | `netezza`       | `nz`, `nzgo`                                    | [github.com/IBM/nzgo/v12][d-netezza]                                        |\n| PostgreSQL PGX       | `pgx`           | `px`                                            | [github.com/jackc/pgx/v5/stdlib][d-pgx]                                     |\n| Presto               | `presto`        | `pr`, `prs`, `prestos`, `prestodb`, `prestodbs` | [github.com/prestodb/presto-go-client/presto][d-presto]                     |\n| RamSQL               | `ramsql`        | `rm`, `ram`                                     | [github.com/proullon/ramsql/driver][d-ramsql]                               |\n| SAP ASE              | `sapase`        | `ax`, `ase`, `tds`                              | [github.com/thda/tds][d-sapase]                                             |\n| SAP HANA             | `saphana`       | `sa`, `sap`, `hana`, `hdb`                      | [github.com/SAP/go-hdb/driver][d-saphana]                                   |\n| Snowflake            | `snowflake`     | `sf`                                            | [github.com/snowflakedb/gosnowflake][d-snowflake]                           |\n| Trino                | `trino`         | `tr`, `trs`, `trinos`                           | [github.com/trinodb/trino-go-client/trino][d-trino]                         |\n| Vertica              | `vertica`       | `ve`                                            | [github.com/vertica/vertica-sql-go][d-vertica]                              |\n| VoltDB               | `voltdb`        | `vo`, `vdb`, `volt`                             | [github.com/VoltDB/voltdb-client-go/voltdbclient][d-voltdb]                 |\n| YDB                  | `ydb`           | `yd`, `yds`, `ydbs`                             | [github.com/ydb-platform/ydb-go-sdk/v3][d-ydb]                              |\n|                      |                 |                                                 |                                                                             |\n| GO DRiver for ORacle | `godror`        | `gr`                                            | [github.com/godror/godror][d-godror] \u003csup\u003e[†][f-cgo]\u003c/sup\u003e                  |\n| ODBC                 | `odbc`          | `od`                                            | [github.com/alexbrainman/odbc][d-odbc] \u003csup\u003e[†][f-cgo]\u003c/sup\u003e                |\n|                      |                 |                                                 |                                                                             |\n| Amazon Redshift      | `postgres`      | `rs`, `redshift`                                | [github.com/lib/pq][d-postgres] \u003csup\u003e[‡][f-wire]\u003c/sup\u003e                      |\n| CockroachDB          | `postgres`      | `cr`, `cdb`, `crdb`, `cockroach`, `cockroachdb` | [github.com/lib/pq][d-postgres] \u003csup\u003e[‡][f-wire]\u003c/sup\u003e                      |\n| OLE ODBC             | `adodb`         | `oo`, `ole`, `oleodbc`                          | [github.com/mattn/go-adodb][d-adodb] \u003csup\u003e[‡][f-wire]\u003c/sup\u003e                 |\n| SingleStore MemSQL   | `mysql`         | `me`, `memsql`                                  | [github.com/go-sql-driver/mysql][d-mysql] \u003csup\u003e[‡][f-wire]\u003c/sup\u003e            |\n| TiDB                 | `mysql`         | `ti`, `tidb`                                    | [github.com/go-sql-driver/mysql][d-mysql] \u003csup\u003e[‡][f-wire]\u003c/sup\u003e            |\n| Vitess Database      | `mysql`         | `vt`, `vitess`                                  | [github.com/go-sql-driver/mysql][d-mysql] \u003csup\u003e[‡][f-wire]\u003c/sup\u003e            |\n|                      |                 |                                                 |                                                                             |\n|                      |                 |                                                 |                                                                             |\n\n[d-adodb]: https://github.com/mattn/go-adodb\n[d-athena]: https://github.com/uber/athenadriver\n[d-avatica]: https://github.com/apache/calcite-avatica-go\n[d-bigquery]: https://github.com/go-gorm/bigquery\n[d-cassandra]: https://github.com/MichaelS11/go-cql-driver\n[d-chai]: https://github.com/chaisql/chai\n[d-clickhouse]: https://github.com/ClickHouse/clickhouse-go\n[d-cosmos]: https://github.com/btnguyen2k/gocosmos\n[d-couchbase]: https://github.com/couchbase/go_n1ql\n[d-csvq]: https://github.com/mithrandie/csvq-driver\n[d-databend]: https://github.com/datafuselabs/databend-go\n[d-databricks]: https://github.com/databricks/databricks-sql-go\n[d-duckdb]: https://github.com/marcboeker/go-duckdb\n[d-dynamodb]: https://github.com/btnguyen2k/godynamo\n[d-exasol]: https://github.com/exasol/exasol-driver-go\n[d-firebird]: https://github.com/nakagami/firebirdsql\n[d-flightsql]: https://github.com/apache/arrow/tree/main/go/arrow/flight/flightsql/driver\n[d-godror]: https://github.com/godror/godror\n[d-h2]: https://github.com/jmrobles/h2go\n[d-hive]: https://github.com/sql-machine-learning/gohive\n[d-ignite]: https://github.com/amsokol/ignite-go-client\n[d-impala]: https://github.com/sclgo/impala-go\n[d-maxcompute]: https://github.com/sql-machine-learning/gomaxcompute\n[d-moderncsqlite]: https://gitlab.com/cznic/sqlite\n[d-mymysql]: https://github.com/ziutek/mymysql\n[d-mysql]: https://github.com/go-sql-driver/mysql\n[d-netezza]: https://github.com/IBM/nzgo\n[d-odbc]: https://github.com/alexbrainman/odbc\n[d-oracle]: https://github.com/sijms/go-ora\n[d-ots]: https://github.com/aliyun/aliyun-tablestore-go-sql-driver\n[d-pgx]: https://github.com/jackc/pgx\n[d-postgres]: https://github.com/lib/pq\n[d-presto]: https://github.com/prestodb/presto-go-client\n[d-ql]: https://gitlab.com/cznic/ql\n[d-ramsql]: https://github.com/proullon/ramsql\n[d-sapase]: https://github.com/thda/tds\n[d-saphana]: https://github.com/SAP/go-hdb\n[d-snowflake]: https://github.com/snowflakedb/gosnowflake\n[d-spanner]: https://github.com/googleapis/go-sql-spanner\n[d-sqlite3]: https://github.com/mattn/go-sqlite3\n[d-sqlserver]: https://github.com/microsoft/go-mssqldb\n[d-trino]: https://github.com/trinodb/trino-go-client\n[d-vertica]: https://github.com/vertica/vertica-sql-go\n[d-voltdb]: https://github.com/VoltDB/voltdb-client-go\n[d-ydb]: https://github.com/ydb-platform/ydb-go-sdk\n\n\u003c!-- DRIVER DETAILS END --\u003e\n\n[f-cgo]: #f-cgo \"Requires CGO\"\n[f-wire]: #f-wire \"Wire compatible\"\n\n\u003cp\u003e\n  \u003ci\u003e\n    \u003ca id=\"f-cgo\"\u003e\u003csup\u003e†\u003c/sup\u003e Requires CGO\u003c/a\u003e\u003cbr\u003e\n    \u003ca id=\"f-wire\"\u003e\u003csup\u003e‡\u003c/sup\u003e Wire compatible (see respective driver)\u003c/a\u003e\n  \u003c/i\u003e\n\u003c/p\u003e\n\nAny protocol scheme `alias://` can be used in place of `protocol://`, and will\nwork identically with [`dburl.Parse`][goref-parse] and [`dburl.Open`][goref-open].\n\n## Installing\n\nInstall in the usual Go fashion:\n\n```sh\n$ go get github.com/xo/dburl@latest\n```\n\n## Using\n\n`dburl` does not import any of Go's SQL drivers, as it only provides a way to\n[parse][goref-parse] and [open][goref-open] database URL stylized connection\nstrings. As such, it is necessary to explicitly `import` the relevant SQL driver:\n\n```go\nimport (\n    // import Microsoft SQL Server driver\n    _ \"github.com/microsoft/go-mssqldb\"\n)\n```\n\nSee the [database schemes table][Schemes] above for a list of the\nexpected Go driver `import`'s.\n\nAdditional examples and API details can be found in [the `dburl` package\ndocumentation][goref-dburl].\n\n### URL Parsing Rules\n\n[`dburl.Parse`][goref-parse] and [`dburl.Open`][goref-open] rely primarily on\nGo's standard [`net/url.URL`][goref-net-url] type, and as such, parsing or\nopening database connection URLs with `dburl` are subject to the same rules,\nconventions, and semantics as [Go's `net/url.Parse` func][goref-net-url-parse].\n\n## Example\n\nA [full example](_example/example.go) for reference:\n\n```go\n// _example/example.go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"log\"\n\n\t_ \"github.com/microsoft/go-mssqldb\"\n\t\"github.com/xo/dburl\"\n)\n\nfunc main() {\n\tdb, err := dburl.Open(\"sqlserver://user:pass@localhost/dbname\")\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tvar name string\n\tif err := db.QueryRow(`SELECT name FROM mytable WHERE id=10`).Scan(\u0026name); err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tfmt.Println(\"name:\", name)\n}\n```\n\n## Scheme Resolution\n\nBy default on non-Windows systems, `dburl` will resolve paths on disk, and URLs\nwith `file:` schemes to an appropriate database driver:\n\n1. Directories will resolve as `postgres:` URLs\n2. Unix sockets will resolve as `mysql:` URLs\n3. Regular files will have their headers checked to determine if they are\n   either `sqlite3:` or `duckdb:` files\n4. Non-existent files will test their file extension against well-known\n   `sqlite3:` and `duckdb:` file extensions and open with the appropriate\n   scheme\n\nIf this behavior is undesired, it can be disabled by providing different\nimplementations for [`dburl.Stat`][goref-variables] and [`dburl.OpenFile`][goref-variables],\nor alternately by setting [`dburl.ResolveSchemeType`][goref-variables] to false:\n\n```go\nimport \"github.com/xo/dburl\"\n\nfunc init() {\n    dburl.ResolveSchemeType = false\n}\n```\n\n## About\n\n`dburl` was built primarily to support these projects:\n\n- [usql][usql] - a universal command-line interface for SQL databases\n- [xo][xo] - a command-line tool to generate code for SQL databases\n\n[go-project]: https://go.dev/project\n[goref-open]: https://pkg.go.dev/github.com/xo/dburl#Open\n[goref-variables]: https://pkg.go.dev/github.com/xo/dburl#pkg-variables\n[goref-parse]: https://pkg.go.dev/github.com/xo/dburl#Parse\n[goref-sql-db]: https://pkg.go.dev/database/sql#DB\n[goref-net-url]: https://pkg.go.dev/net/url#URL\n[goref-net-url-parse]: https://pkg.go.dev/net/url#URL.Parse\n[usql]: https://github.com/xo/usql\n[xo]: https://github.com/xo/xo\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxo%2Fdburl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxo%2Fdburl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxo%2Fdburl/lists"}