pgdb

package
v0.11.0 Latest Latest
Warning

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

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

Documentation

Overview

Package pgdb opens a PostgreSQL connection pool and helps with transactions.

It stays deliberately thin: queries are written by generators (sqlc for static ones, jet for dynamic ones) and only the parts identical in every project live here.

Index

Constants

View Source
const SchemaVersionsTable = "platform_schema_versions"

SchemaVersionsTable records the schema version of every owner that MigrateSchema ran for.

Variables

This section is empty.

Functions

func InTx

func InTx(ctx context.Context, pool *pgxpool.Pool, fn func(tx pgx.Tx) error) error

InTx runs fn inside a transaction: it rolls back on error or panic and commits otherwise.

func Migrate added in v0.2.0

func Migrate(ctx context.Context, pool *pgxpool.Pool, fsys fs.FS, log *slog.Logger) ([]string, error)

Migrate applies the pending SQL migrations from fsys and returns the files it applied.

Migrations are goose files ("-- +goose Up"). A session advisory lock is held while they run, so several instances starting at once apply each migration exactly once. Files other than *.sql are ignored: the embedded directory also holds its Go file.

func MigrateSchema added in v0.8.0

func MigrateSchema(ctx context.Context, db Beginner, owner string, steps []SchemaStep) error

MigrateSchema brings the tables a platform module owns to its last step.

Project tables live in goose migrations (Migrate); a module's own tables are versioned here, per owner, so a release can add a column and every database gets it. Steps run in one transaction under an advisory lock, so several instances starting at once apply each step exactly once. A database already at a newer version than the steps — a rollback to an older release — is left as it is: schema changes must stay readable by the release before them. Statements must be transactional: no CONCURRENTLY.

func Open

func Open(ctx context.Context, cfg Config) (*pgxpool.Pool, error)

Open creates the pool and verifies the connection. Without the check the service would start against an unreachable database and fail later, on a user request.

func RegisterTypes added in v0.9.0

func RegisterTypes(conn *pgx.Conn)

RegisterTypes registers the types the platform maps for every project on a connection: numeric as decimal.Decimal, the type the generated sqlc config uses for it. The codec sends numeric in the binary format, also inside arrays, instead of the text fallback through sql.Scanner. Open calls it on every connection; call it yourself on a connection made without Open.

Types

type Beginner added in v0.8.0

type Beginner interface {
	Begin(ctx context.Context) (pgx.Tx, error)
}

Beginner starts a transaction: *pgxpool.Pool, *pgx.Conn and pgx.Tx all satisfy it.

type Config

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

	// Hooks are what a project adds to every connection and to the pool settings; nil adds
	// nothing. They sit behind a pointer, so Config stays comparable with ==.
	Hooks *Hooks
}

Config holds pool settings. Empty fields fall back to defaults.

type Hooks added in v0.9.0

type Hooks struct {
	// AfterConnect runs on every new connection, after the platform has registered its
	// types (numeric as decimal.Decimal). Projects register their own types here, such as
	// enums or composite types. An error discards the connection.
	AfterConnect func(ctx context.Context, conn *pgx.Conn) error

	// ConfigurePool adjusts the pgx pool settings once the fields of Config are applied,
	// for what Config does not cover: BeforeAcquire, a tracer, runtime parameters. An
	// AfterConnect set here runs after the platform types and before Hooks.AfterConnect.
	ConfigurePool func(*pgxpool.Config)
}

Hooks extend the pool Open makes.

type SchemaStep added in v0.8.0

type SchemaStep struct {
	Version    int
	Statements []string
}

SchemaStep is one version of the tables a platform module owns.

Jump to

Keyboard shortcuts

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