README
¶
PostgreSQL integration fixture
A test-only module that provisions isolated, digest-pinned PostgreSQL containers and hosts the database/postgres adapter's integration suite. It is a separate module so the adapter and its consumers never depend on container tooling. Docker is required; missing infrastructure fails rather than skipping.
See the adapter README for Start, Connect, Open, isolated databases, role pairs and TLS fixtures.
GOWORK=off go test -tags integration -race -shuffle=on -count=1 ./...
Documentation
¶
Overview ¶
Package testutil provisions isolated, digest-pinned PostgreSQL containers for integration tests. Docker is a required prerequisite; failures never skip tests. Import this package only from test code, not application runtime packages.
Index ¶
Constants ¶
const ( // EnvAddr is the shared server's host:port. When it is empty, Open starts an owned container. EnvAddr = "GOKIT_POSTGRES_TEST_ADDR" // EnvUser is the shared server's superuser; it defaults to "postgres". EnvUser = "GOKIT_POSTGRES_TEST_USER" // EnvPasswordFile is a file holding the superuser's password. Leave it empty for servers that trust local logins. EnvPasswordFile = "GOKIT_POSTGRES_TEST_PASSWORD_FILE" //nolint:gosec // Names an environment variable, not a credential. )
Environment variables that select a shared PostgreSQL server for Open.
const Image = "postgres:17-alpine@sha256:18cfe3ef5e6815560c98237d6216d1e5119702fb0f3894c8785dd58b8bbe5d73"
Image is the immutable multi-architecture PostgreSQL 17 integration image.
Variables ¶
This section is empty.
Functions ¶
func DockerReady ¶
DockerReady checks the declared Docker prerequisite with a five-second ceiling. It returns a setup error, never a skipped or successful gate.
func WithPasswordFile ¶
func WithPasswordFile(dir string, params database.ConnParams) (database.ConnParams, error)
WithPasswordFile writes params' password to a new mode-0600 file in the caller-owned dir, such as t.TempDir(), and returns params that reference the file instead, for tests of PasswordFile resolution. The caller removes dir.
Types ¶
type Database ¶
type Database struct {
// contains filtered or unexported fields
}
Database is one isolated database of a Fixture. PUBLIC holds no CONNECT, TEMPORARY or public-schema CREATE right in it, so only role pairs created here can use it. Close drops it and its role pairs.
func (*Database) AdminConfig ¶
func (d *Database) AdminConfig() *pgx.ConnConfig
AdminConfig returns an owned superuser connection snapshot for this database, for test-only provisioning and assertions. It must not be logged.
func (*Database) Close ¶
Close terminates sessions, drops the database and then its roles with a fresh 10-second budget, even after cancellation. A failed Close may be retried; after success, repeated calls return nil.
func (*Database) NewRolePair ¶
NewRolePair creates a fresh owner and runtime login within the 10-second budget. Passwords are random and stored as client-computed SCRAM-SHA-256 verifiers, so no plaintext password reaches the server.
type Fixture ¶
type Fixture struct {
Params database.ConnParams
// contains filtered or unexported fields
}
Fixture owns one isolated PostgreSQL container. Params carry ephemeral credentials and must not be logged or retained as evidence.
func Connect ¶
Connect attaches to an existing PostgreSQL server as a superuser within a ten-second budget. The fixture owns no container: Close drops only the databases and roles created through it and leaves the server running, so many test binaries can share one server. Params must name a superuser login and an existing maintenance database.
func Open ¶
Open returns a fixture on the shared server named by EnvAddr, or starts an owned container with Start when it is unset. A configured but unusable shared server is an error; Open never falls back to a container. TLS fixtures always start an owned container because they configure the server.
func Start ¶
Start requires a reachable Docker daemon, bounds provisioning to three minutes, and releases any partial container on failure. Each invocation owns a separate container and database.
func (*Fixture) AdminConfig ¶
func (f *Fixture) AdminConfig() (*pgx.ConnConfig, error)
AdminConfig returns an owned snapshot for isolated test administration, never production use. It preserves the fixture's verified connection settings and must not be logged.
func (*Fixture) Close ¶
Close closes every open Database, then terminates the owned container using a fresh thirty-second budget even when the caller is canceled. Every cleanup failure is returned. A failed termination is retried by the next Close; after termination succeeds, repeated calls return nil.
func (*Fixture) ContainerID ¶
ContainerID identifies the owned container for attachment to a caller-owned test network. It is empty after release. The fixture, not the network caller, owns container teardown.
type RolePair ¶
type RolePair struct {
Owner, Runtime database.ConnParams
}
RolePair is a fresh least-privilege login pair: Owner may create the schema and migrate it, Runtime may only connect. Neither has role attributes, TEMPORARY or membership in another role. Both carry ephemeral credentials that must not be logged or retained. The pair is dropped with its Database.
type RolePairConfig ¶
type RolePairConfig struct {
Schema string
}
RolePairConfig names the application schema both roles use as their search_path.
Source Files