Documentation
¶
Overview ¶
Package pgtest provides ephemeral, per-test PostgreSQL schemas for tests that run against any real database, including CI service containers. Each call to New creates a randomly named schema, points a fresh connection pool's search_path at it, and registers cleanup that drops the schema and closes the pool once the test finishes, so tests can run concurrently (even across packages, even against the same shared database) without stepping on each other's tables.
ConnString reads the server to test against from the PG_CONNSTRING environment variable and skips the calling test when it is unset. Unlike the pg package's own test suite, which falls back to a hardcoded local connection string so its CI job has a default to run against, pgtest has no such fallback: it is meant to be imported by downstream projects' test suites too, where a hardcoded host, user and password would be meaningless (or worse, silently wrong). A missing PG_CONNSTRING therefore means "skip", not "guess".
Usage ¶
func TestSomething(t *testing.T) {
connString := pgtest.ConnString(t)
schema := pg.NewSchema()
schema.MustRegister("widgets", Widget{})
db := pgtest.New(t, schema, connString)
repo := pg.NewRepository[Widget](db)
// ... use repo/db; the schema is dropped automatically on test completion.
}
Build the *pg.Schema fresh inside each test, as above, rather than sharing one across tests. New mutates the Schema's registered tables in place (see New's doc), so passing the same *pg.Schema to two overlapping New calls is an unsynchronized concurrent write to shared state: a genuine data race that "go test -race" will flag, not just a source of occasional flaky assertions. New detects the overlap and fails the second call fast instead of letting it race silently, but the fix is still to give each New call its own Schema.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConnString ¶
ConnString returns the connection string to test against, read from the PG_CONNSTRING environment variable. If it is unset or empty, ConnString skips the calling test with an explanatory message instead of falling back to a default: see the package doc for why.
func New ¶
New opens a *pg.DB against connString whose search_path is a freshly created, randomly named schema (pgtest_<16 hex chars>) private to the calling test, and registers a tb.Cleanup function that drops the schema (CASCADE, so any table created inside it goes too) and closes the connection pool once the test (or, called from inside t.Run, the subtest) finishes.
If schema has any tables registered, New also calls DB.CreateSchema to materialize them inside the new schema before returning, so the caller can start using pg.Repository right away. An empty schema (pg.NewSchema(), nothing registered) is fine too: New still creates and cleans up the isolated schema, leaving table creation to the caller.
New also repoints every table registered on schema at the new schema name (see the SearchPath comment in New's body for why that is necessary for Insert/Upsert to work at all). Because schema.Tables() returns the Schema's own live *desc.Table pointers rather than copies, doing that from two overlapping New calls sharing one Schema would be an unsynchronized write to the same memory from two goroutines: a genuine data race (the kind "go test -race" reports), not just a logical mix-up. New refuses to let that happen: a second New call given a *pg.Schema that an earlier, still-active New call already holds fails immediately via tb.Fatalf instead of racing. Build a fresh *pg.Schema per call to New instead of sharing one across concurrent tests; registering the same struct types on it repeatedly is cheap.
Every setup step (parsing connString, opening the pool, creating the schema, creating its tables) fails the test immediately via tb.Fatalf on error. Once the schema itself has been created, cleanup is registered before anything else can fail, so a later failure (such as CreateSchema rejecting one of schema's tables) still drops the schema instead of leaking it.
Types ¶
This section is empty.