postgres

Documentation

Overview

Package postgres is a PostgreSQL connection as a dependency: a configuration section, a pgx pool traced and measured through the service's OpenTelemetry providers, a query log, pgtx transactions, an optional schema and sqld migrations applied at start, a ping probe.

type Config struct {
    config.Backplane `json:"backplane"`
    DB postgres.Config `json:"db"` // GREETER_DB_DSN, GREETER_DB_POOL_MAX_CONNS, ...
}

//go:embed migrations/*.sql
var migrations embed.FS

db := deps.NewDependency(root, postgres.New(cfg.DB, postgres.Migrations(migrations)))
err := tx.DoSerializable(ctx, db.Get().Trm, func(ctx context.Context) error { ... })

Index

• Variables
• func New(cfg Config, opts ...Option) deps.Provider[*DB]
• type Config
  • func (c Config) Enabled() bool
  • func (c Config) Validate() error
• type DB
  • func Open(ctx context.Context, log *xlog.Logger, cfg Config, opts ...Option) (*DB, error)
  • func (db *DB) Close()
  • func (db *DB) Ping(ctx context.Context) error
• type Option
  • func Migrations(fsys ...fs.FS) Option
  • func Schema(name string) Option
  • func Serializable() Option
• type Pool

Variables

var (
	// ErrNoDSN: the section has no connection string.
	ErrNoDSN = errors.New("postgres: dsn is required")
	// ErrDSN: the connection string does not parse (not quoted: it may
	// hold a password).
	ErrDSN = errors.New("postgres: dsn does not parse")
)

Errors of Config.

Functions

func New

func New(cfg Config, opts ...Option) deps.Provider[*DB]

New is the provider of the connection: Provide opens it (Open), the probe pings, Close releases the pool.

Types

type Config

type Config struct {
	// DSN is a libpq URL or key=value string (secret: it may hold the
	// password).
	DSN config.Secret `desc:"libpq URL or key=value string." json:"dsn,omitempty"`
	// QueryLog is the lowest level of the per-query log: trace, debug,
	// info, warn, error or none. Arguments are never logged.
	QueryLog string `` /* 151-byte string literal not displayed */
	Pool     Pool   `desc:"Connection pool."                                                                                        json:"pool"`
}

Config is the connection's section.

func (Config) Enabled

func (c Config) Enabled() bool

Enabled reports whether a connection string is set.

func (Config) Validate

func (c Config) Validate() error

Validate checks what the schema cannot: the connection string is set and parses, the query log level is known.

type DB

type DB struct {
	// Pool for what DB does not cover (LISTEN, COPY).
	Pool *pgxpool.Pool
	// Trm owns transaction boundaries: tx.Do, tx.DoSerializable.
	Trm tx.Trm
	// DB routes to the context's transaction, else the pool; generated
	// queries run on it.
	DB tx.DB
}

DB is the pool with its transaction manager. It is shared by pointer: it holds the pool.

func Open

func Open(ctx context.Context, log *xlog.Logger, cfg Config, opts ...Option) (*DB, error)

Open connects, pings, creates the schema and applies the migrations.

func (*DB) Close

func (db *DB) Close()

Close releases the pool.

func (*DB) Ping

func (db *DB) Ping(ctx context.Context) error

Ping checks the connection.

type Option

type Option func(o *options)

Option configures Open and New.

func Migrations

func Migrations(fsys ...fs.FS) Option

Migrations are applied at start in version order (sqld's migrate, under its advisory lock): directories of *.sql, e.g. an embed.FS.

func Schema

func Schema(name string) Option

Schema makes every connection run with search_path=name and creates the schema before migrating, so the migrations' bookkeeping lives there too.

func Serializable

func Serializable() Option

Serializable makes serializable the transaction manager's default isolation (read committed without it).

type Pool

type Pool struct {
	MaxConns        int64         `desc:"Most open connections; 0: pgx's default."                 json:"max_conns"          schemapb:"default=0;gte=0"`
	MinConns        int64         `desc:"Connections kept open when idle."                         json:"min_conns"          schemapb:"default=0;gte=0"`
	MaxConnLifetime time.Duration `desc:"A connection this old is closed; 0: pgx's default."       json:"max_conn_lifetime"  schemapb:"default=0s;gte=0"`
	MaxConnIdleTime time.Duration `desc:"A connection idle this long is closed; 0: pgx's default." json:"max_conn_idle_time" schemapb:"default=0s;gte=0"`
}

Pool bounds the pgx pool; a zero field is pgx's default. Set MaxConns explicitly in production: the default follows the node's CPUs.