pipework 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.31.0
+
+- **A finished test file no longer waits out a cluster-wide checkpoint to drop its database.** `CREATE DATABASE ... WITH TEMPLATE` was suspected of forcing checkpoints; it does not. Since PG15 its default strategy is `WAL_LOG`, which needs no checkpoint, and pipework issues no `STRATEGY` clause — measured on PG17, forty clones force zero. Every `DROP DATABASE` forces one: Postgres's own `dropdb()` calls `RequestCheckpoint(CHECKPOINT_IMMEDIATE | FORCE | WAIT)`, so the dropping backend blocks until the whole dirty cluster is synced. Teardown dropped one database per test file, which put that wait inside every `afterAll`; on a saturated cluster single checkpoints were measured at 47.1 s / 28.6 s / 24.4 s, which is a teardown hook timing out on a run that leaked nothing. Teardown now terminates the file's backends and **queues** the database instead of dropping it. The queue is emptied when it reaches `test.dropBatchSize` (default 8) and again at worker shutdown, so one teardown in eight pays the wait rather than all of them, and the rest of a worker's drops settle after its files are done instead of in the middle of a wide start burst. The number of checkpoints is fixed by the number of databases and batching does not change it — what changes is which hook is standing there waiting. Each flush logs one `pipework:test-drop <batch|shutdown> queued=… dropped=… elapsed_ms=…` line, so what the drops cost is a number rather than an inference. Two supporting changes: a clone's name now carries a per-clone sequence number (`<project>_test_app_3_<pid>_<nonce>`) so the next file in a worker never asks for a name still queued for drop, and the create path's own `DROP DATABASE IF EXISTS` is gone — with unique names it could only ever be a no-op, and a non-no-op would have been a checkpoint on the create path too. Nothing leaks: a worker killed with drops still queued loses its run lock with its connection, and the next run's reaper drops them exactly as it always has. `flushPendingDrops()` is exported from `pipework/test` for a consumer whose own teardown wants the queue settled before it looks at `pg_database`. Set `test.dropBatchSize: 1` to restore the drop-per-file behaviour.
+
+## 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.