pipework 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.30.0
+
+- **Test setup narrates its steps, and its own bound is on progress rather than on a wall clock.** `setupTestDatabases()` was a single awaited call: a consumer's `beforeAll` had nothing to log while it ran, and nothing to say when it did not finish. Under a width-40 start burst, a setup that was merely queued behind its peer forks — advancing the whole time — was killed by vitest's 60 s hook timeout and reported as `Hook timed out in 60000ms` with no test assertion attached, a reading about the host rather than about the suite. `setupTestDatabases(instance, { onProgress })` now reports every step it reaches: `rls-probe`, `run-prepare`, `template-pin`, `template-wait` (once per poll while a peer builds), `template-build`, `template-migrate` (once per migration file), `template-ready`, `queue-check`, `clone-start`, `clone-done`, `ready`. Each report names the phase, the database it is about, the total elapsed time, and the phase it displaced with how long that held — so a caller can log the steps, or time them, without parsing prose. Setup also bounds itself now, and the bound is on PHASE ADVANCE, not on total elapsed time: a setup that keeps reaching steps finishes late and green however long the whole thing takes, while one that stops advancing for `test.setupStallMs` (default 120 s) fails as `SetupStalled`, naming the last phase reached, the database, how long it has been stuck, and the total elapsed. The default setup file installs a listener that stays silent while setup is quick and writes one `pipework:test-setup slow phase=… db=… held_ms=… next=… elapsed_ms=…` line per phase that held 10 s or longer — so a healthy run gains no output and a late one explains itself. `applyMigrations()` takes a matching `onMigration` callback, which is what keeps a long migration replay from looking like a stall. Existing callers are unaffected: the options argument is optional and setup's behavior without it is unchanged.
+
+## 0.29.0
+
+- **New: `closeSetupConnections()` lets a consumer close the harness's setup connections before their own `afterAll` looks at the database.** The connections `useSetupDb()` opens are closed by `setupPipeworkTests`' own `afterAll`, and under vitest's `sequence.hooks: 'stack'` that hook runs *after* every setupFile `afterAll` — so a teardown-time observer sampling `pg_stat_activity` to name leaked backends saw every setup connection still open and could not tell them from a real leak. The internal `_closeSetupConnections` was not reachable through the `pipework/test` entry, leaving copying `useSetupDb` app-side purely to win the hook order as the only way out. `closeSetupConnections()` is now exported from `pipework/test`: close first, then sample, and what remains is a true survivor set. It is idempotent, a connection that throws on close is still tolerated, and calling it early does not disturb the harness's own teardown — the pool still closes and the databases still drop afterwards. A later `useSetupDb()` opens a fresh connection. Hook order is unchanged for everyone else.
+
 ## 0.28.0
 
 - **Fix: a queue column of the wrong type or nullability is caught at startup, not by a fence that silently never matches.** 0.27.0 made the queue check compare column names, so a table missing `claim_token` fails loudly. A column can still be present under the right name and be the wrong column: `ALTER COLUMN ... SET DATA TYPE` and `DROP NOT NULL` are migration steps a consumer can skip exactly as they can skip an `ADD COLUMN`, and the result is quieter than a missing column — `claim_token` as `text` compares wrong against a `uuid` rather than erroring, so a fence built on it never matches and nothing says why. The check now compares each required column's type and nullability too, and reports a drifted column the way it reports a missing one: which table, which database, which column, what the definition requires, what the database has, and the generate-then-migrate cure. What counts as compatible is deliberate. Type is canonical identity rather than spelling — the definition's declared type is resolved through Postgres's own `to_regtype` and the OID compared, so `timestamptz` and `timestamp with time zone` agree without a hand-maintained alias table. Length and precision are ignored: `varchar(64)` against `varchar(128)` is not drift, because a check that reports false drift on a healthy table gets switched off. Nullability is reported in one direction only — nullable where the definition requires NOT NULL breaks a promise the definition makes; stricter than the definition asks cannot, and may be deliberate. Defaults are not compared. Still two queries whatever the number of queues, and still read from `pg_attribute`, so an unprivileged role is not told to migrate when the cure is a GRANT. Note this is newly blocking on upgrade: a consumer whose queue table has drifted starts on 0.27.x and gets a startup refusal on 0.28.0 — that is the point of the check, and the cure it names is `pipework generate` then `pipework migrate`.