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 ¶
- Variables
- func Connect(name string, fs *os.FS, cfg *config.Config) (*mssqlx.DBs, error)
- func Open(lc di.Lifecycle, name string, fs *os.FS, cfg *config.Config) (*mssqlx.DBs, error)
- func Register(name string, driver Driver) (err error)
- type Conn
- type Driver
- type NamedValue
- type Rows
- type Stmt
- type Tx
- type Value
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 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 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.
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.
- 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 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