Documentation
¶
Overview ¶
Package dbtest provides shared setup for the Postgres-gated ("*_db_test.go") suites that CI runs together in the db-tests lane (.github/workflows/ci.yml) against ONE shared database.
Those suites compile into separate per-package test binaries that `go test` runs as parallel processes, all pointed at the same MEMQL_DATABASE_DSN. Only one of them (examples/referencepack) ever migrated the blank service DB; the others (component/memql, component/automations/ steps) opened a connection and read/wrote the MemoryNodes table assuming the schema already existed. With no coordination the two classes raced: when a reader reached its first DB op before referencepack's migration finished, it failed with `relation "MemoryNodes" does not exist`, or -- if the initial CREATE had landed but a later migration had not -- a half-applied `column ... does not exist`. That intermittently red the required db-tests lane and poisoned the merge queue (memql#2551).
EnsureSchema closes the gap: every db-gated package calls it from TestMain, so the schema is fully migrated before any test in any package touches it. A blocking, cross-process advisory lock serializes the migration so the first process migrates while the rest wait, then observe the applied migrations and return -- the non-idempotent (column-rename) migrations can never run concurrently.
A SECOND lock sits underneath, and the advisory lock does not cover it. The production migrator (component/database) takes bun's lock row in bun_migration_locks on every Database.Start -- including the db-gated tests that boot their own memory-nodes database mid-run (component/grpc, the pack live-e2e suites), which never see the advisory lock. bun's Lock is a TRY-lock, so a TestMain that reached it inside one of those windows used to fail its whole package in 0.1s with "migrations table is already locked". EnsureSchema now waits that holder out (bounded, with backoff) and retries, still under the advisory lock, so the first process still migrates and the rest still only observe. See migrateWaitingOutForeignLock for why taking the bun lock inside the advisory lock would not have closed it.
Index ¶
Constants ¶
const AllowBootstrappedDBEnv = "MEMQL_ALLOW_BOOTSTRAPPED_DB"
AllowBootstrappedDBEnv opts a run back in to a database that belongs to a bootstrapped cluster. Deliberately explicit and deliberately separate from MEMQL_REQUIRE_DB: "I want a database" and "I accept writing into a live cluster's data" are different statements.
const RequireDBEnv = "MEMQL_REQUIRE_DB"
RequireDBEnv is the opt-in that turns db-gated skips into failures.
Variables ¶
This section is empty.
Functions ¶
func DSN ¶
func DSN() string
DSN returns the database DSN the db-gated suites target: the MEMQL_DATABASE_DSN environment value, or the shared default.
func EnsureSchema ¶
EnsureSchema migrates the shared test database to the current schema, serialized across processes so the parallel db-gated package test binaries never race on a half-created schema (memql#2551). It is idempotent: the first process to acquire the advisory lock migrates; every other process blocks on the lock, then observes the applied migrations and returns. When bun's own migration lock row is held by a migrator outside the advisory lock (a sibling package's test starting its own database), it waits that holder out rather than failing the package; a row still held after migrationLockWait is reported as stranded.
It reports reachable=false (err=nil) when no Postgres is reachable, so the caller can proceed to m.Run() and let the individual tests self-skip -- preserving the green-by-skip behaviour on a DB-less CI lane.
It never publishes a DSN it has not connected to. See ensureSchema.
func RequireDB ¶
func RequireDB() bool
RequireDB reports whether MEMQL_REQUIRE_DB demands a reachable database.
func SafeDSN ¶
SafeDSN redacts the password in a DSN so it can appear in test output. Returns the input unchanged when it carries no credentials.
func Unreachable ¶
Unreachable is the single decision point for a db-gated test whose ping failed: it FAILS the test when MEMQL_REQUIRE_DB is set, and otherwise skips with a message naming the redacted DSN and the underlying error -- so an authentication failure reads as one instead of looking like an absent database. purpose describes the suite ("accountDeletionSweep acceptance").
Types ¶
This section is empty.