postgres

package
v0.10.0 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package postgres is a platform module: a PostgreSQL connection pool with a health check, pool metrics and a clean shutdown.

The module writes no queries: sqlc generates the static ones, jet builds the dynamic ones.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Apply added in v0.9.0

func Apply(modules []platform.Module, opts ...Option) error

Apply passes options to the postgres modules among modules; call it before platform.Run, since the module opens its pool in Init. The module is built by the generated modules.gen.go, so a project adds its hooks and pool defaults in main.go:

modules := platformModules(cfg)
if err := postgres.Apply(modules,
	postgres.WithDefaults(postgres.PoolSizes{MaxConns: 25, MinConns: 5, MaxConnIdleTime: 10 * time.Minute}),
	postgres.WithAfterConnect(registerTypes),
); err != nil {
	log.Fatal(err)
}

Apply fails when modules has no postgres module: hooks the project relies on must not be dropped silently.

func InTx

func InTx(ctx context.Context, app *platform.App, fn func(tx pgx.Tx) error) error

InTx runs fn in a transaction on the pool from the container.

func Pool

func Pool(app *platform.App) *pgxpool.Pool

Pool returns the pool from the container.

func SQL added in v0.2.0

func SQL(app *platform.App) *sql.DB

SQL returns database/sql over the pool from the container. Dynamic queries built with jet run through it: stmt.QueryContext(ctx, postgres.SQL(app), &dest).

Types

type Config

type Config struct {
	URL             string
	MaxConns        int32
	MinConns        int32
	MaxConnLifetime time.Duration
	MaxConnIdleTime time.Duration
	ConnectTimeout  time.Duration

	// Migrate applies pending migrations during startup. Turn it off when migrations
	// run as a separate step of the deploy.
	Migrate bool
	// contains filtered or unexported fields
}

Config holds module settings. Load fills it from the environment; the platform generator writes the Load call into the project's config.gen.go.

func Load

func Load(l *confx.Loader) Config

Load reads the module settings from environment variables.

type Module

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

Module implements platform.Module.

func New

func New(cfg Config, opts ...Option) *Module

New creates the module from ready settings.

func (*Module) Health

func (m *Module) Health(ctx context.Context) error

Health reports whether the database answers.

func (*Module) Init

func (m *Module) Init(ctx context.Context, app *platform.App) error

Init opens the pool, verifies the connection and puts the pool into the container, where other modules and project code pick it up through Pool(app).

func (*Module) Name

func (m *Module) Name() string

func (*Module) Stop

func (m *Module) Stop(context.Context) error

Stop closes the pool, waiting for busy connections to come back.

type Option added in v0.2.0

type Option func(*Module)

Option configures the module.

func WithAfterConnect added in v0.9.0

func WithAfterConnect(hook func(ctx context.Context, conn *pgx.Conn) error) Option

WithAfterConnect adds a hook run on every new connection, after the platform has registered its types (numeric as decimal.Decimal). Projects register their own types here. Hooks run in the order they were added; an error discards the connection. A nil hook is ignored.

func WithDefaults added in v0.9.0

func WithDefaults(p PoolSizes) Option

WithDefaults sets the pool sizes of the application. They replace the defaults of the platform, while a DATABASE_* variable that is set still wins, and so does a field of Config the project changed after Load. In a Config built by hand rather than by Load, a non-zero field counts as set. A zero field of p changes nothing; a later WithDefaults overrides the non-zero fields of an earlier one.

func WithMigrations added in v0.2.0

func WithMigrations(fsys fs.FS) Option

WithMigrations gives the module the migrations of the project. The generated wiring passes the embedded db/migrations directory.

func WithPoolConfig added in v0.9.0

func WithPoolConfig(fn func(*pgxpool.Config)) Option

WithPoolConfig adds a function that adjusts the pgx pool settings once the sizes are applied, for what the module does not expose. Functions run in the order they were added. A nil function is ignored.

type PoolSizes added in v0.9.0

type PoolSizes struct {
	MaxConns        int32
	MinConns        int32
	MaxConnLifetime time.Duration
	MaxConnIdleTime time.Duration
	ConnectTimeout  time.Duration
}

PoolSizes holds the pool settings an application chooses as its defaults. A zero field keeps the default of the platform, so a default cannot be zero; a project that needs a zero sets the field of Config or the DATABASE_* variable.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL