Documentation
¶
Overview ¶
Package pgtest provides a REAL ephemeral postgres for generate-time schema introspection and for hermetic tests that need a database.
Why real postgres ¶
forge is postgres-pinned. The schema a project's migrations declare — schema-qualified DDL (CREATE TABLE controlplane.foo), postgres-only types (TIMESTAMPTZ, JSONB, TEXT[], BIGSERIAL), '::type' casts, multi-ADD ALTERs, generated/identity columns — only round-trips faithfully on real postgres. The previous in-memory SQLite "shadow" approximated this and froze the ORM the moment a project used a construct SQLite couldn't parse (the controlplane.-schema bug). Real postgres needs no normalization: migrations apply verbatim.
The shared instance ¶
Booting postgres is expensive, so this package boots ONE server per process (sync.Once) and hands every caller its own freshly-created, uniquely-named database on that server. Databases are cheap; the server boot is the cost, paid once. This mirrors how the e2e corpus builds the forge binary once via sync.Once and runs fixtures in parallel against it.
By default the server is an embedded-postgres binary (github.com/fergusstrange/embedded-postgres) — a real postgres downloaded and cached under the user cache dir on first use, no Docker required. Set FORGE_TEST_POSTGRES_URL to a base postgres DSN (postgres://user:pass@host:port/postgres?sslmode=disable) to point at an already-running server instead (a dev docker-compose, CI service container, or a detected local postgres) and skip the embedded boot.
Index ¶
Constants ¶
const EnvBaseURL = "FORGE_TEST_POSTGRES_URL"
EnvBaseURL names the env var that, when set, points pgtest at an already-running postgres instead of booting embedded-postgres. The value is a base DSN whose database is "postgres" (the maintenance DB pgtest connects to in order to CREATE DATABASE).
Variables ¶
This section is empty.
Functions ¶
func New ¶
New creates a fresh, uniquely-named, empty database on the shared server and returns an open *sql.DB connected to it plus a cleanup function that closes the connection and drops the database. The first call boots the shared server (embedded download on the very first run of a new machine).
Callers own the returned cleanup; tests typically defer it or register it with t.Cleanup. The connection is configured for postgres (database/sql driver "postgres").
func NewURL ¶
NewURL creates a fresh, uniquely-named, empty database on the shared server like New, but returns its connection DSN (a postgres:// URL) instead of an open *sql.DB. Use this when the consumer is a separate process that connects itself via DATABASE_URL — e.g. an e2e test that boots a generated server. The returned cleanup drops the database; the caller must not hold connections past it.
Types ¶
This section is empty.
Source Files