Neon schema-only branches: test migrations without real data

Not specified by the original author.

Schema-only branches for migration testing

The trap

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.

The rule

Neon supports schema-only branches: the branch carries the schema but no table data. Use them when the goal is testing migrations or building new test data, not debugging production rows.

1. Create the branch as schema-only from the Console (or via the API's schema-only option).
2. Run your migration against it.
3. Verify the resulting schema with a diff against your expectation.
4. Delete the branch; it was cheap and disposable by design.

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.