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 `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 `database/sql/pg` rather than calling it directly.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrEmptyDSN = errors.New("driver: empty database DSN")
ErrEmptyDSN is returned when a configured DSN source resolves to an empty string.
var ErrNoDSNs = errors.New("driver: no database DSNs configured")
ErrNoDSNs is returned when SQL configuration enables a driver without any master or slave DSNs.
var ErrSkip = driver.ErrSkip
ErrSkip aliases `database/sql/driver`.ErrSkip.
Functions ¶
func Register ¶
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 database/sql/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 DBs ¶ added in v2.448.0
DBs wraps the upstream master/slave SQL pool collection.
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
Connect opens master/slave `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, 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
ConnectMasterSlaves opens master/slave `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 `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 Destroy.
Preconditions:
- cfg must be non-nil and already treated as enabled/validated by the caller.
- driver-specific wrappers, such as 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.
type Driver ¶
Driver aliases `database/sql/driver`.Driver.
It is the concrete driver type expected by Register.
type NamedValue ¶ added in v2.374.0
type NamedValue = driver.NamedValue
NamedValue aliases `database/sql/driver`.NamedValue.
Source Files