Documentation
¶
Overview ¶
Package pg provides PostgreSQL (github.com/alexfalkowski/go-service/v2/database/sql) wiring and helpers for go-service.
This package integrates the github.com/jackc/pgx/v5/stdlib PostgreSQL driver with go-service SQL wiring by:
- registering the pgx stdlib database/sql driver under the name "pg" with OpenTelemetry instrumentation, and
- providing an Open constructor that creates master/slave connection pools using the shared SQL driver helpers.
Configuration and enablement ¶
PostgreSQL configuration is optional. By convention, a nil *Config (or nil embedded config) is treated as "disabled", and constructors such as Open return (nil, nil) when disabled.
Master/slave pools ¶
Open resolves master and replica DSNs from configuration (DSNs are expressed as go-service "source strings"), connects using the shared master/slave pool abstraction used by the repository, applies pool settings (max lifetime/open/idle), and registers OpenTelemetry DB stats metrics.
The package returns github.com/alexfalkowski/go-service/v2/database/sql/driver.DBs, which embeds the upstream pool collection and is aliased by the root github.com/alexfalkowski/go-service/v2/database/sql package as github.com/alexfalkowski/go-service/v2/database/sql.DBs.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Module = di.Module( di.Register(Register), di.Constructor(Open), )
Module wires PostgreSQL (github.com/alexfalkowski/go-service/v2/database/sql) support into go.uber.org/fx/go.uber.org/dig.
It registers the github.com/jackc/pgx/v5/stdlib driver under the name "pg" (with OpenTelemetry instrumentation) and provides a constructor that opens master/slave connection pools.
Provided components:
Disabled behavior: Open returns (nil, nil) when PostgreSQL configuration is disabled.
Functions ¶
func Connect ¶ added in v2.327.0
Connect opens PostgreSQL master/slave connection pools.
Disabled behavior: if cfg is nil/disabled, Connect returns (nil, nil).
Enabled behavior: Connect delegates to the shared SQL driver helper to:
- resolve master and replica DSNs (expressed as go-service "source strings"),
- connect using the previously registered driver name "pg",
- register OpenTelemetry DB stats metrics, and
- apply connection pool limits/lifetime.
The returned type wraps the upstream master/slave pool collection and is aliased by the root github.com/alexfalkowski/go-service/v2/database/sql package as github.com/alexfalkowski/go-service/v2/database/sql.DBs for higher-level callers.
func Open ¶
Open opens PostgreSQL master/slave connection pools.
Open preserves PostgreSQL's nil/disabled config semantics and then delegates connection lifecycle ownership to the shared SQL driver helper.
The returned type is the same go-service driver.DBs wrapper returned by Connect.
func Register ¶
func Register()
Register registers the pgx stdlib database/sql driver under the name "pg".
The registration is performed via github.com/alexfalkowski/go-service/v2/database/sql/driver.Register, which wraps the underlying driver with OpenTelemetry instrumentation via github.com/alexfalkowski/go-service/v2/database/sql/telemetry. The returned error from registration is intentionally ignored.
Register is typically called during process initialization via DI wiring (see Module).
Types ¶
type Config ¶
Config contains PostgreSQL SQL database configuration.
It embeds github.com/alexfalkowski/go-service/v2/database/sql/config.Config to reuse common github.com/alexfalkowski/go-service/v2/database/sql pool settings and DSN configuration.
Optional pointers and "enabled" semantics ¶
This type is intentionally optional. By convention across go-service configuration types, a nil *Config is treated as "PostgreSQL disabled". The embedded *config.Config is also optional; Config.IsEnabled returns true only when both the outer *Config and the embedded *config.Config are non-nil.
This allows services to omit either `pg:` or the embedded fields entirely to disable PostgreSQL wiring.
Source Files