pgsql

Documentation

Overview

Package pgsql provides a PostgreSQL implementation of sql.DB.

Index

• func New(ctx context.Context, host string, port int, user string, name string, ...) (*sql.DB, error)
• func NewFromConfig(ctx context.Context, conf Config) (*sql.DB, error)
• type Config
• type Option
  • func WithIAMAuth(endpoint, region, user string) Option
  • func WithMaxIdleConns(count int) Option
  • func WithMaxIdleTime(d time.Duration) Option
  • func WithMaxLifetime(d time.Duration) Option
  • func WithMaxOpenConns(count int) Option
  • func WithPassword(password string) Option

Functions

func New

func New(
	ctx context.Context,
	host string,
	port int,
	user string,
	name string,
	sslmode string,
	options ...Option,
) (*sql.DB, error)

New creates a new sql.DB for the given PostgreSQL database.

The returned database connection pool has the following features:

• Built-in OpenTelemetry tracing and metrics.
• Automatic closure of connections that observe a read-only transaction error to enable recovery when a primary server moves to standby.

func NewFromConfig

func NewFromConfig(ctx context.Context, conf Config) (*sql.DB, error)

NewFromConfig creates a new sql.DB using the given configuration.

Types

type Config

type Config struct {
	// The hostname of the database server.
	Hostname string `koanf:"hostname"`

	// The port the database server is listening on. Defaults to 5432.
	Port int `koanf:"port" default:"5432"`

	// The username to authenticate with.
	Username string `koanf:"username"`

	// The password to authenticate with. This should be omitted when UseIAMAuth is set to true.
	Password string `koanf:"password" json:"-"`

	// Enables the use of IAM authentication. For use in AWS environments only.
	UseIAMAuth bool `koanf:"useiamauth"`

	// The AWS region of the database server. For use in AWS environments only.
	Region string `koanf:"region"`

	// The name of the database to connect to.
	Name string `koanf:"name"`

	// The SSL mode to connect with. Defaults to verify-full.
	SSLMode string `koanf:"sslmode" default:"verify-full"`

	// The maximum time a database connection can be idle before being closed. Defaults to 5
	// minutes. Set to 0 to disable.
	MaxIdleTime time.Duration `koanf:"maxidletime" default:"5m"`

	// The maximum lifetime for a database connection. Defaults to 5 minutes. Set to 0 to disable.
	MaxLifetime time.Duration `koanf:"maxlifetime" default:"5m"`

	// The maximum number of idle connections in the database connection pool. Defaults to no limit.
	MaxIdleConns int `koanf:"maxidleconns"`

	// The maximum number of open connections in the database connection pool. Defaults to no limit.
	//
	// It is strongly recommended to set this value when sharing a single database server across
	// multiple clients to avoid accidentally starving other clients of connections.
	MaxOpenConns int `koanf:"maxopenconns"`
}

Config contains configuration for connecting to a PostgreSQL database. It is intended to be populated by internal/drivers/config.Load.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option customises the behaviour when creating a sql.DB.

func WithIAMAuth

func WithIAMAuth(endpoint, region, user string) Option

WithAIMAuth enables the use of AWS IAM for database authentication.

Based on AWS docs (untested).

func WithMaxIdleConns

func WithMaxIdleConns(count int) Option

WithMaxIdleConns limits the number of idle connections in the database connection pool.

func WithMaxIdleTime

func WithMaxIdleTime(d time.Duration) Option

WithMaxIdleTime sets the maximum idle time for a database connection. Defaults to 5 minutes. Set to 0 to disable.

The maximum idle time should be set to avoid the effects of idle connections being closed. For example, Istio will close idle connections after 60 minutes, which is only observable when trying to use the now closed connection. By setting a timeout below this value, Istio's timeout will never be observed and the availability impact never felt.

func WithMaxLifetime

func WithMaxLifetime(d time.Duration) Option

WithMaxLifetime sets the maximum lifetime for a database connection. Defaults to 5 minutes. Set to 0 to disable.

The 5 minute default value allows some connection issues to be automatically recovered from in a relatively short period of time. For example, if a deadlock is created, it can last no longer than 5 minutes. The chosen value is by no means perfect, but is intended to be a good start to refine from.

func WithMaxOpenConns

func WithMaxOpenConns(count int) Option

WithMaxOpenConns limits the number of open connections in the database connection pool.

func WithPassword

func WithPassword(password string) Option

WithPassword sets the password to authenticate with.