Documentation
¶
Overview ¶
Package sql provides SQL database wiring and helpers for go-service.
This package is the entrypoint for wiring SQL database support into go.uber.org/fx/go.uber.org/dig. It composes driver-specific modules (for example PostgreSQL via github.com/alexfalkowski/go-service/v2/database/sql/pg) and exposes a small, consistent configuration shape for services (Config).
Configuration and enablement ¶
SQL configuration is optional. By convention across go-service config types, a nil *Config is treated as "disabled". Driver-specific configs typically follow the same convention, and constructors that depend on config often return (nil, nil) when disabled.
Writer/reader pool wrapper ¶
This package also exposes the shared writer/reader pool abstraction used by repository code:
- DBs, the go-service writer/reader pool collection type, and
- ConnectWritersReaders, the go-service helper for opening those pools.
Callers choose the pool role explicitly with [DBs.Reader] or [DBs.Writer] and then use standard-library database/sql methods on the returned pool.
This keeps internal code on a go-service import path while go-service-owned cleanup remains attached to [DBs.Destroy].
Writer/reader pools and telemetry ¶
Driver integrations typically open writer/reader connection pools, configure pool limits/lifetimes, wrap drivers with OpenTelemetry instrumentation when tracing or metrics are enabled, and register database/sql stats metrics when metrics are enabled.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Module = di.Module( pg.Module, )
Module wires SQL database support into go.uber.org/fx/go.uber.org/dig.
This module is the aggregate SQL bundle used by higher-level application bundles such as github.com/alexfalkowski/go-service/v2/module.Server and github.com/alexfalkowski/go-service/v2/module.Client. It keeps SQL support opt-in via a single DI option while delegating backend-specific behavior to subpackages.
At present it includes only PostgreSQL support via github.com/alexfalkowski/go-service/v2/database/sql/pg.Module, but the module shape is intentionally extensible for additional SQL drivers in the future.
Driver-specific constructors read DSNs/pool settings from config, open writer/reader pools, install OpenTelemetry driver instrumentation when tracing or metrics are enabled, register DB stats metrics when metrics are enabled, and attach lifecycle hooks that close pools on shutdown.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// PG configures PostgreSQL support (writer/reader DSNs and shared pool settings).
//
// PostgreSQL is the only SQL backend wired by this repository today.
PG *pg.Config `yaml:"pg,omitempty" json:"pg,omitempty" toml:"pg,omitempty"`
}
Config is the root SQL database configuration for a go-service based service.
It composes driver-specific configuration for SQL backends wired by this repository. Today the built-in backend is PostgreSQL via the Config.PG field, but the root shape leaves room for additional SQL backends without changing the surrounding service config layout.
Optional pointers and "enabled" semantics ¶
This config is intentionally optional. By convention across go-service configuration types, a nil *Config is treated as "SQL disabled". Driver-specific sub-configs are also pointers and are treated as optional; downstream constructors typically return (nil, nil) when a required sub-config is nil.
type DB ¶ added in v2.374.0
DB aliases database/sql.DB.
It is exposed so go-service SQL packages can use the local package namespace while preserving standard-library behavior.
func Open ¶ added in v2.374.0
Open aliases database/sql.Open.
The driver name must already be registered with the standard library database/sql driver registry. The returned DB uses standard-library database/sql behavior.
type DBs ¶ added in v2.339.0
DBs is an alias of driver.DBs.
It represents the writer/reader SQL pool collection used by go-service SQL integrations. Callers choose a pool with [DBs.Reader] or [DBs.Writer] and use standard-library database/sql methods on the returned pool.
func ConnectWritersReaders ¶ added in v2.609.0
ConnectWritersReaders is a thin wrapper around driver.ConnectWritersReaders.
It opens a writer/reader SQL pool collection for a registered standard library database/sql driver name and returns any per-DSN open errors.
The driver name must already be registered with the standard library database/sql driver registry. At least one writer or reader DSN must be configured.
type Rows ¶ added in v2.374.0
Rows aliases database/sql.Rows.
It is exposed so go-service SQL packages can use the local package namespace while preserving standard-library behavior.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package config provides shared SQL (github.com/alexfalkowski/go-service/v2/database/sql) configuration types for go-service.
|
Package config provides shared SQL (github.com/alexfalkowski/go-service/v2/database/sql) configuration types for go-service. |
|
Package driver provides low-level SQL driver registration and connection helpers for go-service.
|
Package driver provides low-level SQL driver registration and connection helpers for go-service. |
|
Package pg provides PostgreSQL (github.com/alexfalkowski/go-service/v2/database/sql) wiring and helpers for go-service.
|
Package pg provides PostgreSQL (github.com/alexfalkowski/go-service/v2/database/sql) wiring and helpers for go-service. |
|
Package telemetry exposes selected github.com/XSAM/otelsql helpers through the go-service SQL import tree.
|
Package telemetry exposes selected github.com/XSAM/otelsql helpers through the go-service SQL import tree. |