Documentation
¶
Overview ¶
Package postgres provides shared PostgreSQL connection helpers.
It focuses on predictable connection lifecycle and configuration defaults that are safe for service startup and shutdown flows.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNilClient is returned when a postgres client receiver is nil. ErrNilClient = errors.New("postgres client is nil") // ErrNilContext is returned when a required context is nil. ErrNilContext = errors.New("context is nil") // ErrInvalidConfig indicates invalid postgres or migration configuration. ErrInvalidConfig = errors.New("invalid postgres config") // ErrNotConnected indicates operations requiring an active connection were called before connect. ErrNotConnected = errors.New("postgres client is not connected") // ErrInvalidDatabaseName indicates an invalid database identifier. ErrInvalidDatabaseName = errors.New("invalid database name") // ErrMigrationDirty indicates migrations stopped at a dirty version. ErrMigrationDirty = errors.New("postgres migration dirty") // ErrNilMigrator is returned when a migrator receiver is nil. ErrNilMigrator = errors.New("postgres migrator is nil") )
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the v2 postgres connection manager.
func (*Client) Close ¶
Close releases database resources. All three handles (resolver, primary, replica) are always explicitly closed to prevent leaks -- the resolver may not own the underlying sql.DB connections.
func (*Client) Connect ¶
Connect establishes a new primary/replica resolver and swaps it atomically.
func (*Client) IsConnected ¶
IsConnected reports whether the resolver is currently initialized.
type Config ¶
type Config struct {
PrimaryDSN string
ReplicaDSN string
Logger log.Logger
MetricsFactory *metrics.MetricsFactory
MaxOpenConnections int
MaxIdleConnections int
ConnMaxLifetime time.Duration
ConnMaxIdleTime time.Duration
}
Config stores immutable connection options for a postgres client.
type MigrationConfig ¶
type MigrationConfig struct {
PrimaryDSN string
DatabaseName string
MigrationsPath string
Component string
// AllowMultiStatements enables multi-statement execution in migrations.
// SECURITY: Only enable when migration files are from trusted, version-controlled sources.
// Multi-statement mode increases the blast radius of compromised migration files.
AllowMultiStatements bool
Logger log.Logger
}
MigrationConfig stores migration-only settings.
type Migrator ¶
type Migrator struct {
// contains filtered or unexported fields
}
Migrator runs schema migrations explicitly.
func NewMigrator ¶
func NewMigrator(cfg MigrationConfig) (*Migrator, error)
NewMigrator creates a migrator with explicit migration config.
type SanitizedError ¶ added in v2.3.0
type SanitizedError struct {
// Message is the credential-free error description.
Message string
}
SanitizedError wraps a database error with a credential-free message. Error() returns only the sanitized text.
Unwrap deliberately returns nil so the original error chain is never exposed, preventing database credentials from leaking through error inspection. Note: errors.Is will NOT match sentinels via chain traversal (since Unwrap returns nil). Match on the sanitized Message or use typed assertions instead.
func (*SanitizedError) Error ¶ added in v2.3.0
func (e *SanitizedError) Error() string
func (*SanitizedError) Unwrap ¶ added in v2.3.0
func (e *SanitizedError) Unwrap() error
Unwrap deliberately returns nil to prevent error chain traversal from leaking the original error which may contain database credentials. errors.Is will not traverse into the original cause.
Source Files