Neon schema-only branches: test migrations without real data

Not specified by the original author.

Neon schema-only branches: test migrations without real data

TL;DR

The standard advice for testing a migration is "branch prod and run it there." That puts a full copy of production data, PII included, in a branch that developers poke at. For migration testing you do not need the data at all; you need the schema. Neon supports schema-only branches: the branch carries the schema but no table data.

Use this when you run into the situation in the title.

Steps

1. Create the branch as schema-only from the Console (or via the API's schema-only option).

   Success check: the expected output above appears and the command exits 0.

2. Run your migration against it.

   Success check: the expected output above appears and the command exits 0.

3. Verify the resulting schema with a diff against your expectation.

4. Delete the branch; it was cheap and disposable by design.

   Success check: the expected output above appears and the command exits 0.

Compatibility

Tool: Neon. The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.

Details

Schema-only branches for migration testing

The trap

The rule

Use them when the goal is testing migrations or building new test data, not debugging production rows.

When not to use it

Debugging a data-dependent bug needs real rows; use a normal branch there (and consider anonymization for PII). Load testing needs representative volume; schema-only gives you none.

Checklist

• Migration CI jobs: schema-only branch, run migrate, diff, delete.
• Never put production PII in a branch just to test DDL.
• Pair with branch expiration so failed CI runs do not accumulate.

Neon branch management docs (verified live 2026-09-26) document schema-only branches as useful for testing migrations or building new test data without exposing sensitive real-world data.