Seed the Parent Branch, Not Every PR: Neon Branching Meets Seed Data

The core insight of Neon branching seed data is that you almost never need to seed a branch at all, so you seed the parent (usually main, dev, or a dedicated seed branch), and every branch created from it comes up populated.

# Seed the parent once, from your local machine or a manual CI job
seedfast connect
seedfast seed --scope "realistic e-commerce: 3 orgs, 200 users, 1,000 orders across 50 products"

Now the preview workflow has no seeding step at all:

# .github/workflows/preview.yml
name: Preview branch per PR

on:
  pull_request:

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Create Neon branch from main
        id: neon
        uses: neondatabase/create-branch-action@v6
        with:
          project_id: ${{ secrets.NEON_PROJECT_ID }}
          branch_name: preview/pr-${{ github.event.pull_request.number }}
          parent_branch: main
          database: ${{ secrets.NEON_DATABASE_NAME }}
          role: ${{ secrets.NEON_ROLE_NAME }}
          api_key: ${{ secrets.NEON_API_KEY }}

      - name: Run migrations on the new branch
        run: npx prisma migrate deploy
        env:
          DIRECT_URL: ${{ steps.neon.outputs.db_url }}

      - name: Run E2E tests
        run: npm run test:e2e
        env:
          DATABASE_URL: ${{ steps.neon.outputs.db_url_pooled }}

Specify the database and role inputs when your Neon project uses non-default names. Without them the action falls back to neondb / neondb_owner, and if those don't exist on your project, the output DSNs point at credentials Postgres will refuse to connect with, the kind of silent misconfiguration that shows up only when the test step runs. Otherwise there's no seed step at all, because the branch is already populated; a typical preview pipeline runs in the time it takes to deploy the app, and the database ends up being the cheap part of it.

This pattern works until either a PR introduces a migration that changes the schema in ways the inherited rows can't satisfy, or your security review forces schema-only branching. Both cases are the rest of this article.

A developer opens a PR that adds ALTER TABLE orders ADD COLUMN fulfillment_provider TEXT NOT NULL, the branch gets created from main, and the 1,000 inherited orders have no fulfillment_provider to satisfy it. The migration fails outright, or worse, it doesn't, because someone added a default, and now your tests are running against orders where every provider is the same literal string.

You don't want to reseed every branch (that defeats the O(1) advantage); you want to reseed only the branches where the inherited data no longer matches what the schema expects. A simple heuristic is "does this PR touch the migrations directory?"

# .github/workflows/preview.yml (excerpt)
      - name: Check if PR changes migrations
        id: migrations
        uses: tj-actions/changed-files@v46
        with:
          # Adjust the glob list to match your migrator. Cover every location
          # where schema changes can land — Prisma, Drizzle, raw SQL, Flyway,
          # Liquibase, custom folders. A missed path here means CI silently
          # runs against stale inherited data.
          files: |
            prisma/migrations/**
            drizzle/migrations/**
            db/migrations/**
            supabase/migrations/**
            **/*.sql

      - name: Run migrations on the new branch
        run: npx prisma migrate deploy
        env:
          DIRECT_URL: ${{ steps.neon.outputs.db_url }}

      - name: Reseed branch for schema-drift PRs
        if: steps.migrations.outputs.any_changed == 'true'
        run: npx seedfast seed --scope "e2e baseline: 3 orgs, 20 users, 100 orders" --output json
        env:
          SEEDFAST_API_KEY: ${{ secrets.SEEDFAST_API_KEY }}
          SEEDFAST_DSN: ${{ steps.neon.outputs.db_url }}

The reseed step only runs on branches that changed a migration file. The glob list above is the most brittle part of the workflow, because if your team commits migrations somewhere it doesn't cover, CI silently runs against stale inherited data and green builds can ship breaking schema changes. Treat the list as a contract with your migrator and update it whenever that surface changes. The Seedfast CLI flags used here (--scope, --output, SEEDFAST_API_KEY, SEEDFAST_DSN) are covered in the CI/CD database seeding docs. Seedfast has a 30-day free trial that covers small schemas end to end, so connect your Neon project and run the Pattern 2 step on a test PR before wiring it into the real workflow.

Two failure modes the glob heuristic does not catch: (a) business-logic PRs that need different data even though no schema changed, which need a manual reseed trigger on the parent branch; (b) schema changes that happen via side effects (e.g., a PR that runs a one-off SQL script from application code rather than a migration file). For (b), the only durable fix is "all schema changes go through the migrator," which is a team discipline issue, not a CI one.

This is the pattern where a static seed.sql stops working. The file describes the old schema, the one that existed in main, while the new branch's schema carries a new column, a new table, or a renamed foreign key the file knows nothing about. Nobody updates it until something breaks, and that job usually falls to whoever is trying to get their own PR to green. What separates reseeding-on-drift from rewriting the seed file inside the PR is that the generator adapts to the schema it finds at run time instead of assuming yesterday's shape. Why static seed files break covers the lifecycle in full; on Neon, the drift hits earlier because you feel every migration on every preview branch.

Schema-only branching is Neon's answer to "we can't copy that data to every PR." The parent database might hold records covered by a regulatory scope your team can't replicate to every developer's preview, or sensitive payment metadata that staging can't expose outside its access boundary; sometimes the dataset is simply too large to copy a hundred times a day regardless of what it contains. Schema-only branches inherit the structure (tables, columns, indexes, foreign keys) and nothing else. Seedfast itself generates synthetic rows and holds no compliance certification of its own; the fit here is that synthetic data replaces the copy, and whatever compliance posture your team already operates continues to apply.

That leaves you at an empty database with a real, complex schema in front of it, the seeding problem in its purest form.

The traditional answers are bad in this specific case:

• A committed seed.sql goes out of date the day after the next migration lands, and doubly so on a schema-only branch where no inherited rows mask the gap. See seed file maintenance for the full argument.
• A Prisma or Drizzle seed.ts does better than raw SQL, but it's still hand-written against a schema that keeps changing under it, so every new FK becomes a hand-edit.
• Copy-and-anonymize from production is the right answer for some teams, but it's heavy, since you end up running a full data pipeline just to fill a CI database.
• Faker libraries generate values but not relationships, so a 20-table schema becomes 20 one-table seed scripts with manual FK wiring, a pattern that stops scaling around table ten on any real schema.

Seedfast reads the branch's live schema on each run and generates rows that fit it, valid and connected, with FKs pointing at real parents. You describe the dataset in a plain-English scope:

# On the schema-only branch
export DIRECT_URL="postgresql://...ep-xxxx.region.aws.neon.tech/db?sslmode=require"

seedfast seed --scope \
  "small SaaS org: 2 workspaces, 15 members, 100 projects with 500 tasks and activity history"

There's no seed.sql and no seed.ts. The CLI connects, discovers what the last migration added, and generates valid, connected rows regardless. If the schema changes next week, the same command works next week. Self-referential tables (employees.manager_id → employees.id) and looped foreign-key chains are handled without any special-casing on your side.

The same binary that handles your parent-branch seed and your drift-reseed also handles schema-only. That's the reason most teams want one tool covering the full workflow instead of three different ones duct-taped together.

Seedfast is meant to coexist with the small set of deterministic fixtures most apps rely on, such as the admin@example.com account your Playwright login spec types, the feature-flag rows keyed by key, or the country-code lookup table. Keep those in a short fixtures.sql or a trimmed-down seed.ts and run them after seedfast seed. Seedfast fills the bulk relational data around them; your fixture file pins the specific records your tests expect by literal value. The two layers compose cleanly because Seedfast writes rows through the same Postgres connection your fixture script uses, so there's no tool-specific state to reconcile. Trying Seedfast against any Neon connection string is free for the first 30 days, and you can run your first seed in about two minutes.

Sometimes a branch gets polluted mid-test, whether a destructive migration runs, a test accidentally writes real data, or a developer just wants to start over. Neon supports resetting a child branch to its parent, a one-call operation via the API or dashboard that drops the branch's divergent writes and restores parent state.

# Restore a branch to the latest state of its parent (main)
curl --request POST \
  --url "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/restore" \
  --header "Authorization: Bearer $NEON_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"source_branch_id": "'"$PARENT_BRANCH_ID"'"}'

The reset takes about a second for the same reason branch creation does, since no data is copied, just a pointer update. That makes "reset to parent, rerun tests" a tight feedback loop when you're debugging flaky tests that might be polluting each other. Combined with Pattern 1 (parent already seeded), you get an instant clean environment every time.

One caveat is that reset-to-parent restores the branch's state to the parent's current state, which means if the parent has not had the PR's migration applied (it usually hasn't), the next CI run will re-apply the migration and overwrite whatever you reset to. The loop is "clean environment for test-data pollution," not "clean environment for migration rollback." For migration-drift branches in Pattern 2, the correct recovery is to delete and recreate the branch rather than reset, since reset will immediately be undone by the next prisma migrate deploy step.

If the parent itself is drifting out of shape (say, main has ten-month-old orders that don't reflect the current product schema), the fix is reseeding the parent, not resetting branches. seedfast seed is idempotent against a freshly-truncated schema, so the operational pattern is to truncate the target tables, then run seedfast seed with the current scope.

Neon bills compute seconds per branch, and a branch that runs a seed for the length of the seed is billing the whole time it runs. For a concrete team, the number depends on how long your seed actually takes: a short reference-data seed takes seconds, while a realistic-volume seed with FK chains takes minutes. What stays fixed is the shape of the bill. Seed every PR, and the line scales linearly with PR volume.

Seeding the parent once and letting branches inherit replaces that line with near-zero CI compute on most PRs. The parent-seed compute happens once after each schema change on main, usually as a scheduled job or a manual workflow dispatch, and it doesn't run for every PR that opens. Preview branches pay the compute cost of their actual tests, nothing more. If your team moves fast on migrations, "once after each schema change" still means a handful of parent reseeds per week, but each one replaces dozens of per-branch seeds that would otherwise run on every PR that opened during the same week.

When schema drift forces a reseed on a specific branch, you pay one seed's worth of compute for that one branch. That's the right bill; you asked the database to do work because the schema changed. The only real waste is paying for that seed on every PR, including the 90% that never touched migrations, and the parent-once pattern is what eliminates that line entirely.

Neon branch caps. Every Neon plan has a branch limit (Free plans are tighter than paid), and PRs that sit open for weeks quietly accumulate branches against it. The delete-branch-action on pull_request: closed is required, not optional, because skipping it means you'll hit the cap mid-PR while the preview workflow fails at branch creation.

Parallel test isolation. If you run Jest or Playwright in parallel and all workers hit the same preview branch, they race for the same rows. For true isolation, create one branch per worker at the start of the test run and delete them at the end. Six workers with one-second branch creation add up to six seconds of overhead, which is vastly cheaper than running six separate seeded databases.

Pooled vs unpooled for seeding. The parent-seed and drift-reseed jobs need the unpooled connection string, because PgBouncer in transaction mode breaks prepared statements and can time out on large seeds, while the app under test uses the pooled string instead. This is the same rule as non-branching Neon seeding; the Neon seeding guide covers the connection-string mechanics in detail.

Auto-suspend mid-seed. Neon computes suspend after an inactivity window; the default is 5 minutes on all plans, and the Free plan cannot disable it. A seed that pauses between large batches can have its connection closed underneath it, surfacing as server closed the connection unexpectedly or a generic TCP reset. Paid plans can raise the suspend delay for the seed branch; Free-plan users need the seed to run continuously without long inter-batch pauses. seedfast seed runs one continuous session, so this mainly bites hand-rolled scripts that batch-and-wait.

Stale parent. The parent-seed pattern assumes the parent's data still reflects the current schema. When a migration lands on main, either (a) run the migration against the parent branch's compute and re-run the parent seed to regenerate rows that fit, or (b) accept that the parent will drift and rely on Pattern 2 (drift-reseed on every PR that touches migrations). Most teams pick (a) as a post-merge job on main.

For the practical setup, the article covers three workflows and picks between them based on the PR:

All three use the same seedfast binary with different scope strings; the difference is when you invoke it, not how. That's the operational simplification that makes Neon branching seed data manageable at team scale, one binary and one mental model standing in for what used to be three separate tools.

• How to seed a Neon database, covering the three seeding methods (raw SQL, ORM, schema-aware) this article builds on, including connection-string gotchas and per-error fixes
• How to seed a Supabase database, the Supabase counterpart covering seed.sql, supabase db reset, auth.users, and Supabase preview branches (separate-DB-per-branch model, not CoW)
• Seed file maintenance, on why static seed.sql and hand-written seed.ts drift from the schema, and how that drift shows up faster on Neon preview branches
• Database seeding in CI/CD, the framework for idempotent, fast, FK-valid seeding in a pipeline, applied to any Postgres (Neon-specific here; this covers the general case)
• Database seeder tools and per-ORM reference, comparing Laravel, Prisma, Drizzle, EF Core, and TypeORM seeders side-by-side
• Get started with Seedfast, to connect the CLI to your Neon project and run the three patterns in under five minutes