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
- func InTx(ctx context.Context, pool *pgxpool.Pool, fn func(tx pgx.Tx) error) error
- func Migrate(ctx context.Context, pool *pgxpool.Pool, fsys fs.FS, log *slog.Logger) ([]string, error)
- func MigrateSchema(ctx context.Context, db Beginner, owner string, steps []SchemaStep) error
- func Open(ctx context.Context, cfg Config) (*pgxpool.Pool, error)
- func RegisterTypes(conn *pgx.Conn)
- type Beginner
- type Config
- type Hooks
- type SchemaStep
Constants ¶
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 ¶
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
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 ¶
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
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
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
SchemaStep is one version of the tables a platform module owns.