home / skills / andrelandgraf / fullstackrecipes / neon-test-branches

neon-test-branches skill

safe

This skill helps you provision isolated Neon test branches with schema-only structure, auto-cleanup TTL, and environment orchestration for safe testing.

npx playbooks add skill andrelandgraf/fullstackrecipes --skill neon-test-branches

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

551 B

---
name: neon-test-branches
description: Create isolated Neon database branches for testing. Schema-only branches with auto-cleanup via TTL, test server orchestration, and environment variable management.
---

# Neon Test Branches

To set up Neon Test Branches, refer to the fullstackrecipes MCP server resource:

**Resource URI:** `recipe://fullstackrecipes.com/neon-test-branches`

If the MCP server is not configured, fetch the recipe directly:

```bash
curl -H "Accept: text/plain" https://fullstackrecipes.com/api/recipes/neon-test-branches
```

Overview

This skill creates isolated Neon database branches for running tests and ephemeral environments. It provisions schema-only branches with automatic cleanup using a TTL, manages environment variables, and coordinates test server lifecycle. Designed for fast, repeatable test runs and CI workflows that need disposable database state.

How this skill works

The skill uses Neon branches that contain only schema, not data, so tests start from a known structure. Each branch gets a TTL after which it is auto-deleted to avoid resource buildup. It also orchestrates a short-lived test server and injects the correct environment variables so test suites connect to the matching branch. Integrations can be triggered from CI or local test runners.

When to use it

Running integration tests that require a clean database schema per run.
Creating ephemeral environments for feature previews or QA sessions.
CI pipelines that need parallel isolated databases to avoid conflicts.
Local development when you want a disposable database state without manual cleanup.
Automated end-to-end tests that require predictable schema migrations.

Best practices

Use short TTLs appropriate to your test duration to minimize orphaned branches.
Provision schema-only branches to avoid copying production data and reduce costs.
Rotate environment variables or secrets per branch to prevent accidental cross-use.
Integrate branch creation and cleanup into CI jobs to ensure deterministic runs.
Monitor branch counts and TTL expirations to catch configuration issues early.

Example use cases

CI job creates a Neon branch, runs migrations, spins up a test server, executes tests, and lets TTL auto-clean the branch.
A pull request preview site uses a branch-per-PR so QA can test against the exact schema for that change.
Parallel test matrix where each worker receives its own Neon branch to avoid contention.
Local developer script that creates a short-lived branch for manual testing of DB migrations.

FAQ

Does the branch copy production data?

No. Branches are schema-only by default to avoid copying production data and to speed up creation.

How are branches cleaned up?

Each branch is created with a TTL. After the TTL expires the branch is automatically deleted to prevent orphaned resources.

Can this be used in CI?

Yes. It is designed for CI workflows and supports orchestration of test servers and environment variable injection for automated jobs.