Workflow: ephemeral database per CI run

TL;DR

Run migrations (direct string), then the test suite. 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.
5. - 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.

3. - 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.

When to use

You are seeing this: At the start of the CI job, create a branch from the main branch via the Neon API with 1-hour expiration. Use this skill when you run into "Workflow: ephemeral database per CI run".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

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.