postgrestest

package
v0.65.0 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package postgrestest provides PostgreSQL test harnesses backed by postgres.

It owns the harnesses that stand up a database for a test, prove a migration set reversible, and snapshot a schema. The connection, transaction and migration primitives they rest on live in postgres.

Index

Constants

This section is empty.

Variables

View Source
var ErrUnsupportedSchemaObject = errors.New("schema holds an object class the census cannot render")

ErrUnsupportedSchemaObject reports a schema object the census cannot safely compare. Such objects fail instead of being silently omitted.

Functions

func NewContextTest

func NewContextTest(ctx context.Context, config postgres.Config) (context.Context, string, error)

NewContextTest derives a context bound to a fresh, randomly named schema created through config, isolating the test from others sharing the database. It returns the schema name so the caller can drop it once done.

func RunDBTest

func RunDBTest(t *testing.T, config postgres.Config, migrations fs.FS, callback TransactionalTestFunc)

RunDBTest runs callback against a fresh PostgreSQL database of its own, cloned from a migrated template with `CREATE DATABASE … TEMPLATE`. Each call is isolated, so the test and its sub-tests may run in parallel even when they reuse the same fixture keys.

The migrations run once, into a template database named after their hash. Each test then gets a fast file-level copy of that template. The test's cleanup drops the copy. The template stays for later runs until the migrations change.

config must expose Options() []pgdriver.Option, as postgrespresets.Default does. callback receives a context carrying a *bun.DB for its database, which postgres.GetContext returns.

func RunIsolatedTransactionalTest

func RunIsolatedTransactionalTest(
	t *testing.T,
	config postgres.Config,
	migrations fs.FS,
	callback TransactionalTestFunc,
)

RunIsolatedTransactionalTest runs callback in a throwaway schema, which admits operations a transaction cannot host concurrently, such as refreshing a materialized view.

The schema lives in the existing database, so its extensions remain available. Each call reruns the whole migration set, which makes RunTransactionalTest the cheaper default.

func RunMigrationRoundtripTest

func RunMigrationRoundtripTest(t *testing.T, config postgres.Config, migrations fs.FS, opts *RoundtripOptions)

RunMigrationRoundtripTest proves that every down migration exactly reverses its up.

It snapshots each up, verifies each down against the preceding snapshot, then re-applies the full set. Fixtures run between steps. Snapshots bind each schema to its exact migration prefix.

config must expose Options() []pgdriver.Option, as postgrespresets.Default does.

func RunTransactionalTest

func RunTransactionalTest(t *testing.T, config postgres.Config, callback TransactionalTestFunc)

RunTransactionalTest runs callback inside a transaction that is rolled back on cleanup. Sub-transactions resolve to that same transaction, so concurrent calls sharing the connection cannot deadlock.

func SchemaSnapshot

func SchemaSnapshot(ctx context.Context, db bun.IDB, schema string) (string, error)

SchemaSnapshot renders supported schema objects as canonical, sorted, one-line records. PostgreSQL renders definitions, so statement order and DDL spelling do not affect the result.

It includes database-scoped extensions and schemas, reads no row data, and returns ErrUnsupportedSchemaObject for an object class it cannot render.

func SnapshotDelta

func SnapshotDelta(want, got string) []string

SnapshotDelta returns sorted per-object differences between want and got. Records are compared as a set.

Types

type RoundtripOptions

type RoundtripOptions struct {
	// Fixtures holds optional `<timestamp>_<name>.sql` files, applied after the named migration.
	Fixtures fs.FS

	// Snapshots is the directory holding one schema snapshot per migration, each bound to the
	// migration history up to it. Empty skips them. Setting GOLIB_UPDATE_SNAPSHOTS rewrites them.
	Snapshots string
}

RoundtripOptions configures RunMigrationRoundtripTest. Its zero value is valid.

type TransactionalTestFunc

type TransactionalTestFunc func(context.Context, *testing.T)

TransactionalTestFunc is the body of a database-backed test, run with a context carrying the connection isolated for that test.

Jump to

Keyboard shortcuts

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