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, creates writer/reader pools, applies each role's pool settings, registers DB stats metrics, and closes those pools on lifecycle stop.
Pool creation follows the database/sql.Open contract: it may not establish a network connection immediately. Use github.com/alexfalkowski/go-service/v2/database/sql/driver.DBs.Ping, github.com/alexfalkowski/go-service/v2/database/sql/driver.DBs.PingWriter, github.com/alexfalkowski/go-service/v2/database/sql/driver.DBs.PingReader, or a health checker when startup/readiness must verify database reachability.
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
- func (d *DBs) DriverName() string
- func (d *DBs) Ping() error
- func (d *DBs) PingReader() error
- func (d *DBs) PingWriter() error
- func (d *DBs) Reader() (*sql.DB, error)
- func (d *DBs) Readers() []*sql.DB
- func (d *DBs) Writer() (*sql.DB, error)
- func (d *DBs) Writers() []*sql.DB
- 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 writer or reader 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 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
type DBs struct {
// contains filtered or unexported fields
}
DBs contains writer and reader SQL connection pools.
Reader returns a random reader pool when readers are configured and falls back to a random writer pool otherwise. Writer returns a random writer pool.
func Connect ¶ added in v2.327.0
Connect opens writer/reader 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"), opens writer and reader pools, registers OpenTelemetry DB stats metrics for each pool when metrics are enabled, and then applies each role's pool settings.
Like database/sql.Open, this creates pool handles but does not ping the database or verify network reachability. Call DBs.Ping, DBs.PingWriter, DBs.PingReader, or a health checker when startup/readiness must prove connectivity.
Preconditions:
- cfg must be non-nil and already treated as enabled/validated by the caller.
Failure behavior:
- returns errors encountered while resolving DSNs or creating pool handles,
- returns ErrEmptyDSN when any configured DSN source resolves to empty bytes, and
- returns ErrNoDSNs when neither writer nor reader DSNs are configured.
The returned DBs owns repository lifecycle cleanup such as DB stats metric unregistration.
func ConnectWritersReaders ¶ added in v2.609.0
ConnectWritersReaders opens writer/reader github.com/alexfalkowski/go-service/v2/database/sql connection pools for a previously registered driver name.
It is a low-level helper for callers that already have resolved literal DSNs. It creates pool handles with database/sql.Open and does not ping the databases.
func Open ¶
func Open(lc di.Lifecycle, name string, fs *os.FS, cfg *config.Config, opts ...telemetry.Option) (*DBs, error)
Open opens writer/reader 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.
func (*DBs) Destroy ¶ added in v2.448.0
Destroy unregisters repository-owned DB stats metrics and closes all database pools.
func (*DBs) DriverName ¶ added in v2.609.0
DriverName returns the registered database/sql driver name.
func (*DBs) PingReader ¶ added in v2.609.0
PingReader pings all reader pools.
func (*DBs) PingWriter ¶ added in v2.609.0
PingWriter pings all writer pools.
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