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 when tracing or metrics are enabled, and
- providing an Open constructor that creates writer/reader 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. Enabled PostgreSQL configuration must provide at least one non-empty writer or replica DSN. PostgreSQL DSN options, including TLS and sslmode settings, are supplied in the configured DSN and passed through to pgx without repository-level rewriting or security policy enforcement.
Writer/reader pools ¶
Open resolves writer and replica DSNs from configuration (DSNs are expressed as go-service "source strings"), connects using the shared writer/reader pool abstraction used by the repository, applies pool settings (max lifetime/open/idle), and registers OpenTelemetry DB stats metrics when metrics are enabled.
The package returns github.com/alexfalkowski/go-service/v2/database/sql/driver.DBs, which 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 when tracing or metrics are enabled) and provides a constructor that opens writer/reader 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 writer/reader 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 writer and replica DSNs (expressed as go-service "source strings"),
- require at least one non-empty writer or replica DSN,
- connect using the previously registered driver name "pg",
- register OpenTelemetry DB stats metrics when metrics are enabled, and
- apply connection pool limits/lifetime.
The returned type 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 writer/reader 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 when tracing or metrics are enabled. 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. PostgreSQL connection options, including TLS and sslmode settings, belong in the configured DSNs and are passed through to pgx unchanged.
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