Documentation
¶
Overview ¶
Package pg provides PostgreSQL (`database/sql`) wiring and helpers for go-service.
This package integrates the pgx 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 `*pg.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.
Although the package-level SQL wrapper aliases this pool type as `database/sql.DBs`, this package returns the underlying upstream type directly to avoid an import cycle with the root `database/sql` package.
Start with `Config`, `Register`, and `Open`.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Module = di.Module( di.Register(Register), di.Constructor(Open), )
Module wires PostgreSQL (`database/sql`) support into Fx/Dig.
It registers the pgx stdlib driver under the name "pg" (with OpenTelemetry instrumentation) and provides a constructor that opens master/slave connection pools.
Provided components:
- Registration: `Register`
- Constructor: `Open`
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 is the upstream master/slave pool collection used throughout the SQL layer. The root `database/sql` package aliases the same type as `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 upstream master/slave pool collection returned by Connect.
func Register ¶
func Register()
Register registers the pgx stdlib `database/sql` driver under the name "pg".
The registration is performed via `database/sql/driver.Register`, which wraps the underlying driver with OpenTelemetry instrumentation via `database/sql/telemetry`. The returned error from registration is intentionally ignored.
Register is typically called during process initialization via DI wiring (see `pg.Module`).
Types ¶
type Config ¶
Config contains PostgreSQL SQL database configuration.
It embeds `database/sql/config`.Config to reuse common `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; 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