pgsql

Documentation

Index

• Variables
• type Config
• type Manager
  • func NewManager(config Config) *Manager
  • func (m *Manager) Close(_ context.Context)
  • func (m *Manager) Exec(ctx context.Context, query string, args ...any) (pgconn.CommandTag, error)
  • func (m *Manager) Healthcheck(ctx context.Context) error
  • func (m *Manager) Migrate(ctx context.Context) error
  • func (m *Manager) Pool(ctx context.Context) (*pgxpool.Pool, error)
  • func (m *Manager) Query(ctx context.Context, query string, args ...any) (pgx.Rows, error)
  • func (m *Manager) QueryRow(ctx context.Context, query string, args ...any) (pgx.Row, error)
  • func (m *Manager) WithTx(ctx context.Context, fn func(tx pgx.Tx) error) (err error)

Variables

var Migrations embed.FS

Types

type Config

type Config struct {
	// DSN is the libpq-style connection string, e.g.:
	//   postgres://user:pass@localhost:5432/dbname
	// Do not append search_path manually - set Schema instead.
	DSN string

	// Schema is the PostgreSQL schema (namespace) to target.
	// When non-empty the manager:
	//   - appends ?search_path=<schema> to the DSN so pgxpool targets it
	//   - issues CREATE SCHEMA IF NOT EXISTS in Migrate()
	//   - sets search_path on the migration connection explicitly
	Schema string

	// The minimum connections to the PostgreSQL pool.
	MinConns int32

	// The maximum connections to the PostgreSQL pool.
	MaxConns int32

	Logger *zap.Logger
	Tracer trace.Tracer
	Meter  metric.Meter
}

Config holds all parameters needed to connect and operate the Manager.

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager manages a pgxpool connection with automatic reconnection and health-check debouncing.

func NewManager

func NewManager(config Config) *Manager

NewManager creates a new PostgreSQL manager.

func (*Manager) Close

func (m *Manager) Close(_ context.Context)

Close shuts down the connection pool.

func (*Manager) Exec

func (m *Manager) Exec(ctx context.Context, query string, args ...any) (pgconn.CommandTag, error)

Exec executes a statement that returns no rows (INSERT, UPDATE, DELETE, ...).

func (*Manager) Healthcheck

func (m *Manager) Healthcheck(ctx context.Context) error

Healthcheck verifies that the pool can reach PostgreSQL.

func (*Manager) Migrate

func (m *Manager) Migrate(ctx context.Context) error

Migrate runs all pending up-migrations from the embedded Migrations FS. Call this once at service startup, before the service accepts traffic.

Migration files must follow the golang-migrate naming convention:

migrations/000001_description.up.sql
migrations/000001_description.down.sql

func (*Manager) Pool

func (m *Manager) Pool(ctx context.Context) (*pgxpool.Pool, error)

Pool returns the underlying *pgxpool.Pool, reconnecting if necessary.

func (*Manager) Query

func (m *Manager) Query(ctx context.Context, query string, args ...any) (pgx.Rows, error)

Query executes a query that returns rows. The caller must close the returned pgx.Rows when done.

func (*Manager) QueryRow

func (m *Manager) QueryRow(ctx context.Context, query string, args ...any) (pgx.Row, error)

QueryRow executes a query expected to return at most one row. Scan errors are deferred to the returned pgx.Row.

func (*Manager) WithTx

func (m *Manager) WithTx(ctx context.Context, fn func(tx pgx.Tx) error) (err error)

WithTx runs fn inside a transaction, committing on success and rolling back on any error or panic.