pg

Documentation

Index

• func WithPrimary(ctx context.Context) context.Context
• func WithReplicaPolicy(ctx context.Context, name string) context.Context
• func WithReplicaRead(ctx context.Context, opts ReplicaReadOptions) context.Context
• type DB
  • func Connect(ctx context.Context, url string, opts ...Option) (*DB, error)
  • func ConnectCluster(ctx context.Context, url string, replicas []ReplicaConfig, opts ...Option) (*DB, error)
  • func (db *DB) Aggregate(ctx context.Context, spec runtime.AggregateSpec) pgx.Row
  • func (db *DB) Close()
  • func (db *DB) Query(ctx context.Context, table, sql string, args ...any) (pgx.Rows, error)
  • func (db *DB) QueryRow(ctx context.Context, table, sql string, args ...any) pgx.Row
  • func (db *DB) Reader(ctx context.Context) Pool
  • func (db *DB) Select(ctx context.Context, spec runtime.SelectSpec) (pgx.Rows, error)
  • func (db *DB) SetReplicaHealthInterval(interval time.Duration)
  • func (db *DB) UseObserver(observer runtime.QueryObserver)
  • func (db *DB) UseReplicaHealthCheck(check ReplicaHealthCheck)
  • func (db *DB) UseReplicaPolicies(defaultPolicy string, policies map[string]ReplicaReadOptions)
  • func (db *DB) Writer() Pool
• type Option
  • func WithHealthCheckPeriod(d time.Duration) Option
  • func WithMaxConnIdleTime(d time.Duration) Option
  • func WithMaxConnLifetime(d time.Duration) Option
  • func WithMaxConns(n int32) Option
  • func WithMinConns(n int32) Option
  • func WithPoolConfig(pc PoolConfig) Option
  • func WithTracer(tracer tracing.Tracer) Option
• type Pool
• type PoolConfig
• type ReplicaConfig
• type ReplicaHealthCheck
• type ReplicaHealthReport
• type ReplicaReadOptions
  • func (opts ReplicaReadOptions) AllowFallback() bool

Functions

func WithPrimary

func WithPrimary(ctx context.Context) context.Context

WithPrimary ensures the primary writer connection is used even when replica policies would normally route the query elsewhere.

func WithReplicaPolicy

func WithReplicaPolicy(ctx context.Context, name string) context.Context

WithReplicaPolicy annotates the context with a routing policy name. The driver resolves the policy against the set configured via UseReplicaPolicies.

func WithReplicaRead

func WithReplicaRead(ctx context.Context, opts ReplicaReadOptions) context.Context

WithReplicaRead requests that read operations attempt to use a replica according to the provided options.

Types

type DB

type DB struct {
	Pool Pool

	Observer runtime.QueryObserver
	// contains filtered or unexported fields
}

DB manages writer and replica pools plus observability hooks.

func Connect

func Connect(ctx context.Context, url string, opts ...Option) (*DB, error)

Connect initialises a pgx pool with optional configuration overrides.

func ConnectCluster

func ConnectCluster(ctx context.Context, url string, replicas []ReplicaConfig, opts ...Option) (*DB, error)

ConnectCluster initialises a primary pool plus the provided replicas.

func (*DB) Aggregate

func (db *DB) Aggregate(ctx context.Context, spec runtime.AggregateSpec) pgx.Row

Aggregate issues an aggregate query generated from runtime specs against the appropriate pool.

func (*DB) Close

func (db *DB) Close()

Close releases all underlying pools.

func (*DB) Query

func (db *DB) Query(ctx context.Context, table, sql string, args ...any) (pgx.Rows, error)

Query routes ad-hoc read statements through the replica routing machinery.

func (*DB) QueryRow

func (db *DB) QueryRow(ctx context.Context, table, sql string, args ...any) pgx.Row

QueryRow routes read statements returning a single row through the replica routing machinery.

func (*DB) Reader

func (db *DB) Reader(ctx context.Context) Pool

Reader returns the pool selected for read operations after applying routing policies.

func (*DB) Select

func (db *DB) Select(ctx context.Context, spec runtime.SelectSpec) (pgx.Rows, error)

Select issues a SELECT generated from runtime specs against the appropriate pool.

func (*DB) SetReplicaHealthInterval

func (db *DB) SetReplicaHealthInterval(interval time.Duration)

SetReplicaHealthInterval adjusts the interval between health checks. Zero or negative values force probes before every read attempt.

func (*DB) UseObserver

func (db *DB) UseObserver(observer runtime.QueryObserver)

UseObserver attaches a query observer to the database handle.

func (*DB) UseReplicaHealthCheck

func (db *DB) UseReplicaHealthCheck(check ReplicaHealthCheck)

UseReplicaHealthCheck overrides the health probe used for replicas.

func (*DB) UseReplicaPolicies

func (db *DB) UseReplicaPolicies(defaultPolicy string, policies map[string]ReplicaReadOptions)

UseReplicaPolicies registers named replica routing policies. The default policy name is applied when reads do not explicitly opt-in via context.

func (*DB) Writer

func (db *DB) Writer() Pool

Writer returns the primary pool used for mutations and transactions.

type Option

type Option func(*pgxpool.Config)

Option configures pgx connections.

func WithHealthCheckPeriod

func WithHealthCheckPeriod(d time.Duration) Option

WithHealthCheckPeriod configures the background health check period.

func WithMaxConnIdleTime

func WithMaxConnIdleTime(d time.Duration) Option

WithMaxConnIdleTime configures how long an idle connection may remain in the pool.

func WithMaxConnLifetime

func WithMaxConnLifetime(d time.Duration) Option

WithMaxConnLifetime configures the maximum connection lifetime.

func WithMaxConns

func WithMaxConns(n int32) Option

WithMaxConns sets the maximum pool size.

func WithMinConns

func WithMinConns(n int32) Option

WithMinConns sets the minimum pool size.

func WithPoolConfig

func WithPoolConfig(pc PoolConfig) Option

WithPoolConfig applies a group of pool settings derived from configuration.

func WithTracer

func WithTracer(tracer tracing.Tracer) Option

WithTracer enables pgx tracing using the provided tracer abstraction.

type Pool

type Pool interface {
	Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
	QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
	Exec(ctx context.Context, sql string, args ...any) (pgconn.CommandTag, error)
	Close()
}

Pool exposes the subset of pgxpool behaviour required by generated clients.

type PoolConfig

type PoolConfig struct {
	MaxConns          int32
	MinConns          int32
	MaxConnLifetime   time.Duration
	MaxConnIdleTime   time.Duration
	HealthCheckPeriod time.Duration
}

PoolConfig describes connection pool tuning knobs exposed via configuration.

type ReplicaConfig

type ReplicaConfig struct {
	Name           string
	URL            string
	ReadOnly       bool
	MaxFollowerLag time.Duration
}

ReplicaConfig describes a read replica participating in the cluster.

type ReplicaHealthCheck

type ReplicaHealthCheck func(ctx context.Context, pool Pool) (ReplicaHealthReport, error)

ReplicaHealthCheck probes a replica connection to determine whether it can satisfy reads.

type ReplicaHealthReport

type ReplicaHealthReport struct {
	ReadOnly bool
	Lag      time.Duration
}

ReplicaHealthReport captures the result of a health probe executed against a replica.

type ReplicaReadOptions

type ReplicaReadOptions struct {
	MaxLag          time.Duration
	RequireReadOnly bool
	DisableFallback bool
}

ReplicaReadOptions influence how reads target replicas.

func (ReplicaReadOptions) AllowFallback

func (opts ReplicaReadOptions) AllowFallback() bool

AllowFallback reports whether the read should fall back to the primary when the replica errors.