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

dburl

package module
v0.34.0 Latest Latest
Warning

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

 Go to latest Published: Sep 27, 2026 License: MIT Imports: 15 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" or driver name (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. The scheme is usually also the driver name that dburl returns. A row marked ‡ uses the driver of another row, and pq returns postgres, which is the name that github.com/lib/pq registers:

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/ClickHouse/clickhouse-go/v2
CSVQ csvq cs, csv, tsv, json github.com/mithrandie/csvq-driver §
Alibaba MaxCompute maxcompute mc github.com/aliyun/aliyun-odps-go-sdk/sqldriver
Alibaba Tablestore ots ot, tablestore github.com/aliyun/aliyun-tablestore-go-sql-driver
Amazon Redshift redshift rs github.com/jackc/pgx/v5/stdlib ‡
Apache Avatica avatica av, phoenix github.com/apache/calcite-avatica-go/v5
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
AWS Athena awsathena s3, aws, athena github.com/uber/athenadriver/go
Azure CosmosDB cosmos cm, gocosmos github.com/btnguyen2k/gocosmos
Cassandra cql ca, scy, scylla, datastax, cassandra github.com/xo/cql
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
Cznic QL ql cznic, cznicql modernc.org/ql §
Databend databend dd, bend github.com/datafuselabs/databend-go
Databricks databricks br, brick, bricks, databrick github.com/databricks/databricks-sql-go
DynamoDb godynamo dy, dyn, dynamo, dynamodb github.com/btnguyen2k/godynamo
Exasol exasol ex, exa github.com/exasol/exasol-driver-go
Firebird firebirdsql fb, firebird github.com/nakagami/firebirdsql
FlightSQL flightsql fl, flight github.com/apache/arrow-go/v18/arrow/flight/flightsql/driver
GO DRiver for ORacle godror gr github.com/godror/godror †
Google BigQuery bigquery bq gorm.io/driver/bigquery/driver
Google Spanner spanner sp github.com/googleapis/go-sql-spanner
ModernC SQLite3 moderncsqlite mq, modernsqlite modernc.org/sqlite §
Netezza nzgo nz, netezza github.com/IBM/nzgo/v12
ODBC odbc od github.com/alexbrainman/odbc †
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/prestodb/presto-go-client/v2
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/snowflakedb/gosnowflake/v2
SurrealDB surrealdb sr, sur, surreal github.com/xo/dbimp/surrealdb
TiDB tidb ti github.com/go-sql-driver/mysql ‡
Trino trino tr, trs, trinos github.com/trinodb/trino-go-client/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, yds, ydbs github.com/ydb-platform/ydb-go-sdk/v3

† Requires CGO
‡ Uses the driver of another row, as a wire compatible database does
§ 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)
	}
	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, cockroachdb and redshift, which all speak PostgreSQL.

func FileTypes added in v0.18.0 

func FileTypes() []string

FileTypes returns the registered file types.

func GenCassandra 

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

GenCassandra generates a cql DSN from the passed URL.

Targets xo/cql, which reads a cql:// URL with net/url. The scheme is always cql, whichever alias was parsed, so the driver never repeats the alias list. 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.

func GenClickhouse 

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

GenClickhouse generates a clickhouse DSN from the passed URL.

func GenCosmos added in v0.2.0 

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

GenCosmos generates a cosmos DSN from the passed URL.

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, so the scheme is always couchbase, whichever alias was parsed. The user information and the query pass through, as they were written, and the driver refuses an unknown or repeated key. The path passes through too, and the driver refuses one other than "/".

The default port follows the tls key, as the port of the query service does: 8093, or 18093 when tls reads as true. The key is read with strconv.ParseBool, as the driver reads it, so the two agree on every value.

func GenDatabend added in v0.12.5 

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

GenDatabend generates a databend DSN from the passed URL.

func GenDatabricks added in v0.19.0 

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

GenDatabricks generates a databricks DSN from the passed URL.

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 dynamo DSN from the passed URL.

func GenExasol added in v0.8.5 

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

GenExasol generates a exasol DSN from the passed URL.

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 GenGodror added in v0.9.0 

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

GenGodror generates a godror DSN from the passed URL.

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 GenMaxCompute added in v0.31.0 

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

GenMaxCompute generates a maxcompute DSN from the passed URL.

Targets aliyun/aliyun-odps-go-sdk/sqldriver, which takes an http or https URL as the endpoint and reads the project from the project query option. The endpoint is https unless the scheme carries +http.

func GenMysql added in v0.9.0 

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

GenMysql generates a mysql DSN from the passed URL.

func GenOdbc added in v0.9.0 

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

GenOdbc generates a odbc DSN from the passed URL.

func GenOpaque 

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

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

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 and nzgo use 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 GenPostgres 

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

GenPostgres generates a postgres DSN from the passed URL.

Targets lib/pq and IBM/nzgo/v12, which both read the keyword/value form. A value holding a space, a quote or a backslash is quoted, as both parsers require.

See GenPgx, which postgres uses instead.

func GenPresto 

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

GenPresto generates a presto DSN from the passed URL.

Targets prestodb/presto-go-client/v2, which accepts only the presto and trino schemes, and reads the catalog and the schema from the path.

The driver sends any query option it does not recognize to the server as a session property. The catalog and the schema cannot go there.

The driver selects TLS from the ssl_ca, ssl_cert, ssl_key and ssl_skip_verify options, and not from the scheme, so presto has no "s" suffixed alias. Setting any of those options also moves the default port to 8443.

See GenTrino, which Trino uses instead. The two drivers want different DSNs.

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 GenSnowflake 

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

GenSnowflake generates a snowflake DSN from the passed URL.

func GenSpanner added in v0.2.0 

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

GenSpanner generates a spanner DSN from the passed URL.

func GenSqlserver added in v0.9.0 

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

GenSqlserver generates a sqlserver DSN from the passed URL.

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, so the scheme is always surrealdb, whichever alias was parsed. The path names the namespace and the database, as /namespace/database, and passes through with its escaping, so a name that holds a slash stays %2F. The user information and the query pass through as they were written, and the driver refuses an unknown or repeated key.

The default port is 8000, with TLS or without, as the driver serves both on the same port.

func GenTableStore added in v0.11.0 

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

GenTableStore generates a tablestore DSN from the passed URL.

func GenTrino added in v0.27.0 

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

GenTrino generates a trino DSN from the passed URL.

Targets trinodb/trino-go-client, which takes an http or https URL and reads the catalog and schema from the query.

See GenPresto. Trino and Presto share a wire protocol, but their drivers disagree about the scheme and about where the catalog and schema belong.

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.

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 SchemeDriverAndAliases 

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

SchemeDriverAndAliases returns the registered driver and aliases for a database scheme.

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"
	// 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 {
	// Driver is the name of the SQL driver. [Parse] sets it as the Scheme on
	// the returned URL, and the standard sql.Open calls expect it.
	//
	// Note: a 2 letter alias is registered automatically, taken from the
	// first 2 characters of the Driver. This does not happen when one of the
	// Aliases is already 2 characters.
	Driver string
	// Generator is the func responsible for generating a DSN based on parsed
	// URL information.
	//
	// 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
	// Override is the Go SQL driver to use instead of Driver.
	//
	// Used for "wire compatible" driver schemes, and for a scheme whose
	// driver registered a name another scheme holds: pq returns postgres,
	// which lib/pq registers, because the postgres scheme returns pgx.
	Override string
	// Dialect is the Driver of the scheme that is canonical for the database
	// product, which is this scheme's own Driver when it is the canonical
	// one.
	//
	// A product reached by more than one Go driver has a scheme per driver,
	// because each Driver is a name a caller passes to sql.Open. They share a
	// Dialect: pgx and postgres are both PostgreSQL, as moderncsqlite and
	// sqlite3 are both SQLite3.
	//
	// A scheme with an Override takes the Dialect of the scheme it overrides.
	// For a wire compatible scheme, that is the product it speaks to.
	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.
	//
	// Blank for a wire compatible scheme, which reaches its driver through
	// Override. A scheme whose Override names a driver that no scheme opens
	// sets it, as pq does for lib/pq.
	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.
	//
	// Blank for a wire compatible scheme, and set by a scheme whose Override
	// names a driver that no scheme opens, as for DriverURL.
	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
	// Driver is the non-aliased SQL driver name to use in a call to
	// [sql.Open].
	Driver string
	// GoDriver is the Go SQL driver name to use when opening a connection to
	// the database. Used by Microsoft SQL Server's azuresql:// URLs, as the
	// wire-compatible alias style uses a different syntax style.
	GoDriver string
	// UnaliasedDriver is the unaliased driver name.
	UnaliasedDriver string
	// Dialect is the [Scheme.Dialect] of the parsed scheme: the Driver 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 return pgx
	// as their Driver, and pq:// returns 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 OriginalScheme, Transport, Driver, Unaliased, 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 OriginalScheme, Transport, Driver, Unaliased, 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.

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.