Help us shape the future of Go! Take the 2026 Go Developer Survey

dburl

package module
v0.54.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 29, 2026 License: MIT Imports: 17 Imported by: 551

README

About dburl

Package dburl parses and opens SQL database connection strings for Go, in a standard URL style. It handles the URL formats of PostgreSQL, MySQL, SQLite3, Oracle Database and Microsoft SQL Server. It also handles most other SQL databases that have a public Go driver.

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

Unit Tests Go Reference Discord Discussion

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", "http", "https", or a driver name for odbc
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 takes the form /service/dbname. Here /service is the service name or SID, and /dbname is optional. See the examples below.

Quickstart

The dburl.Parse func parses a database connection URL in the format above:

import (
    "github.com/xo/dburl"
)

u, err := dburl.Parse("postgresql://user:pass@localhost/mydatabase/?sslmode=disable")
if err != nil { /* ... */ }

dburl.Open parses the URL and returns an open standard sql.DB database connection:

import (
    "github.com/xo/dburl"
)

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

Example URLs

dburl.Parse and dburl.Open handle database connection URLs such as these:

postgres://user:pass@localhost/dbname
pg://user:pass@localhost/dbname?sslmode=disable
pq://user:pass@localhost/dbname
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
cassandra://user:pass@localhost/keyspace?consistency=localQuorum
sqlite:/path/to/file.db
file:myfile.sqlite3?loc=auto
odbc+postgres://user:pass@localhost:port/dbname?option1=

Database Schemes, Aliases, and Drivers

The table lists every supported dburl protocol scheme, with its aliases and its Go driver. A parsed URL names the scheme in URL.SchemeName and the name to pass to sql.Open in URL.Driver. The two differ when a scheme opens a driver that another product also uses: tidb opens mysql, postgres, cockroachdb and redshift open pgx, and pq opens postgres, which is the name that github.com/lib/pq registers. dburl.Open passes URL.Driver to sql.Open:

Database Scheme / Tag Scheme Aliases Driver Package / Notes
PostgreSQL postgres pg, pgsql, postgresql github.com/jackc/pgx/v5/stdlib
MySQL mysql my, maria, aurora, mariadb, percona github.com/go-sql-driver/mysql
Microsoft SQL Server sqlserver ms, mssql, azuresql github.com/microsoft/go-mssqldb
Oracle Database oracle or, ora, oci, oci8, odpi, odpi-c github.com/sijms/go-ora/v3
SQLite3 sqlite3 sq, sqlite, file github.com/mattn/go-sqlite3 † §
DuckDB duckdb dk, ddb, duck, file github.com/duckdb/duckdb-go/v2 † §
ClickHouse clickhouse ch github.com/xo/dbimp/clickhouse
CSVQ csvq cs, csv, tsv, json github.com/mithrandie/csvq-driver §
Alibaba MaxCompute maxcompute mc github.com/xo/dbimp/maxcompute
Alibaba Tablestore tablestore ot, ots github.com/xo/dbimp/tablestore
Amazon Athena athena s3, aws, awsathena github.com/xo/dbimp/athena
Amazon Redshift redshift rs github.com/jackc/pgx/v5/stdlib
Apache Avatica avatica av, phoenix github.com/xo/dbimp/avatica
Apache Drill drill dl github.com/xo/dbimp/drill
Apache Druid druid dr github.com/xo/dbimp/druid
Apache H2 h2 github.com/jmrobles/h2go
Apache Hive hive hi, hive2 github.com/beltran/gohive/v2
Apache Impala impala im github.com/sclgo/impala-go
Apache Pinot pinot pi github.com/xo/dbimp/pinot
Apache Solr solr so github.com/xo/dbimp/solr
ArangoDB arangodb ar, arango github.com/xo/dbimp/arangodb
Azure Cosmos DB cosmos cm github.com/xo/dbimp/cosmos
Cassandra cassandra ca, cql, scy, cass, scylla, datastax github.com/xo/cassandra
ChaiSQL chai ci, genji, chaisql github.com/chaisql/chai §
CockroachDB cockroachdb cr, cdb, crdb, cockroach github.com/jackc/pgx/v5/stdlib
Couchbase couchbase n1, n1ql github.com/xo/dbimp/couchbase
CrateDB cratedb ct, crate github.com/jackc/pgx/v5/stdlib
Databend databend dd, bend github.com/xo/dbimp/databend
Databricks databricks br, brick, bricks, databrick github.com/xo/dbimp/databricks
DynamoDB dynamodb dy, dyn, dynamo github.com/xo/dbimp/dynamodb
Elasticsearch elasticsearch es, elastic github.com/xo/dbimp/elasticsearch
Exasol exasol ex, exa github.com/xo/dbimp/exasol
Firebird firebirdsql fb, firebird github.com/nakagami/firebirdsql
FlightSQL flightsql fl, flight github.com/apache/arrow-go/v18/arrow/flight/flightsql/driver
GizmoSQL gizmosql gz, gizmo github.com/apache/arrow-go/v18/arrow/flight/flightsql/driver
Google BigQuery bigquery bq github.com/xo/dbimp/bigquery
Google Spanner spanner sp github.com/xo/dbimp/spanner
InfluxDB influxdb in, influx github.com/xo/dbimp/influxdb
InfluxDB InfluxQL influxql iq github.com/xo/dbimp/influxdb
libSQL libsql ls, turso github.com/xo/dbimp/libsql
ModernC SQLite3 moderncsqlite mq, modernsqlite modernc.org/sqlite §
Neo4j neo4j nj, neo, n4j github.com/xo/dbimp/neo4j
ODBC odbc od github.com/xo/odbc
OpenSearch opensearch os, open github.com/xo/dbimp/opensearch
PostgreSQL lib/pq pq libpq github.com/lib/pq
PostgreSQL PGX pgx px github.com/jackc/pgx/v5/stdlib
Presto presto pr, prestodb github.com/xo/dbimp/trino
QuestDB questdb qs github.com/jackc/pgx/v5/stdlib
rqlite rqlite rq github.com/xo/dbimp/rqlite
SAP HANA hdb sa, sap, hana, saphana github.com/SAP/go-hdb/driver
SingleStore MemSQL memsql me github.com/go-sql-driver/mysql
Snowflake snowflake sf github.com/xo/dbimp/snowflake
SurrealDB surrealdb sr, sur, surreal github.com/xo/dbimp/surrealdb
TiDB tidb ti github.com/go-sql-driver/mysql
Trino trino tr github.com/xo/dbimp/trino
Vertica vertica ve github.com/vertica/vertica-sql-go
Vitess Database vitess vt github.com/go-sql-driver/mysql
VoltDB voltdb vo, vdb, volt github.com/VoltDB/voltdb-client-go/voltdbclient
YDB ydb yd github.com/ydb-platform/ydb-go-sdk/v3

† Requires CGO
§ Embedded, with no server to run
Hosted service, with no server you can run

You can write any alias as alias:// in place of protocol://. dburl.Parse and dburl.Open treat the two the same.

Installing

Install dburl with go get:

$ go get github.com/xo/dburl@latest

Using

dburl does not import any Go SQL driver. It only parses and opens database connection URLs, so you must import the SQL driver yourself:

import (
    // import Microsoft SQL Server driver
    _ "github.com/microsoft/go-mssqldb"
)

See the database schemes table above for the Go driver that each scheme expects.

The dburl package documentation has more examples and the API details.

URL Parsing Rules

dburl.Parse and dburl.Open build on Go's standard net/url.URL type. The same rules and conventions apply as for Go's net/url.Parse func.

Example

A full example:

// _example/example.go
package main

import (
	"fmt"
	"log"

	_ "github.com/microsoft/go-mssqldb"
	"github.com/xo/dburl"
)

func main() {
	db, err := dburl.Open("sqlserver://user:pass@localhost/dbname")
	if err != nil {
		log.Fatal(err)
	}
	var name string
	if err := db.QueryRow(`SELECT name FROM mytable WHERE id=10`).Scan(&name); err != nil {
		log.Fatal(err)
	}
	fmt.Println("name:", name)
}

Scheme Resolution

On systems other than Windows, dburl resolves a path on disk, or a URL with a file: scheme, to a database driver:

  1. A directory resolves as a postgres: URL.
  2. A Unix socket resolves as a mysql: URL.
  3. For a file that exists, dburl reads the file header and resolves it as a sqlite3: or a duckdb: URL.
  4. For a file that does not exist, dburl matches the file extension against the known sqlite3: and duckdb: extensions.

To turn this off, set dburl.ResolveSchemeType to false. You can also supply your own dburl.Stat and dburl.OpenFile funcs instead:

import "github.com/xo/dburl"

func init() {
    dburl.ResolveSchemeType = false
}

About

dburl exists to support these projects:

  • usql - a universal command-line interface for SQL databases
  • dbtpl - a command-line tool to generate code for SQL databases
  • dbmeta - a Go package that reads metadata from SQL databases

Documentation

Overview

Package dburl parses and opens SQL database connection strings for Go, in the style of net/url.URL.

It handles the URL formats of PostgreSQL, MySQL, SQLite3, Oracle Database and Microsoft SQL Server. It also handles most other SQL databases that have a public Go driver.

See the package documentation README section for more details.

Example 
package main

import (
	"log"

	"github.com/xo/dburl"
)

func main() {
	db, err := dburl.Open("my://user:pass@host:1234/dbname")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()
	res, err := db.Query("SELECT ...")
	if err != nil {
		log.Fatal(err)
	}
	for res.Next() {
		/* ... */
	}
	if err := res.Err(); err != nil {
		log.Fatal(err)
	}
}
Example (Parse) 
package main

import (
	"database/sql"
	"log"

	"github.com/xo/dburl"
)

func main() {
	u, err := dburl.Parse("pg://user:pass@host:1234/dbname")
	if err != nil {
		log.Fatal(err)
	}
	// Driver is the name that the Go driver registered, which is pgx here.
	db, err := sql.Open(u.Driver, u.DSN)
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()
	res, err := db.Query("SELECT ...")
	if err != nil {
		log.Fatal(err)
	}
	for res.Next() {
		/* ... */
	}
	if err := res.Err(); err != nil {
		log.Fatal(err)
	}
}

Index

Examples

Constants

This section is empty.

Variables

View Source 
var OdbcIgnoreQueryPrefixes []string

OdbcIgnoreQueryPrefixes are the query prefixes to ignore when generating the odbc DSN. Used by GenOdbc.

View Source 
var OpenFile = func(name string) (fs.File, error) {
	return os.OpenFile(name, os.O_RDONLY, 0)
}

OpenFile is the default open file func.

Used internally to read file headers.

View Source 
var ResolveSchemeType = true

ResolveSchemeType is a configuration setting to open paths on disk using SchemeType, Stat, and OpenFile. Set this to false in an `init()` func to disable this behavior.

View Source 
var Stat = func(name string) (fs.FileInfo, error) {
	return fs.Stat(os.DirFS(filepath.Dir(name)), filepath.Base(name))
}

Stat is the default stat func.

Used internally to stat files, and used when generating the DSNs for postgres://, mysql://, file:// schemes, and opaque URL's.

Functions

func BuildURL added in v0.23.0 

func BuildURL(components map[string]any) (string, error)

BuildURL creates a dsn using the mapped components.

Recognized components are: 

protocol, proto, scheme
transport
username, user
password, pass
hostname, host
port
path, file, opaque
database, dbname, db
instance
parameters, params, options, opts, query, q

See BuildURL for more information.

func DialectProtocols added in v0.32.0 

func DialectProtocols(name string) []string

DialectProtocols returns every protocol name and alias of the registered schemes that share the Dialect of the named scheme, sorted. A scheme with no Dialect returns its own Protocols.

For postgres it returns the names of postgres, pgx, pq and redshift. cockroachdb and cratedb speak PostgreSQL, and are products of their own, so each has a Dialect and a family of its own.

func FileTypes added in v0.18.0 

func FileTypes() []string

FileTypes returns the registered file types.

func GenArangoDB added in v0.36.0 

func GenArangoDB(u *URL) (string, string, error)

GenArangoDB generates an arangodb DSN from the passed URL.

Targets the driver planned in xo/dbimp/arangodb, which is to read an arangodb:// URL and refuse any other scheme. The user information, the path and the query pass through as they were written. It adds no port, because the driver defaults to 8529 (D34).

func GenAthena added in v0.50.0 

func GenAthena(u *URL) (string, string, error)

GenAthena generates an athena DSN from the passed URL.

Targets the driver xo/dbimp/athena, which reads an athena:// URL. The host is the endpoint, such as athena.us-east-1.amazonaws.com, and the driver reads the region from it. A host that is only a region, such as us-east-1, is the short form, and GenAthena writes the endpoint (D62 and D63). The path is the database, and the query takes workgroup, output, token and catalog. The user is the access key and the password is the secret key. The driver accepts a URL with neither, so GenAthena checks neither. A URL with no host returns ErrMissingHost. Everything else passes through as it was written (D59).

func GenAvatica added in v0.41.0 

func GenAvatica(u *URL) (string, string, error)

GenAvatica generates an avatica DSN from the passed URL.

Targets xo/dbimp/avatica, which reads an avatica:// URL and refuses any other scheme, and refuses a path. The user information and the query pass through as they were written. It adds no port, because the driver defaults to 8765, the port of an Avatica server (D34 and D47). The alias phoenix reaches the same driver.

func GenCassandra 

func GenCassandra(u *URL) (string, string, error)

GenCassandra generates a cassandra DSN from the passed URL.

Targets xo/cassandra, which reads a cassandra:// URL with net/url. The scheme is always cassandra, whichever alias was parsed, so cql:// and scylla:// reach the driver as cassandra://, which is the only scheme it reads. The user information and the path, which is the keyspace, pass through, and so does the query, as it was written, because the driver takes a host key that can repeat. It adds no port, because gocql defaults to 9042 (D34 and D56).

func GenClickhouse 

func GenClickhouse(u *URL) (string, string, error)

GenClickhouse generates a clickhouse DSN from the passed URL.

Targets xo/dbimp/clickhouse, which reads a clickhouse:// URL with net/url and speaks HTTP only. The user information, the path, which is the database, and the query pass through as they were written. The driver reads the tls key and refuses any other key. It adds no port, because the driver defaults to 8123, or 8443 with tls (D34). The transports +http and +https are gone, and so is the native protocol on 9000 (D53).

func GenCockroachDB added in v0.35.0 

func GenCockroachDB(u *URL) (string, string, error)

GenCockroachDB generates a cockroachdb DSN from the passed URL.

CockroachDB speaks the wire protocol of PostgreSQL, so the DSN is the one GenPgxFromURL writes, with the default port 26257 and sslmode=disable. It returns pgx as the driver. The scheme has a Dialect of its own, because it is a product of its own.

func GenCosmos added in v0.2.0 

func GenCosmos(u *URL) (string, string, error)

GenCosmos generates a cosmos DSN from the passed URL.

Targets the driver xo/dbimp/cosmos, which reads a cosmos:// URL. The host is the account, such as account.documents.azure.com, and a name with no dot gets that suffix (D62). The user is any text, and the password is the master key of the account as base64 text, so a URL with no host returns ErrMissingHost, and one with no password returns ErrMissingUser. The path is the database and the container, and the query takes tls, insecure, pagesize and partitionkey. Everything else passes through as it was written (D59).

func GenCouchbase added in v0.33.0 

func GenCouchbase(u *URL) (string, string, error)

GenCouchbase generates a couchbase DSN from the passed URL.

Targets xo/dbimp/couchbase, which reads a couchbase:// URL with net/url and refuses any other scheme. The user information, the path and the query pass through as they were written, and the driver refuses an unknown or repeated key, and a path other than "/". It adds no port, because the driver defaults to 8093, or 18093 with tls (D34).

func GenCrateDB added in v0.35.0 

func GenCrateDB(u *URL) (string, string, error)

GenCrateDB generates a cratedb DSN from the passed URL.

CrateDB speaks the wire protocol of PostgreSQL, so the DSN is the one GenPgxFromURL writes. It adds no port, because pgx defaults to 5432, which is the port of the PostgreSQL interface of CrateDB (D34). It returns pgx as the Go driver, as GenCockroachDB does.

func GenDatabend added in v0.12.5 

func GenDatabend(u *URL) (string, string, error)

GenDatabend generates a databend DSN from the passed URL.

Targets the driver planned in xo/dbimp/databend, which replaces databend-go and reads a databend:// URL and refuses any other scheme, so the scheme is always databend, whichever alias was parsed. The user information, the path, which names the database, and the query pass through as they were written. It adds no port, because the driver defaults to 8000, with TLS or without (D34 and D39).

func GenDatabricks added in v0.19.0 

func GenDatabricks(u *URL) (string, string, error)

GenDatabricks generates a databricks DSN from the passed URL.

Targets the driver xo/dbimp/databricks, which reads a databricks://token:<access token>@host/<warehouse id> URL. The host is the workspace, and a name with no dot gets the suffix .cloud.databricks.com (D62). The password is the access token, and the driver accepts only the user token or no user, so a URL with no host returns ErrMissingHost and one with no password returns ErrMissingUser. The path is the id of the SQL warehouse, so a URL with no path returns ErrMissingPath. The query takes catalog, schema, timeout and tls, and everything else passes through as it was written (D61).

func GenDrill added in v0.45.0 

func GenDrill(u *URL) (string, string, error)

GenDrill generates a drill DSN from the passed URL.

Targets the driver xo/dbimp/drill, which reads a drill:// URL and refuses any other scheme. The URL has no path, and the schema is the key schema. The user information and the query pass through as they were written, and the driver refuses a key it does not know. It adds no port, because the driver has its own default, which tls=true does not change (D34 and D54).

func GenDruid added in v0.42.0 

func GenDruid(u *URL) (string, string, error)

GenDruid generates a druid DSN from the passed URL.

Targets the driver xo/dbimp/druid, which reads a druid:// URL, refuses any other scheme, and refuses a path, because Druid has no database to choose. The user information and the query pass through as they were written. It adds no port, because the driver defaults to 8888, the port of the Druid Router (D34 and D48).

func GenDuckDB added in v0.23.3 

func GenDuckDB(u *URL) (string, string, error)

GenDuckDB generates a duckdb dsn from the passed URL.

func GenDynamo added in v0.19.0 

func GenDynamo(u *URL) (string, string, error)

GenDynamo generates a dynamodb DSN from the passed URL.

Targets the driver xo/dbimp/dynamodb, which reads a dynamodb:// URL. The host is the endpoint, such as dynamodb.us-east-1.amazonaws.com, and the region is the key region, which the driver requires. A host that is only a region, such as us-east-1, is the short form: GenDynamo writes the endpoint of the region, and names the region in the key when the URL has none (D62 and D63). The user is the access key and the password is the secret key, and the signature needs both, so a URL without one returns ErrMissingUser. The driver speaks HTTPS unless the URL names tls=false, and refuses a path and any other key. The user information and the query pass through. It adds no port, because the driver uses the port of the scheme (D34 and D55).

func GenElasticsearch added in v0.45.0 

func GenElasticsearch(u *URL) (string, string, error)

GenElasticsearch generates a elasticsearch DSN from the passed URL.

Targets the driver xo/dbimp/elasticsearch, which reads a elasticsearch:// URL and refuses any other scheme. The URL has no path, because Elasticsearch has no database to choose. The user information and the query pass through as they were written, and the driver refuses a key it does not know. It adds no port, because the driver has its own default, which tls=true does not change (D34 and D54).

func GenExasol added in v0.8.5 

func GenExasol(u *URL) (string, string, error)

GenExasol generates an exasol DSN from the passed URL.

Targets the driver xo/dbimp/exasol, which reads an exasol://user:password@host:port/schema URL. The user is required, so a URL with no user returns ErrMissingUser. The password and the schema, which is the path, are optional. The query takes tls, validateservercertificate, certificatefingerprint, compression, autocommit, fetchsize, querytimeout, clientname and protocol, and the driver refuses any other key and a repeated one. The user information, the path and the query pass through as they were written. It adds no port, because the driver defaults to 8563 (D34 and D66).

func GenFirebird 

func GenFirebird(u *URL) (string, string, error)

GenFirebird generates a firebird DSN from the passed URL.

func GenFromURL 

func GenFromURL(urlstr string) func(*URL) (string, string, error)

GenFromURL returns a func that generates a DSN based on parameters of the passed URL.

The query is rebuilt with net/url.Values.Encode, which writes a space as a +, and a key that appears more than once is joined into one value with spaces. Do not use it for a driver that reads a + as itself, such as pgx, which has GenPgxFromURL, or for a driver that takes a repeated key.

func GenGizmoSQL added in v0.36.0 

func GenGizmoSQL(u *URL) (string, string, error)

GenGizmoSQL generates a flightsql DSN for GizmoSQL from the passed URL.

GizmoSQL serves Flight SQL, so the DSN is a flightsql:// URL, with the default port 31337, which is the port of GizmoSQL. The Flight SQL driver has no default port (D34). It returns flightsql as the Go driver.

func GenHive added in v0.28.1 

func GenHive(u *URL) (string, string, error)

GenHive generates a hive DSN from the passed URL.

Targets beltran/gohive/v2. Its ParseDSN rejects any string that does not start with "hive://", and reads the database name from the path.

The database name is required. An empty path is an error and not a default, so an absent name becomes "default".

The driver also cannot start without auth. Its connect path tests the accepted values in turn, and anything else reaches panic("Unrecognized auth"). The empty string is one of those, so an absent or empty auth becomes NONE. Any other value passes through untouched. See D16.

func GenInfluxDB added in v0.35.0 

func GenInfluxDB(u *URL) (string, string, error)

GenInfluxDB generates an influxdb DSN from the passed URL.

Targets the driver in xo/dbimp/influxdb, which reads an influxdb:// URL and refuses any other scheme. The user information, the path and the query pass through as they were written. It adds no driver option, so the driver reads sqlmode and version with its own defaults. See GenInfluxQL.

It adds no port, because the driver defaults to 8086 for version 1 and 2, and 8181 otherwise (D34).

func GenInfluxQL added in v0.35.0 

func GenInfluxQL(u *URL) (string, string, error)

GenInfluxQL generates an influxdb DSN for InfluxQL from the passed URL.

It writes the DSN as GenInfluxDB does, and adds sqlmode=disable when the URL does not name sqlmode, so that the driver speaks InfluxQL. It returns influxdb as the Go driver, because one driver serves both schemes.

func GenLibsql added in v0.40.0 

func GenLibsql(u *URL) (string, string, error)

GenLibsql generates a libsql DSN from the passed URL.

Targets xo/dbimp/libsql, which serves libSQL and Turso, reads a libsql:// URL and refuses any other scheme, and refuses a path. The token is the password of the URL. The user information and the query pass through as they were written. It adds no port, because the driver defaults to 443 with TLS, which is on by default, and needs an explicit port with tls=false (D34 and D45).

func GenMaxCompute added in v0.31.0 

func GenMaxCompute(u *URL) (string, string, error)

GenMaxCompute generates a maxcompute DSN from the passed URL.

Targets the driver xo/dbimp/maxcompute, which reads a maxcompute://id:key@host/project URL. The user is the access key id and the password is the access key secret, so a URL with no password returns ErrMissingUser. The path is the project, so a URL with no path returns ErrMissingPath, and a URL with no host returns ErrMissingHost. The host is service.<region>.maxcompute.aliyun.com, and the driver reads the region from it, or from the region option when the host has another form. The tls option passes through to the driver, and the endpoint path /api is the driver's (D68).

func GenModernCSqlite added in v0.53.0 

func GenModernCSqlite(u *URL) (string, string, error)

GenModernCSqlite generates a modernc.org/sqlite DSN from the passed URL. It is GenOpaque, and it names the driver sqlite, which is the name that modernc.org/sqlite registers with database/sql (D67).

func GenMysql added in v0.9.0 

func GenMysql(u *URL) (string, string, error)

GenMysql generates a mysql DSN from the passed URL.

It adds no port, because go-sql-driver/mysql defaults to 3306 (D34).

func GenNeo4j added in v0.35.0 

func GenNeo4j(u *URL) (string, string, error)

GenNeo4j generates a neo4j DSN from the passed URL.

Targets xo/dbimp/neo4j, which reads a neo4j:// URL with net/url and refuses any other scheme. The path names the database, and the driver reads an empty path as the database neo4j. The user information, the path and the query pass through as they were written. It adds no port, because the driver defaults to 7474, or 7473 with tls (D34).

func GenOdbc added in v0.9.0 

func GenOdbc(u *URL) (string, string, error)

GenOdbc generates an odbc DSN from the passed URL.

Targets xo/odbc, which reads an odbc+<driver>:// URL, so the URL passes through with its user information, host, port, path and query. The driver writes the connection string from it, and quotes a value that holds a ; or a brace (D52). GenOdbc adds no host, no port and no option, because the ODBC driver that the user installed owns each default (D34).

A query key that starts with a prefix in OdbcIgnoreQueryPrefixes is dropped, so a client can keep its own options out of the DSN. A URL with no driver, such as odbc://host/db, returns ErrMissingDriver.

func GenOpaque 

func GenOpaque(u *URL) (string, string, error)

GenOpaque generates a opaque file path DSN from the passed URL.

func GenOpensearch added in v0.45.0 

func GenOpensearch(u *URL) (string, string, error)

GenOpensearch generates a opensearch DSN from the passed URL.

Targets the driver xo/dbimp/opensearch, which reads a opensearch:// URL and refuses any other scheme. The URL has no path, because OpenSearch has no database to choose. The user information and the query pass through as they were written, and the driver refuses a key it does not know. It adds no port, because the driver has its own default, which tls=true does not change (D34 and D54).

func GenPgx added in v0.32.0 

func GenPgx(u *URL) (string, string, error)

GenPgx generates a pgx DSN from the passed URL.

Targets jackc/pgx/v5/stdlib, which reads a postgres:// URL with the same rules as libpq. Every component is percent-encoded, a space as %20, because the driver rejects a raw space and reads a + as itself. A unix socket directory cannot be a URL host, so it is passed as the host query option.

GenPgx supplies no default host and no default port, so the driver reads PGHOST and then its socket default. See GenPgxFromURL for one that does.

See GenPostgres, which lib/pq uses instead.

func GenPgxFromURL added in v0.32.0 

func GenPgxFromURL(urlstr string) func(*URL) (string, string, error)

GenPgxFromURL returns a func that generates a pgx DSN, taking the default host, port and query options from the passed URL. The parsed URL overrides each one it carries, as with GenFromURL.

Use it in place of GenFromURL for a scheme whose driver is pgx, because GenFromURL writes a space in a query option as a +, which pgx reads as itself.

func GenPinot added in v0.36.0 

func GenPinot(u *URL) (string, string, error)

GenPinot generates a pinot DSN from the passed URL.

Targets xo/dbimp/pinot, which reads a pinot:// URL and refuses any other scheme, and refuses a path. The user information, the path and the query pass through as they were written. It adds no port, because the driver defaults to 8099, the port of a Pinot broker (D34 and D43).

func GenPostgres 

func GenPostgres(u *URL) (string, string, error)

GenPostgres generates a postgres DSN from the passed URL.

Targets lib/pq, which reads the keyword/value form. A value holding a space, a quote or a backslash is quoted, as the parser requires.

See GenPgx, which postgres uses instead, and GenPq, which names the driver for the pq scheme.

func GenPq added in v0.36.0 

func GenPq(u *URL) (string, string, error)

GenPq generates a pq DSN from the passed URL.

It is the DSN of GenPostgres, and it names postgres as the driver, which is the name that lib/pq registers.

func GenPresto 

func GenPresto(u *URL) (string, string, error)

GenPresto generates a trino DSN for Presto from the passed URL.

Presto is a flavor of the driver that GenTrino targets. The DSN is the one GenTrino writes, with the key flavor set to presto, and the Dialect is presto. It returns trino as the name of the driver, because the driver registers one name (D50).

func GenQuestDB added in v0.36.0 

func GenQuestDB(u *URL) (string, string, error)

GenQuestDB generates a questdb DSN from the passed URL.

QuestDB speaks the wire protocol of PostgreSQL, so the DSN is the one GenPgxFromURL writes, with the default port 8812, which is the port of its PostgreSQL interface. pgx would use 5432 (D34). It returns pgx as the Go driver, as GenCrateDB does.

func GenRqlite added in v0.36.0 

func GenRqlite(u *URL) (string, string, error)

GenRqlite generates a rqlite DSN from the passed URL.

Targets xo/dbimp/rqlite, which reads a rqlite:// URL and refuses any other scheme, and refuses a path. The user information, the path and the query pass through as they were written. It adds no port, because the driver defaults to 4001, the port of the HTTP API of rqlite (D34 and D44).

func GenScheme 

func GenScheme(scheme string) func(*URL) (string, string, error)

GenScheme returns a generator that will generate a scheme based on the passed scheme DSN.

func GenSchemeHost added in v0.36.0 

func GenSchemeHost(scheme string) func(*URL) (string, string, error)

GenSchemeHost returns a generator that rewrites only the scheme, as GenScheme does, and that returns ErrMissingHost when the URL names no host. It is for a scheme whose host is not a server, such as the project of bigquery, where localhost is never right (D38).

func GenSnowflake 

func GenSnowflake(u *URL) (string, string, error)

GenSnowflake generates a snowflake DSN from the passed URL.

Targets xo/dbimp/snowflake, which reads a snowflake:// URL. The host is the full host of the account, such as org-account.snowflakecomputing.com, and the driver refuses a host that does not end that way. The user is the login user, and the password is the private key of the user, as the base64url text of its PKCS8 DER bytes. The key is the only way to sign in, so a URL with no host, no user or no password returns ErrMissingHost or ErrMissingUser. A host that does not end that way, has no port and is not an IP address is an account name, such as org-account, and GenSnowflake adds the suffix (D58). The path holds the database and the schema, and the query takes role, warehouse, timeout and timezone. Each one passes through as it was written, and the driver refuses any other key. It adds no port, because the driver uses 443 (D34 and D58).

func GenSolr added in v0.45.0 

func GenSolr(u *URL) (string, string, error)

GenSolr generates a solr DSN from the passed URL.

Targets the driver xo/dbimp/solr, which reads a solr:// URL and refuses any other scheme. The path is the name of one collection, and it is optional. The user information and the query pass through as they were written, and the driver refuses a key it does not know. It adds no port, because the driver has its own default, which tls=true does not change (D34 and D54).

func GenSpanner added in v0.2.0 

func GenSpanner(u *URL) (string, string, error)

GenSpanner generates a spanner DSN from the passed URL.

Targets xo/dbimp/spanner. The URL is spanner://host:port/project/instance/database?credential_file=/key.json, and it passes through with its user information and its whole query as they were written (D60 and D63). An empty host leaves the endpoint to the driver, as spanner:///p/i/d does, so GenSpanner adds no host. Parse reads a URL with no host and a path as a unix socket, so the scheme accepts that transport, and a spanner+unix URL is refused here. The path must name all three parts (D35).

func GenSqlserver added in v0.9.0 

func GenSqlserver(u *URL) (string, string, error)

GenSqlserver generates a sqlserver DSN from the passed URL.

A URL for azuresql, by its scheme or by the key fedauth, can name a server with no dot, such as myserver, and GenSqlserver adds .database.windows.net to it. A host with a port is left as it is (D62 and D63).

func GenSurrealDB added in v0.34.0 

func GenSurrealDB(u *URL) (string, string, error)

GenSurrealDB generates a surrealdb DSN from the passed URL.

Targets xo/dbimp/surrealdb, which reads a surrealdb:// URL with net/url and refuses any other scheme. The path names the namespace and the database, as /namespace/database, and passes through with its escaping. The user information and the query pass through as they were written. It adds no port, because the driver defaults to 8000 (D34). A path that does not name both returns ErrMissingPath (D38).

func GenTableStore added in v0.11.0 

func GenTableStore(u *URL) (string, string, error)

GenTableStore generates a tablestore DSN from the passed URL.

Targets the driver xo/dbimp/tablestore, which reads a tablestore://id:secret@host/instance URL. The user is the access key id and the password is the access key secret, so a URL with no password returns ErrMissingUser. The path is the instance, so a URL with no path returns ErrMissingPath, and a URL with no host returns ErrMissingHost. A host that is <instance>.<region> gets the suffix .ots.aliyuncs.com, and a host with no dot, such as localhost, does not (D68). The tls option passes through to the driver.

func GenTiDB added in v0.36.0 

func GenTiDB(u *URL) (string, string, error)

GenTiDB generates a tidb DSN from the passed URL.

It is the DSN of GenMysql, with the default port 4000, which is the port of TiDB. go-sql-driver/mysql would use 3306 (D34).

func GenTrino added in v0.27.0 

func GenTrino(u *URL) (string, string, error)

GenTrino generates a trino DSN from the passed URL.

Targets xo/dbimp/trino, which serves Trino and Presto, registers the name trino, reads a trino:// URL and refuses any other scheme. The path names the catalog and the schema, and each is optional. The path and the query pass through as they were written. It adds no port, because the driver defaults to 8080, and to 8443 with tls (D34).

Two things are written for the scheme (D50):

  • The driver requires a user, and a server that does no authentication accepts any name, so a URL with no user gets the user "user", as it always did. This is an exception to rule 10.
  • The scheme chooses the flavor: the key flavor is trino unless the URL names it, so the driver does not ask the server, and presto:// against a Trino server fails and does not act as Trino. This is an exception to rule 7, as sqlmode=disable is for influxql (D29).

The driver reads TLS from the tls key and never from the scheme, as every dbimp driver does, so no alias of the scheme means HTTPS.

func GenVoltdb added in v0.9.0 

func GenVoltdb(u *URL) (string, string, error)

GenVoltdb generates a voltdb DSN from the passed URL.

func GenYDB added in v0.19.0 

func GenYDB(u *URL) (string, string, error)

GenYDB generates a ydb dsn from the passed URL.

Targets ydb-platform/ydb-go-sdk/v3, which reads TLS from the scheme: grpcs is secure and grpc is not. The tls option chooses it, and is false by default. With tls=true the scheme is grpcs and the default port is 2135, and otherwise they are grpc and 2136. The aliases yds and ydbs are gone (D51).

func Open 

func Open(urlstr string) (*sql.DB, error)

Open takes a URL string, also known as a DSN, in the form of "protocol+transport://user:pass@host/dbname?option1=a&option2=b" and opens a standard sql.DB connection.

See Parse for information on formatting URL strings to work properly with Open.

func OpenMap added in v0.23.0 

func OpenMap(components map[string]any) (*sql.DB, error)

OpenMap takes a map of URL components and opens a standard sql.DB connection.

See BuildURL for information on the recognized map components.

func Protocols added in v0.12.0 

func Protocols(name string) []string

Protocols returns list of all valid protocol aliases for a registered Scheme name.

func Register 

func Register(scheme Scheme)

Register registers a Scheme.

func RegisterAlias 

func RegisterAlias(name, alias string)

RegisterAlias registers an additional alias for a registered scheme.

func RegisterFileType added in v0.18.0 

func RegisterFileType(driver string, f func([]byte) bool, ext string)

RegisterFileType registers a file header recognition func, and extension regexp.

func SchemeNameAndAliases added in v0.36.0 

func SchemeNameAndAliases(name string) (string, []string)

SchemeNameAndAliases returns the Name and the aliases of the registered scheme that name or an alias names. It was SchemeDriverAndAliases (D38).

func SchemeType added in v0.17.0 

func SchemeType(name string) (string, error)

SchemeType returns the scheme type for a path.

func ShortAlias added in v0.12.4 

func ShortAlias(name string) string

ShortAlias returns the short alias for the scheme name.

Types

type Deployment added in v0.29.0 

type Deployment uint

Deployment is the deployment kinds a database offers. 

const (
	// DeploymentEmbedded is a database with no server, used as a library.
	DeploymentEmbedded Deployment = 1
	// DeploymentServer is a database with a server that anyone can run.
	DeploymentServer Deployment = 2
	// DeploymentHosted is a database offered only as a service, with no
	// edition anyone can run.
	DeploymentHosted Deployment = 4
)

Deployment kinds.

A database can offer more than one. CockroachDB is a server anyone can run and a service, so it is DeploymentServer|DeploymentHosted.

type Error 

type Error string

Error is an error. 

const (
	// ErrInvalidDatabaseScheme is the invalid database scheme error.
	ErrInvalidDatabaseScheme Error = "invalid database scheme"
	// ErrUnknownDatabaseScheme is the unknown database type error.
	ErrUnknownDatabaseScheme Error = "unknown database scheme"
	// ErrUnknownFileHeader is the unknown file header error.
	ErrUnknownFileHeader Error = "unknown file header"
	// ErrUnknownFileExtension is the unknown file extension error.
	ErrUnknownFileExtension Error = "unknown file extension"
	// ErrInvalidTransportProtocol is the invalid transport protocol error.
	ErrInvalidTransportProtocol Error = "invalid transport protocol"
	// ErrRelativePathNotSupported is the relative paths not supported error.
	ErrRelativePathNotSupported Error = "relative path not supported"
	// ErrMissingHost is the missing host error.
	ErrMissingHost Error = "missing host"
	// ErrMissingPath is the missing path error.
	ErrMissingPath Error = "missing path"
	// ErrMissingUser is the missing user error.
	ErrMissingUser Error = "missing user"
	// ErrMissingDriver is the missing ODBC driver error.
	ErrMissingDriver Error = "missing driver"
	// ErrInvalidQuery is the invalid query error.
	ErrInvalidQuery Error = "invalid query"
)

Error values.

func (Error) Error 

func (err Error) Error() string

Error satisfies the error interface.

type Scheme 

type Scheme struct {
	// Name is the name of the scheme. [Parse] sets it as the SchemeName of the
	// returned URL, and as its Driver when the generator names no driver.
	//
	// Note: a 2 letter alias is registered automatically, taken from the
	// first 2 characters of the Name. This does not happen when one of the
	// Aliases is already 2 characters.
	Name string
	// Generator is the func responsible for generating a DSN based on parsed
	// URL information. It returns the DSN, and the name to pass to sql.Open
	// when that is not the Name, as mysql for tidb or pgx for postgres.
	//
	// Note: this func must not modify the passed URL.
	Generator func(*URL) (string, string, error)
	// Transport are allowed protocol transport types for the scheme.
	Transport Transport
	// Opaque toggles Parse to not re-process URLs with an "opaque" component.
	Opaque bool
	// Aliases are any additional aliases for the scheme.
	Aliases []string
	// Defaults are query options that [Parse] adds to the URL before it runs
	// the Generator, when the URL does not name the key or gives it an empty
	// value. A value the URL gives always wins, so the caller can change any of
	// them. They are options that the driver needs to behave as the xo
	// projects expect, such as parseTime for mysql (D65).
	Defaults map[string]string
	// Dialect is the Name of the scheme that is canonical for the database
	// product, which is this scheme's own Name when it is the canonical one.
	//
	// A product reached by more than one Go driver has a scheme per driver.
	// They share a Dialect: pgx, pq and postgres are all PostgreSQL, as
	// moderncsqlite and sqlite3 are both SQLite3. A product that speaks the
	// wire protocol of another has a Dialect of its own, because its catalog
	// differs: tidb opens the mysql driver, and its Dialect is tidb.
	Dialect string
	// Desc is the database display name, as "Apache Hive".
	Desc string
	// Home is the home page of the database provider. It can be blank.
	Home string
	// DriverURL is the home page of the Go database driver.
	DriverURL string
	// GoPackage is the import path of the Go database driver, including the
	// major version when the module carries one.
	//
	// This is the import path and not the module path. The two differ: for
	// pgx the module is github.com/jackc/pgx/v5 and the import path that
	// registers the driver is github.com/jackc/pgx/v5/stdlib.
	GoPackage string
	// RequiresCGO reports whether the Go database driver needs cgo.
	RequiresCGO bool
	// Deployment is the deployment kinds the database offers.
	Deployment Deployment
}

Scheme wraps information used for registering a database URL scheme for use with Parse/Open.

func BaseSchemes 

func BaseSchemes() []Scheme

BaseSchemes returns the supported base schemes.

func Unregister 

func Unregister(name string) *Scheme

Unregister unregisters a scheme and all associated aliases, returning the removed Scheme.

type Transport added in v0.3.0 

type Transport uint

Transport is the allowed transport protocol types in a database URL scheme. 

const (
	TransportNone Transport = 0
	TransportTCP  Transport = 1
	TransportUDP  Transport = 2
	TransportUnix Transport = 4
	TransportAny  Transport = 8
)

Transport types.

type URL 

type URL struct {
	// URL is the base [net/url.URL].
	url.URL

	// OriginalScheme is the original parsed scheme (ie, "sq", "mysql+unix", "sap", etc).
	OriginalScheme string
	// Transport is the specified transport protocol (ie, "tcp", "udp",
	// "unix", ...), if provided.
	Transport string
	// SchemeName is the [Scheme.Name] of the parsed scheme, with no alias, as
	// "tidb" for ti:// and tidb://.
	SchemeName string
	// Driver is the name to pass to [sql.Open], which the Go driver
	// registered. It is always set, and it is the SchemeName unless the
	// scheme opens a driver of another name: tidb opens mysql, postgres and
	// cockroachdb open pgx, pq opens postgres, and influxql opens influxdb.
	Driver string
	// Dialect is the [Scheme.Dialect] of the parsed scheme: the Name of the
	// scheme that is canonical for the database product.
	//
	// Use it, and not Driver, to learn which product a URL connects to.
	// Driver names the Go driver, so postgres:// and pgx:// both open pgx,
	// and pq:// opens postgres. All three have the Dialect postgres.
	Dialect string
	// DSN is the built connection "data source name" that can be used in a
	// call to [sql.Open].
	DSN string
	// contains filtered or unexported fields
}

URL wraps the standard net/url.URL type, adding the OriginalScheme, Transport, SchemeName, Driver, Dialect and DSN strings.

func FromMap added in v0.23.0 

func FromMap(components map[string]any) (*URL, error)

FromMap creates a URL using the mapped components.

Recognized components are: 

protocol, proto, scheme
transport
username, user
password, pass
hostname, host
port
path, file, opaque
database, dbname, db
instance
parameters, params, options, opts, query, q

See BuildURL for more information.

func Parse 

func Parse(urlstr string) (*URL, error)

Parse parses a URL string, similar to the standard net/url.Parse.

Handles parsing the OriginalScheme, Transport, SchemeName, Driver, Dialect and DSN fields.

Note: an opaque URL is written "scheme:" and not "scheme://". When the database scheme does not support an opaque component, Parse rebuilds the URL as "scheme://<opaque>" and parses it again.

func (*URL) Normalize 

func (u *URL) Normalize(sep, empty string, cut int) string

Normalize returns the driver, host, port, database, and user name of a URL, joined with sep, populating blank fields with empty. When cut is more than 0, it drops the empty fields at the end, and keeps the last field that is not empty and at least cut fields. It drops a field only when empty is the empty string.

func (*URL) Short 

func (u *URL) Short() string

Short provides a short description of the user, host, and database.

func (*URL) String 

func (u *URL) String() string

String satisfies the fmt.Stringer interface.

Source Files

View all Source files

Directories

Path Synopsis
_example/example.go
 _example/example.go
Package passfile provides a mechanism for reading database credentials from passfiles.
 Package passfile provides a mechanism for reading database credentials from passfiles.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.