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
- Variables
- func CheckDigest(ctx context.Context, c testcontainers.Container, digest string) error
- func Database(t testing.TB) string
- func Judge(t testing.TB) *sql.DB
- func Open(t testing.TB) *sql.DB
- func OpenDatabase(t testing.TB, role, name string) *sql.DB
- func OpenDatabaseNumberingOIDs(t testing.TB, role, name string) *sql.DB
- func OpenMissingDatabase(t testing.TB, role, name string) *sql.DB
- func OpenRole(t testing.TB, role string) *sql.DB
- func OpenRoleNumberingOIDs(t testing.TB, role string) *sql.DB
- func Reset(t testing.TB, fn func(ctx context.Context, db *sql.DB) error)
- func ResetRole(t testing.TB, role string, fn func(ctx context.Context, db *sql.DB) error)
- func Terminate()
- func Version(tag string) string
- type Codec
Constants ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 OpenRoleNumberingOIDs ¶
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 ¶
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.
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.