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 writer/reader 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
- 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) SetConnMaxLifetime(v time.Duration)
- func (d *DBs) SetMaxIdleConns(v int)
- func (d *DBs) SetMaxOpenConns(v int)
- 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 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 writers nor readers 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.
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.
func (*DBs) SetConnMaxLifetime ¶ added in v2.609.0
SetConnMaxLifetime sets the maximum amount of time a connection may be reused across all pools.
func (*DBs) SetMaxIdleConns ¶ added in v2.609.0
SetMaxIdleConns sets the maximum number of idle connections across all pools.
func (*DBs) SetMaxOpenConns ¶ added in v2.609.0
SetMaxOpenConns sets the maximum number of open connections across all 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