testcontainer

package
v0.0.0-...-3108594 Latest Latest
Warning

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

Go to latest
Published: Nov 22, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package testcontainer is how pg's tests reach PostgreSQL: through a tape (enginetest/tape) that replays the pinned server's answers, or, in a recording (OMNI_RECORD=1), through the pinned server itself. That server is one testcontainer per pin role and test binary, started by the first test that records on it and removed by Terminate, which the package's TestMain calls.

Index

Constants

View Source
const (
	Default = "default"
	PG18    = "pg18"
)

The pin roles. Default is the release the parser's grammar is read from, and judges compat.tsv; PG18 serves the tests that ask the next major.

Variables

View Source
var Pins = func() string {
	_, file, _, _ := runtime.Caller(0)
	return filepath.Join(filepath.Dir(file), "..", "..", "testdata", "pins.tsv")
}()

Pins is pg/testdata/pins.tsv.

Functions

func CheckDigest

func CheckDigest(ctx context.Context, c testcontainers.Container, digest string) error

CheckDigest proves the container runs the pinned image. The pull names image@digest, so a moved tag cannot select another image; this check reads what the daemon actually started, which is where the recorded answers came from.

func Database

func Database(t testing.TB) string

Database is the name of the database Open connects t to: one per top-level test, named for it, so that a test reads the same current_database() in every recording. PostgreSQL keeps 63 bytes of a name, so a long test name ends in a hash of the whole.

func Judge

func Judge(t testing.TB) *sql.DB

Judge returns a connection to the default server itself, outside any tape, for the judge of compat.tsv, which runs only in a recording. A statement sent with no arguments reaches the server as written, in one simple query.

func Open

func Open(t testing.TB) *sql.DB

Open returns t's connection to PostgreSQL: a replay of its tape, or the pinned server in a recording. Each call is a connection of its own, at session defaults, to the database of t's top-level test (Database). In a recording each top-level test starts on a server that holds nothing another test made: before its first connection the server's other databases and every role the image did not start with are dropped, and its database is created empty.

func OpenDatabase

func OpenDatabase(t testing.TB, role, name string) *sql.DB

OpenDatabase is OpenRole on a database of the given name, for a test whose SQL names its database. A recording creates it empty on the test's first connection to it.

func OpenDatabaseNumberingOIDs

func OpenDatabaseNumberingOIDs(t testing.TB, role, name string) *sql.DB

OpenDatabaseNumberingOIDs is OpenDatabase for a test that reads OIDs as numbers: it gives the named database's connection OID stand-ins, as OpenRoleNumberingOIDs does for the role's own database, so a sync of its system catalogs records a reproducible tape.

func OpenMissingDatabase

func OpenMissingDatabase(t testing.TB, role, name string) *sql.DB

OpenMissingDatabase returns t's connection to a database the pinned server does not have: the server refuses the connection, and a recording holds what it answered. name must be one no test creates; the emptying below drops every database the image did not start with and creates none.

func OpenRole

func OpenRole(t testing.TB, role string) *sql.DB

OpenRole is Open on the server of another pin row, such as PG18.

func OpenRoleNumberingOIDs

func OpenRoleNumberingOIDs(t testing.TB, role string) *sql.DB

OpenRoleNumberingOIDs is OpenRole for a test that reads OIDs as numbers, as a sync of system catalogs does to join them. A user object's OID (16384 and up) is the server's next free one when the object was made, so it differs with what the server made before; in a recording each such value of a result column of type oid becomes a stand-in, 2^32 plus the order in which the test first read that OID, the same in every connection of the test to that server. Stand-ins keep equality and are never sent back.

func Reset

func Reset(t testing.TB, fn func(ctx context.Context, db *sql.DB) error)

Reset runs fn on the default server before a test opens its connection, in a recording only: it puts what databases share (roles, tablespaces) into the state the test's tape starts from, so a replay needs nothing. fn's connection is to the database postgres, and is not recorded.

func ResetRole

func ResetRole(t testing.TB, role string, fn func(ctx context.Context, db *sql.DB) error)

ResetRole is Reset on the server of another pin row.

func Terminate

func Terminate()

Terminate removes every server this run started.

func Version

func Version(tag string) string

Version is the server_version of a source tag: 17.12 for REL_17_12.

Types

type Codec

type Codec struct{}

Codec renders pgx's *pgconn.PgError as its SQLSTATE and message on one line, then a line for each other field the server sent:

42601 syntax error at or near "FROM"
position: 8

A line break inside a field is written \n, and a backslash \\. The source file, line and routine the server names are left out: they say where in PostgreSQL's code the error was raised, and move with a patch release that changes nothing a test reads.

func (Codec) DecodeError

func (Codec) DecodeError(text string) error

func (Codec) EncodeError

func (Codec) EncodeError(err error) (string, bool)

func (Codec) MadeUp

func (Codec) MadeUp() *regexp.Regexp

MadeUp matches an OID read as text.

func (Codec) StandIn

func (Codec) StandIn(_ string, n int) string

StandIn is the nth OID's stand-in: no OID's text starts with a 0.

Jump to

Keyboard shortcuts

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