https://github.com/seddryck/duburl
DubUrl provides a standardized URL-style mechanism for providing database connection information and opening a DbConnection in the .NET ecosystem
https://github.com/seddryck/duburl
ado-net adonet connection-string connection-uri connection-url database database-url duckdb mysql odbc oledb oracle postgresql power-bi-dax sql sql-server sqlite
Last synced: about 1 month ago
JSON representation
DubUrl provides a standardized URL-style mechanism for providing database connection information and opening a DbConnection in the .NET ecosystem
- Host: GitHub
- URL: https://github.com/seddryck/duburl
- Owner: Seddryck
- License: apache-2.0
- Created: 2022-06-05T13:23:06.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-04-16T15:41:07.000Z (about 1 month ago)
- Last Synced: 2025-04-16T22:03:26.788Z (about 1 month ago)
- Topics: ado-net, adonet, connection-string, connection-uri, connection-url, database, database-url, duckdb, mysql, odbc, oledb, oracle, postgresql, power-bi-dax, sql, sql-server, sqlite
- Language: C#
- Homepage:
- Size: 5.02 MB
- Stars: 3
- Watchers: 2
- Forks: 1
- Open Issues: 68
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# DubUrl
DubUrl provides a standard, URL style mechanism for parsing database connection strings and opening DbConnections for .NET. With DubUrl, you can parse and open URLs for popular databases such as Microsoft SQL Server, PostgreSQL, MySQL, SQLite3, Oracle Database and most of the other SQL databases. This project is inspired from the package [dburl](https://pkg.go.dev/github.com/xo/[email protected]/_example) available in the GoLang ecosystem and is trying to match the aliases for portocols.
[About][] | [Overview][] | [Quickstart][] | [Examples][] | [Schemes][] | [Installing][] | [Using][]
[About]: #about (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
**Social media:** [](https://seddryck.github.io/DubUrl)
[](https://twitter.com/Seddryck)
**Releases:** [](https://www.nuget.org/packages/DubUrl/) [](https://github.com/Seddryck/DubUrl/blob/master/LICENSE)
**Dev. activity:** [](https://github.com/Seddryck/DubUrl/commits)
**Continuous integration builds:** [](https://ci.appveyor.com/project/Seddryck/DubUrl/)
[](https://ci.appveyor.com/project/Seddryck/DubUrl/build/tests)
[](https://www.codefactor.io/repository/github/seddryck/duburl)
[](https://codecov.io/github/Seddryck/DubUrl)
[](https://app.fossa.com/projects/git%2Bgithub.com%2FSeddryck%2FDubUrl?ref=badge_shield)
**Status:** [](https://github.com/Seddryck/DubUrl/stargazers)
[](https://github.com/Seddryck/DubUrl/issues?utf8=%E2%9C%93&q=is:issue+is:open+label:bug+)
[](https://github.com/Seddryck/DubUrl/search?l=C%23)
[](https://seddryck.github.io/DubUrl/docs/native-ado-net-providers)
[](https://seddryck.github.io/DubUrl/docs/odbc-driver-locators)
[](https://seddryck.github.io/DubUrl/docs/oledb-provider-locators)
[](https://seddryck.github.io/DubUrl/docs/adomd-providers)
[](https://github.com/Seddryck/DubUrl/issues?utf8=%E2%9C%93&q=is:issue+is:open+label:new-feature+)
[](https://github.com/Seddryck/DubUrl/issues?utf8=%E2%9C%93&q=is:issue+is:open+label:new-database+)
[](https://github.com/Seddryck/DubUrl/issues?utf8=%E2%9C%93&q=is:issue+is:open+label:ado-net-provider+)
[](https://github.com/Seddryck/DubUrl/issues?utf8=%E2%9C%93&q=is:issue+is:open+label:odbc-driver-locator+)
## Database Connection URL Overview
Supported database connection URLs are of the form:
```text
driver:alias://user:pass@host/dbname?opt1=a&opt2=b
```
Where:
| Component | Description |
|--------------------|--------------------------------------------------------------------------------------|
| alias | database type (see below) |
| driver | driver/provider name (only for 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 to a standard connection string with the [`Parse`] as such:
```csharp
string connectionUrl = "mssql://{server}/{database_name}";
string connectionString = new ConnectionUrl(connectionUrl).Parse();
```
Additionally, a simple helper, [`Open`], is provided that will parse, open, and return a [standard `DbConnection`](https://docs.microsoft.com/en-us/dotnet/api/system.data.common.dbconnection).
```csharp
string connectionUrl = "mssql://{server}/{database_name}";
IDbConnection connection = new ConnectionUrl(connectionUrl).Open();
```
If you don't want to open the connection but only return it and manage its state by yourself, use the function [`Connect`]
```csharp
string connectionUrl = "mssql://{server}/{database_name}";
IDbConnection connection = new ConnectionUrl(connectionUrl).Connect();
```
## Example URLs
The following are example database connection URLs that can be handled by
[`Parse`], [`Connect`] and [`Open`]:
```text
mssql://user:[email protected]/instance/dbname?keepAlive=10
oledb+mssql://user:pass@localhost/dbname
postgres://user:pass@localhost/dbname
odbc+postgres://user:pass@localhost:port/dbname?option1=
mysql://user:pass@localhost/dbname
oracle://user:[email protected]/sid
db2://user:pass@localhost/dbname
```
## Protocol Schemes and Aliases
### ADO.Net data providers
The following databases and their associated schemes are supported out of the box:
|Database | Aliases | Provider Invariant Name |
|------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | -------------------------------|
| | mssql, ms, sqlserver, mssqlserver | Microsoft.Data.SqlClient |
| | mysql, my | MySqlConnector |
| | pg, pgx, pgsql, postgres, postgresql | Npgsql |
| | oracle, or, ora | Oracle.ManagedDataAccess |
| | db2 | IBM.Data.Db2 |
| | maria, mariadb | MySqlConnector |
| | duck, duckdb | DuckDB.NET.Data |
| | fb, firebird | FirebirdSql.Data.FirebirdClient|
| | sq, sqlite | Microsoft.Data.Sqlite |
| | td, teradata, tera | Teradata.Client |
| | sf, snowflake | Snowflake.Data |
| | cr, cockroach, cockroachdb, crdb, cdb | Npgsql |
| | crt, crate, cratedb | Npgsql |
| | sg, sgs, singlestore, single | SingleStoreConnector |
| | tr, trino | NReco.PrestoAdo |
| | quest, questdb | Npgsql |
| | ts, timescale | Npgsql |
### ODBC driver locators
The following databases and their associated schemes are supported out of the box:
|Database | Aliases | Name Pattern |
|------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ | ---------------------------------------------------------------------------|
| | mssql, ms, sqlserver, mssqlserver | ^\bODBC Driver\s([0-9]{1,2}(?:\.[0-9]{1,2}){0,2})\s\bfor SQL Server$ |
| | mysql, my | ^\bMySQL ODBC\s([0-9]{1,2}(?:\.[0-9]{1,2}){0,2})\s(ANSI\|Unicode)\s\bDriver$|
| | pg, pgx, pgsql, postgres, postgresql | ^\bPostgreSQL\s(ANSI\|Unicode)(\(x64\))?$ |
| | maria, mariadb | ^\bMariaDB ODBC\s([0-9]{1,2}(?:\.[0-9]{1,2}){0,2})\s\bDriver$ |
| | duck, duckdb | ^\bDuckDB\s\bDriver$ |
| | drill | ^\bMapR Drill ODBC Driver$ |
| | tr, trino | ^(Simba)\s\bTrino ODBC Driver$ |
| | accdb, access, msaccess, mdb | ^\bMicrosoft Access Driver\s\(\*\.mdb, \*\.accdb\)$ |
| | xls, xlsx, xlsb, xlsm | ^\bMicrosoft Excel Driver\s\(\*\.xls, \*\.xlsx, \*\.xlsm, \*\.xlsb\)$ |
| | txt, csv, tsv | ^\bMicrosoft Access Text Driver\s\(\*\.txt, \*\.csv\)$ |
| | quest, questdb | ^\bPostgreSQL\s(ANSI\|Unicode)(\(x64\))?$ |
| | ts, timescale | ^\bPostgreSQL\s(ANSI\|Unicode)(\(x64\))?$ |
### Extension for OLEDB provider locators
The following databases and their associated schemes are supported through the OLE DB data provider extension:
|Database | Aliases | Name Pattern |
|------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------|
| | mssql, ms, sqlserver, mssqlserver | ^\bMSOLEDBSQL$ |
| | mysql, my | ^\bMySQL Provider$ |
| | xls | ^\bMicrosoft\.ACE\.OLEDB\.([0-9]{1,2}(?:\.[0-9]{1,2}){0,2})$|
| | xlsx | ^\bMicrosoft\.ACE\.OLEDB\.([0-9]{1,2}(?:\.[0-9]{1,2}){0,2})$|
| | xlsm | ^\bMicrosoft\.ACE\.OLEDB\.([0-9]{1,2}(?:\.[0-9]{1,2}){0,2})$|
| | xlsb | ^\bMicrosoft\.ACE\.OLEDB\.([0-9]{1,2}(?:\.[0-9]{1,2}){0,2})$|
| | accdb, access, msaccess, mdb | ^\bMicrosoft\.ACE\.OLEDB\.([0-9]{1,2}(?:\.[0-9]{1,2}){0,2})$|
### Extension for ADOMD.NET data provider
The following databases and their associated schemes are supported through the ADOMD.NET data provider extension:
|Database | Aliases | Provider Invariant Name |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | --------------------------------------|
| | asazure, asa | Microsoft.AnalysisServices.AdomdClient|
| | pbidesktop, pbix, powerbidesktop | Microsoft.AnalysisServices.AdomdClient|
| | powerbi, pbi, pbiazure, pbipremium, powerbipremium | Microsoft.AnalysisServices.AdomdClient|
| | ssasmultidim, ssasmdx | Microsoft.AnalysisServices.AdomdClient|
| | ssastabular, ssasdax | Microsoft.AnalysisServices.AdomdClient|
## Installing
Install in the usual .NET fashion:
```sh
Install-Package DubUrl
```
To install the extension for OLEDB provider locators
```sh
Install-Package DubUrl.OleDb
```
To install the extension for ADOMD.NET data provider
```sh
Install-Package DubUrl.Adomd
```
## Using
Check the [first steps guide](https://seddryck.github.io/DubUrl/docs/basics-connection-url/) on the website.
Please note that `DubUrl` does not install actual drivers, and only provides a standard way to [`Parse`] respective database connection URLs then [`Connect`] or [`Open`] connections.