DubUrl

The duburl command-line tool validates, renders, and deploys versioned database schema documents. The duburl-worker tool hosts reusable application services over persistent JSON-RPC on standard input and output. 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 available in the GoLang ecosystem and is trying to match the aliases for portocols.

About | Overview | Quickstart | Examples | Schemes | Installing | Using

About

Social media:

Releases:

Dev. activity:

Continuous integration builds:

Status:

Database Connection URL Overview

Supported database connection URLs are of the form:

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

DuckDB is also available through ADBC with DubUrl.Adbc and DubUrl.Provider.DuckDb. See ADBC provider setup for registration and examples.

Database connection URLs in the above format can be parsed to a standard connection string with the [Parse] as such:

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.

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]

string connectionUrl = "mssql://{server}/{database_name}";
IDbConnection connection = new ConnectionUrl(connectionUrl).Connect();

When to use dependency injection

Use DubUrl.Extensions and services.AddDubUrl() when an ASP.NET Core application or worker already uses DI, or when you want centralized configuration, query logging and controlled registries for tests. Inject ConnectionUrlFactory or IDatabaseUrlFactory into your services. For small programs, constructing ConnectionUrl directly is sufficient: both approaches share Core's registry cache. Default DI factories observe connector changes for each new URL; explicitly supplied registries remain fixed. See the DI setup and lifetime guide.

Example URLs

The following are example database connection URLs that can be handled by [Parse], [Connect] and [Open]:

mssql://user:pass@remote-host.com/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:pass@somehost.com/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
	mysql, my	MySqlConnector
	mssql, ms, sqlserver, mssqlserver	Microsoft.Data.SqlClient
	pg, pgx, pgsql, postgres, postgresql	Npgsql
	db2	IBM.Data.Db2
	maria, mariadb	MySqlConnector
	oracle, or, ora	Oracle.ManagedDataAccess
	duck, duckdb	DuckDB.NET.Data
	fb, firebird	FirebirdSql.Data.FirebirdClient
	sq, sqlite	Microsoft.Data.Sqlite
	sf, snowflake	Snowflake.Data
	crt, crate, cratedb	Npgsql
	td, teradata, tera, teradatasql	Teradata.Client
	cr, cockroach, cockroachdb, crdb, cdb	Npgsql
	sg, sgs, singlestore, single, singlestoredb	SingleStoreConnector
	tr, trino	NReco.PrestoAdo
	ts, timescale	Npgsql
	quest, questdb	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))?$

On Windows, DubUrl discovers ODBC drivers through the machine and user registries. On Linux, discovery uses odbcinst -q -d, respecting unixODBC's configured registry (including ODBCSYSINI and ODBCINSTINI). Install unixodbc, odbcinst, and the ODBC driver for your database before using automatic discovery. Other platforms continue to use the standard ODBC INI file locations.

Supply an exact Driver URL option to bypass discovery. Driver names may be braced or unbraced; URL-encode spaces and reserved characters:

odbc+pgsql://user:password@localhost:5432/database?Driver=PostgreSQL%20Unicode

PostgreSQL and Timescale ODBC URLs emit separate Server and Port properties. The PostgreSQL provider QA workflow verifies explicit drivers and automatic discovery against a real PostgreSQL database on Linux.

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$
	oracle, or, ora	^\bOraOLEDB.Oracle$
	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 the provider-neutral library, the database implementation, and its driver. For PostgreSQL:

dotnet add package DubUrl
dotnet add package DubUrl.Provider.PostgreSql
dotnet add package Npgsql

Then new ConnectionUrl("pg://localhost/demo") works through automatic discovery. DubUrl does not install every provider. It replaces the DubUrl.Core package while retaining the DubUrl.Core.dll assembly and existing namespaces. Existing aggregate users must add their chosen provider packages.

To install the extension for OLEDB provider locators

Install-Package DubUrl.OleDb

To install the extension for ADOMD.NET data provider

Install-Package DubUrl.Adomd

Using

Check the first steps guide 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.