Documentation
¶
Overview ¶
Package shadowdb resolves WHICH postgres server hosts the generate-time schema-introspection shadow database.
Why this layer exists ¶
forge derives ORM/CRUD code by applying a project's migrations to a throwaway "shadow" postgres and introspecting the live schema (pkg/schemadef). That needs a server. Historically the ONLY way to use a real running server instead of a fragile embedded one was the FORGE_TEST_POSTGRES_URL env var — a TEST-suite variable that leaked into being the production codegen config channel. Because it lived OUTSIDE forge's config system it silently diverged between steps, and because it was the only non-embedded path, embedded became the accidental default — which on a shared/resource-starved machine leaks SysV semaphores and fails initdb.
This package moves the "which server" DECISION into forge's own environment/config layer. schemadef and pkg/pgtest stay dumb mechanics: pgtest knows how to make an ephemeral database (embedded, or a scratch DB on a given server URL); schemadef applies migrations and introspects against whatever database it is handed. The POLICY of which server to use, and whether one is reachable at all, lives here.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Resolve ¶
Resolve returns the base DSN of a REACHABLE postgres SERVER to host the generate-time shadow database, or "" when none is available — in which case the caller falls back to embedded postgres (true zero-setup / CI).
projectDir is the directory containing forge.yaml.
Resolution order — first usable candidate wins:
FORGE_TEST_POSTGRES_URL — the explicit override / escape hatch. It is honored as-is WITHOUT a reachability probe: an override that is set but wrong must fail loudly downstream (a hard CREATE DATABASE error), not silently fall back to embedded and hide the misconfiguration. forge's own e2e suite sets this to share one server across the parallel corpus, so this path must keep working unchanged.
an exported DATABASE_URL — a dev shell that already points at the running stack.
the project's per-env SECRET dotenv (`.env.<env>` DATABASE_URL) — the dev DB the app itself dials. A scaffolded project marks database_url `sensitive`, so its VALUE lives here (gitignored) and the git-tracked config.k carries only the Secret reference.
the project's per-env config (deploy/kcl/<env>/config.k `database_url`) — the same DB, for a project that did NOT mark the field sensitive.
the forge dev-stack convention — localhost:${POSTGRES_PORT:-5432} with ${POSTGRES_USER:-postgres}/${POSTGRES_PASSWORD:-postgres}, the SAME host coordinates the scaffold's docker-compose maps postgres to.
Candidates 2–5 are reduced to their SERVER coordinates against the maintenance database "postgres" and PROBED (pgtest.CanReach) before being returned, so the app's own database is never opened or mutated, and a candidate that is down or has wrong credentials is skipped rather than turned into a hard error. When none is reachable, "" is returned and the caller uses embedded postgres.
Note on the scaffold phase: at `forge new` / one-shot scaffold time the project's own dev DB is typically NOT up yet, so candidates 3–4 will not probe. Candidate 5 still lets a developer whose machine already runs a shared dev postgres at the conventional coordinates use it; otherwise the resolver returns "" and embedded is used — no configuration required.
Types ¶
This section is empty.
Source Files