Workflow: ephemeral database per CI run

Workflow: ephemeral database per CI run

Goal

Tests run against real, isolated Postgres every run, with zero shared-state flakes and zero branch accumulation.

Steps

1. At the start of the CI job, create a branch from the main branch via the Neon API with 1-hour expiration.
2. Poll the branch operation to finished; read the connection string.
3. Run migrations (direct string), then the test suite.
4. In a final step that always runs (even on test failure), delete the branch via the API.

Ordering constraints

• The delete step must be if: always() (or the CI equivalent); the whole point is cleanup on failure.
• Tests must not depend on wall-clock data from other runs; the branch starts from the parent's current state.

Traps

• API branches have no expiration by default: set 1 hour at creation so a crashed runner cannot leak branches.
• Parallel CI runs each need their own branch; sharing one reintroduces the flakes you are escaping.
• Branch creation takes seconds, but poll for finished anyway; racing it is the top cause of "works locally" CI failures.

Verify

A week of CI runs leaves zero leftover branches in the Console; test flakiness from shared DB state disappears.

Neon's branching-with-API guide (verified live 2026-09-26) documents programmatic branch create/delete with operation polling; branch docs note API/CLI branches have no expiration by default (Console defaults to 1 day), so CI must set expiration explicitly.