database

package
v0.62.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 7, 2026 License: Apache-2.0 Imports: 43 Imported by: 4

Documentation

Overview

Copyright 2020 The Moov Authors Use of this source code is governed by an Apache License license that can be found in the LICENSE file.

Copyright 2020 The Moov Authors Use of this source code is governed by an Apache License license that can be found in the LICENSE file.

Copyright 2020 The Moov Authors Use of this source code is governed by an Apache License license that can be found in the LICENSE file.

Copyright 2020 The Moov Authors Use of this source code is governed by an Apache License license that can be found in the LICENSE file.

Copyright 2020 The Moov Authors Use of this source code is governed by an Apache License license that can be found in the LICENSE file.

Index

Constants

View Source 
const MIGRATIONS_DIR = "/migrations/"

Variables

View Source 
var (
	ErrMissingConfig = errors.New("database config not defined")
)

Functions

func ApplyConnectionsConfig added in v0.17.0 

func ApplyConnectionsConfig(db *sql.DB, connections *ConnectionsConfig, logger log.Logger) *sql.DB

func ApplyPostgresPoolConfig added in v0.62.0 

func ApplyPostgresPoolConfig(logger log.Logger, poolConfig *pgxpool.Config, connections ConnectionsConfig)

ApplyPostgresPoolConfig fills zero-valued fields in connections with DefaultPostgresConnectionsConfig, then maps them onto poolConfig.

Unlike database/sql (where MaxOpen=0 means unlimited), pgxpool always has a finite MaxConns. Leaving MaxOpen unset previously fell through to pgxpool's default of max(4, NumCPU()), which silently shrinks pools for services that never configured Connections. We instead apply explicit library defaults so behavior is predictable and logged.

MaxIdle has no pgxpool equivalent — pgxpool caps total connections via MaxConns rather than idle count. When set, MaxIdle is logged and ignored so operators aren't misled into thinking it took effect.

func DataTooLong added in v0.32.0 

func DataTooLong(err error) bool

func DeadlockFound added in v0.54.3 

func DeadlockFound(err error) bool

func GetDriver deprecated 

func GetDriver(logger log.Logger, config DatabaseConfig) (source.Driver, database.Driver, error)

Deprecated: Here to not break compatibility since it was once public.

func LoadTLSClientCertFromFile added in v0.35.0 

func LoadTLSClientCertFromFile(logger log.Logger, certFile, keyFile string) (tls.Certificate, error)

func LoadTLSClientCertsFromConfig added in v0.35.0 

func LoadTLSClientCertsFromConfig(logger log.Logger, config *MySQLConfig) ([]tls.Certificate, error)

func MySQLDataTooLong added in v0.32.0 

func MySQLDataTooLong(err error) bool

MySQLDataTooLong returns true when the provided error matches the MySQL code for data too long for column (when trying to insert a value that is greater than the defined max size of the column).

func MySQLDeadlockFound added in v0.43.0 

func MySQLDeadlockFound(err error) bool

MySQLDeadlockFound returns true when the provided error matches the MySQL code for deadlock found.

func MySQLDriver 

func MySQLDriver(db *sql.DB) (database.Driver, error)

func MySQLUniqueViolation 

func MySQLUniqueViolation(err error) bool

MySQLUniqueViolation returns true when the provided error matches the MySQL code for duplicate entries (violating a unique table constraint).

func New 

func New(ctx context.Context, logger log.Logger, config DatabaseConfig) (*sql.DB, error)

New establishes a database connection according to the type and environmental variables for that specific database.

func NewAndMigrate 

func NewAndMigrate(ctx context.Context, logger log.Logger, config DatabaseConfig, opts ...MigrateOption) (*sql.DB, error)

func NewPkgerSource added in v0.15.2 

func NewPkgerSource(database string, allowGeneric bool) (source.Driver, error)

func NopInTx added in v0.19.0 

func NopInTx() error

func PoolDBStats added in v0.62.0 

func PoolDBStats(db *sql.DB) (sql.DBStats, bool)

PoolDBStats returns sql.DBStats derived from the underlying pgxpool when db was opened by this package's Postgres/AlloyDB path.

ok is false for MySQL/Spanner DBs, unknown *sql.DB values, or after Close. Callers that scrape connection pressure (for example OTel db-metrics spans) should prefer this over db.Stats() for Postgres from New.

Mapping from pgxpool.Stat: 

MaxOpenConnections ← MaxConns
OpenConnections    ← TotalConns
InUse              ← AcquiredConns
Idle               ← IdleConns
WaitCount          ← EmptyAcquireCount
WaitDuration       ← EmptyAcquireWaitTime
MaxIdleTimeClosed  ← MaxIdleDestroyCount
MaxLifetimeClosed  ← MaxLifetimeDestroyCount
MaxIdleClosed      ← 0 (no pgxpool equivalent)

func PostgresDeadlockFound added in v0.54.3 

func PostgresDeadlockFound(err error) bool

PostgresDeadlockFound returns true when the provided error matches the Postgres code for deadlock found.

func PostgresDriver added in v0.53.0 

func PostgresDriver(db *sql.DB) (database.Driver, error)

func PostgresUniqueViolation added in v0.53.0 

func PostgresUniqueViolation(err error) bool

PostgresUniqueViolation returns true when the provided error matches the Postgres code for unique violation.

func RecordMySQLStats added in v0.27.4 

func RecordMySQLStats(db *sql.DB) error

func RunMigrations 

func RunMigrations(logger log.Logger, config DatabaseConfig, opts ...MigrateOption) error

func RunMigrationsContext added in v0.52.0 

func RunMigrationsContext(ctx context.Context, logger log.Logger, config DatabaseConfig, opts ...MigrateOption) error

func SpannerDriver added in v0.40.0 

func SpannerDriver(config DatabaseConfig) (database.Driver, error)

func SpannerMigrationDriver added in v0.40.0 

func SpannerMigrationDriver(cfg SpannerConfig, databaseName string) (database.Driver, error)

func SpannerUniqueViolation added in v0.41.0 

func SpannerUniqueViolation(err error) bool

SpannerUniqueViolation returns true when the provided error matches the Spanner code for duplicate entries (violating a unique table constraint). Refer to https://cloud.google.com/spanner/docs/error-codes for Spanner error definitions, and https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto for error codes

func UniqueViolation 

func UniqueViolation(err error) bool

UniqueViolation returns true when the provided error matches a database error for duplicate entries (violating a unique table constraint).

Types

type ConnectionsConfig added in v0.17.0 

type ConnectionsConfig struct {
	MaxOpen     int
	MaxIdle     int
	MaxLifetime time.Duration
	MaxIdleTime time.Duration
}

ConnectionsConfig tunes the database connection pool.

For MySQL these map to database/sql setters via ApplyConnectionsConfig. For Postgres/AlloyDB they map to pgxpool via ApplyPostgresPoolConfig: 

MaxOpen     -> pgxpool MaxConns (required; pgxpool has no "unlimited")
MaxLifetime  -> pgxpool MaxConnLifetime
MaxIdleTime -> pgxpool MaxConnIdleTime
MaxIdle     -> ignored (no pgxpool equivalent; logged when > 0)

Zero means "unset". For Postgres, unset fields are filled from DefaultPostgresConnectionsConfig — unlike database/sql, 0 does not mean unlimited.

func DefaultPostgresConnectionsConfig added in v0.62.0 

func DefaultPostgresConnectionsConfig() ConnectionsConfig

DefaultPostgresConnectionsConfig returns library defaults applied when a Postgres/AlloyDB ConnectionsConfig field is zero.

Operator notes

These defaults change runtime behavior versus the previous database/sql + pgx driver path, where unset fields meant unlimited:

  • MaxOpen (25): pgxpool always has a finite MaxConns. Unset MaxOpen no longer means unlimited — it becomes 25. High-concurrency services must set PostgresConfig.Connections.MaxOpen explicitly if they need more.
  • MaxLifetime (5m): connections are recycled after this age. ApplyPostgresPoolConfig also sets MaxConnLifetimeJitter (pgxpool defaults it to 0) so recycling is staggered. Unset previously meant no max lifetime. Shorter lifetime helps drop stale sockets after AlloyDB failover; increase if reconnect cost (for example AlloyDB IAM) is more expensive than churn.
  • MaxIdleTime (2m): idle connections are closed after this duration. Unset previously meant keep idle forever. Quiet processes will reconnect after idle gaps; raise this if cold-connect latency matters.
  • MaxIdle: not defaulted and not applied for Postgres (no pgxpool equivalent). Prefer MaxOpen to bound total connections.

Override any value via PostgresConfig.Connections. There is no sentinel for "unlimited" lifetime or idle time under pgxpool — leave a field zero only when the default above is acceptable.

func ResolvePostgresConnectionsConfig added in v0.62.0 

func ResolvePostgresConnectionsConfig(connections ConnectionsConfig) ConnectionsConfig

ResolvePostgresConnectionsConfig returns connections with zero-valued fields replaced by DefaultPostgresConnectionsConfig.

type DatabaseConfig 

type DatabaseConfig struct {
	MySQL        *MySQLConfig
	Spanner      *SpannerConfig
	Postgres     *PostgresConfig
	DatabaseName string
	Retries      *RetryConfig
}

type ErrOpenConnections added in v0.14.0 

type ErrOpenConnections struct {
	Database       string
	NumConnections int
}

ErrOpenConnections describes the number of open connections that should have been closed by a call to Close(). All queries/transactions should call Close() to prevent unused, open connections.

func (ErrOpenConnections) Error added in v0.14.0 

func (e ErrOpenConnections) Error() string

type MigrateOption added in v0.44.0 

type MigrateOption func(o *migrateOptions) error

func WithEmbeddedMigrations added in v0.44.0 

func WithEmbeddedMigrations(f fs.FS) MigrateOption

func WithTimeout added in v0.44.0 

func WithTimeout(dur time.Duration) MigrateOption

type MySQLConfig 

type MySQLConfig struct {
	Address        string
	User           string
	Password       string `json:"-"`
	Connections    ConnectionsConfig
	UseTLS         bool
	TLSCAFile      string
	VerifyCAFile   bool
	TLSClientCerts []TLSClientCertConfig

	// InsecureSkipVerify is a dangerous option which should be used with extreme caution.
	// This setting disables multiple security checks performed with TLS connections.
	InsecureSkipVerify bool
}

func (*MySQLConfig) MarshalJSON added in v0.20.0 

func (m *MySQLConfig) MarshalJSON() ([]byte, error)

type PostgresAlloyConfig added in v0.53.0 

type PostgresAlloyConfig struct {
	InstanceURI string
	UseIAM      bool
	UsePSC      bool
}

type PostgresConfig added in v0.53.0 

type PostgresConfig struct {
	Address     string
	User        string
	Password    string `json:"-"`
	Connections ConnectionsConfig
	TLS         *PostgresTLSConfig
	Alloy       *PostgresAlloyConfig
}

PostgresConfig configures a Postgres or AlloyDB connection opened by New.

Pool behavior (pgxpool under *sql.DB):

  • Connections settings are applied to the underlying pgxpool, not database/sql.
  • Zero-valued fields on Connections are filled from DefaultPostgresConnectionsConfig (see that function for operator-facing defaults and upgrade notes).
  • Connections.MaxIdle has no pgxpool equivalent and is ignored (logged when set).
  • Do not call sql.DB SetMaxIdleConns with a non-zero value on the returned DB; OpenDBFromPool requires MaxIdleConns=0 so connections return to pgxpool.
  • db.Stats() is not meaningful for capacity (sql.DB does not hold the pool). Use PoolDBStats(db) for real pgxpool pressure (wired into go-libs observability/sql MeasureStats when present).

type PostgresTLSConfig added in v0.53.0 

type PostgresTLSConfig struct {
	Mode string

	CACertFile     string
	ClientKeyFile  string
	ClientCertFile string
}

type RetryConfig added in v0.60.0 

type RetryConfig struct {
	MaxAttempts int
	MinDuration time.Duration
	MaxDuration time.Duration
}

type RunInTx added in v0.19.0 

type RunInTx func() error

type SourceDriver added in v0.44.0 

type SourceDriver struct {
	source.Driver
	// contains filtered or unexported fields
}

type SpannerConfig added in v0.40.0 

type SpannerConfig struct {
	Project  string
	Instance string

	DisableCleanStatements bool
}

type TLSClientCertConfig added in v0.35.0 

type TLSClientCertConfig struct {
	CertFilePath string
	KeyFilePath  string
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.