Documentation
¶
Overview ¶
Package pgtest provides a shared real-Postgres test harness usable from any package in the module (core/migrate, cmd/gofastr, …) without importing framework/internal/testdb, which is import-restricted to the framework tree.
Resolution (memoised once per process):
- TEST_POSTGRES_DSN env var — CI's `pgvector/pgvector:pg16` service sets it; locally, `make postgres-up` starts the docker-compose service (same image) and `make test-pg` exports the matching DSN.
- unset → t.Skip locally; under CI (PGTEST_REQUIRED=1 or GITHUB_ACTIONS=true) escalate to t.Fatal so the ~30 real-PG suites can't silently degrade to SQLite-only behind a green build.
This used to spawn postgres:16-alpine through testcontainers-go when the env var was unset. Convenient, but testcontainers had to be a require in the root go.mod, and Go hands a module's requirements to everything that imports it — so every application built on GoFastr resolved the Docker client stack to run `go mod tidy` on a hello-world. A build tag would not have helped: tidy walks every build configuration. The env var was already the preferred path and the documented one for CI, so the container branch was removed rather than hidden.
Each DB(t) hands back a connection scoped to a unique schema (search_path), so concurrent tests don't collide, with cleanup registered on t.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BaseDSN ¶
BaseDSN returns the resolved base DSN (the maintenance/default database). When Postgres is unreachable it skips locally but fails the test under CI (see required); this is the single choke point every pgtest entry point (DB, FreshDatabaseDSN, UnusedDSN) flows through. Use BaseDSN directly for EnsureDatabase / CLI round-trips that need a raw connection string.
func DB ¶
DB returns a *sql.DB scoped to a fresh, uniquely-named schema (via search_path) on the shared Postgres, or skips if Postgres is unreachable. The schema and connection are dropped/closed on t.Cleanup.
func FreshDatabaseDSN ¶
FreshDatabaseDSN creates a uniquely-named database on the shared Postgres and returns a URL DSN pointing at it, dropped on t.Cleanup. Use for CLI / tooling tests that connect by URL string and expect to own the database (vs DB(t), which schema-scopes a shared one). Skips if Postgres is unreachable, or if the base DSN isn't URL-form.
func UnusedDSN ¶
UnusedDSN returns a URL DSN pointing at a uniquely-named database that does NOT yet exist, plus a cleanup that drops it if something created it. Use to test database-creation paths (EnsureDatabase / migrate up --create-db). Skips if Postgres is unreachable or the base DSN isn't URL-form.
Types ¶
This section is empty.
Source Files