Documentation
¶
Overview ¶
Package sql provides SQL database wiring and helpers for go-service.
This package is the entrypoint for wiring SQL database support into Fx/Dig. It composes driver-specific modules (for example PostgreSQL via `database/sql/pg`) and exposes a small, consistent configuration shape for services (`sql.Config`).
Configuration and enablement ¶
SQL configuration is optional. By convention across go-service config types, a nil `*sql.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.
Master/slave pool wrapper ¶
This package also exposes the shared master/slave pool abstraction used by repository code:
- `DBs`, the go-service alias for the upstream pool collection type, and
- `ConnectMasterSlaves`, the go-service wrapper for opening those pools.
This keeps internal code on a go-service import path instead of importing the upstream helper package directly where the package graph allows it.
Driver-oriented subpackages such as `database/sql/driver` and `database/sql/pg` still use the upstream pool package internally because the root `database/sql` package already depends on those subpackages for config and module composition. Re-importing the root package from those subpackages would create an import cycle.
Master/slave pools and telemetry ¶
Driver integrations typically open master/slave connection pools, configure pool limits/lifetimes, and register OpenTelemetry instrumentation/metrics for `database/sql` connections.
Start with `Module` and `Config`.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Module = di.Module( pg.Module, )
Module wires SQL database support into Fx/Dig.
This module is the aggregate SQL bundle used by higher-level application bundles such as `module.Server` and `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 `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 master/slave pools, register OpenTelemetry instrumentation/metrics, and attach lifecycle hooks that close pools on shutdown.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// PG configures PostgreSQL support (master/slave 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 `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 DBs ¶ added in v2.339.0
DBs is an alias of mssqlx.DBs.
It represents the master/slave SQL pool collection used by go-service SQL integrations and preserves the upstream behavior exactly.
The value groups master and replica `sqlx.DB` pools behind a single type with helper methods for querying masters, slaves, and running operations against the configured pools.
func ConnectMasterSlaves ¶ added in v2.339.0
ConnectMasterSlaves is a thin wrapper around mssqlx.ConnectMasterSlaves.
It opens a master/slave SQL pool collection for a registered `database/sql` driver name and returns any per-DSN connection errors produced by the upstream helper.
The driver name must already be registered with the global `database/sql` registry. The returned `DBs` value may contain zero or more master and slave pools depending on the provided DSN lists.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package config provides shared SQL (`database/sql`) configuration types for go-service.
|
Package config provides shared SQL (`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 (`database/sql`) wiring and helpers for go-service.
|
Package pg provides PostgreSQL (`database/sql`) wiring and helpers for go-service. |
|
Package telemetry exposes selected otelsql helpers through the go-service SQL import tree.
|
Package telemetry exposes selected otelsql helpers through the go-service SQL import tree. |