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 ErrNoDSNs = errors.New("driver: no database DSNs configured")
ErrNoDSNs is returned when SQL configuration enables a driver without any master or slave DSNs.
Functions ¶
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, 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 type is the upstream master/slave pool collection used internally by the SQL driver layer. Higher-level repository code can usually treat it interchangeably with `database/sql.DBs`, which aliases the same upstream type.
func Open ¶
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.
The returned type is the same upstream master/slave pool collection returned by Connect.
func Register ¶
Register registers a `database/sql` driver under name and wraps it with OpenTelemetry instrumentation.
This function registers the wrapped 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.
- 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.
Source Files