driver

package

v2.588.0 Latest Latest Go to latest Published: Jun 16, 2026 License: MIT Imports: 15 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/alexfalkowski/go-service

Links

Open Source Insights

Documentation ¶

Overview ¶

Package driver provides low-level SQL driver registration and connection helpers for go-service.

This package is the bridge between driver-specific packages (for example github.com/alexfalkowski/go-service/v2/database/sql/pg) and the shared SQL wiring used by the higher-level module graph.

Its main responsibilities are:

Register, which wraps a concrete database/sql/driver.Driver with OpenTelemetry instrumentation and installs it in the global database/sql driver registry.
Open, which resolves DSNs from go-service source strings, opens master/slave pools, applies pool settings, registers DB stats metrics, and closes those pools on lifecycle stop.

Most applications use this package indirectly through a driver package such as github.com/alexfalkowski/go-service/v2/database/sql/pg rather than calling it directly.

Index ¶

Variables
func Register(name string, driver Driver, opts ...telemetry.Option) (err error)
type Conn
type DBs
- func (d *DBs) Destroy() error
type Driver
type NamedValue
type Rows
type Stmt
type Tx
type Value

Constants ¶

This section is empty.

Variables ¶

View Source

var ErrEmptyDSN = errors.New("driver: empty database DSN")

ErrEmptyDSN is returned when a configured DSN source resolves to an empty string.

View Source

var ErrNoDSNs = errors.New("driver: no database DSNs configured")

ErrNoDSNs is returned when SQL configuration enables a driver without any master or slave DSNs.

View Source

var ErrSkip = driver.ErrSkip

ErrSkip aliases database/sql/driver.ErrSkip.

Functions ¶

func Register ¶

func Register(name string, driver Driver, opts ...telemetry.Option) (err error)

Register registers a database/sql driver under name.

This function registers the driver with the global database/sql driver registry. It is therefore intended to be called during process initialization (for example from an init hook or DI registration).

Telemetry:

The driver is wrapped using telemetry.WrapDriver when tracing or metrics are enabled.
If opts is empty, the DB system name attribute is set to the provided name (attributes.DBSystemNameKey).

Errors:

If the underlying sql.Register panics (for example, due to registering the same name more than once), Register converts that panic into an error and returns it.

Types ¶

type Conn ¶ added in v2.374.0

type Conn = driver.Conn

Conn aliases database/sql/driver.Conn.

type DBs ¶ added in v2.448.0

type DBs struct {
	*mssqlx.DBs
	// contains filtered or unexported fields
}

DBs wraps mssqlx.DBs.

It embeds the upstream type so callers keep the usual mssqlx query, exec, transaction, ping, and pool-configuration methods while go-service can attach repository-owned lifecycle cleanup such as OpenTelemetry metric registration cleanup.

func Connect ¶ added in v2.327.0

func Connect(name string, fs *os.FS, cfg *config.Config, opts ...telemetry.Option) (*DBs, error)

Connect opens master/slave github.com/alexfalkowski/go-service/v2/database/sql connection pools for a previously registered driver name.

It resolves DSNs from cfg using the provided filesystem (DSNs are configured as go-service "source strings"), connects using mssqlx.ConnectMasterSlaves, registers OpenTelemetry DB stats metrics for each pool when metrics are enabled, and then applies pool settings (connection lifetime, max idle, and max open connections).

Preconditions:

cfg must be non-nil and already treated as enabled/validated by the caller.

Failure behavior:

returns errors encountered while resolving DSNs or connecting,
returns ErrEmptyDSN when any configured DSN source resolves to empty bytes, and
returns ErrNoDSNs when neither masters nor slaves are configured.

The returned DBs embeds the upstream master/slave pool collection and owns repository lifecycle cleanup such as DB stats metric unregistration.

func ConnectMasterSlaves ¶ added in v2.448.0

func ConnectMasterSlaves(name string, masterDSNs, slaveDSNs []string) (*DBs, []error)

ConnectMasterSlaves opens master/slave github.com/alexfalkowski/go-service/v2/database/sql connection pools for a previously registered driver name.

It is a low-level wrapper around mssqlx.ConnectMasterSlaves for callers that already have resolved literal DSNs.

func Open ¶

func Open(lc di.Lifecycle, name string, fs *os.FS, cfg *config.Config, opts ...telemetry.Option) (*DBs, error)

Open opens master/slave github.com/alexfalkowski/go-service/v2/database/sql connection pools for a previously registered driver name.

Open delegates the connection work to Connect and then appends an OnStop hook to the provided lifecycle that closes all returned pools by calling DBs.Destroy.

Preconditions:

cfg must be non-nil and already treated as enabled/validated by the caller.
driver-specific wrappers, such as github.com/alexfalkowski/go-service/v2/database/sql/pg.Open, own nil/disabled config semantics before delegating here.

The returned type is the same go-service DBs wrapper returned by Connect.