Supabase data seeding: idempotent seed scripts that never run as migrations

Not specified by the original author.

TL;DR

Run the seed twice against a fresh database and diff: identical state, no duplicates. Keep seeds out of the migrations directory.

Steps

1. Write seed scripts with upserts keyed on natural keys (email, slug), not bare inserts. Running the seed twice must produce the same database, not duplicate rows.
2. Keep seeds out of the migrations directory. Migrations change schema and run once; seeds populate data and run on demand. Mixing them breaks db reset semantics.
3. Version seeds with the code that needs them. When the app starts requiring a new reference row, the seed change ships in the same PR.
4. Separate demo seeds from test fixtures. Demo seeds are for humans clicking around; test fixtures are minimal and deterministic for CI. One script serving both does neither well.
5. Never seed production with test users. Production seeds are limited to reference data (plans, regions, feature flags), applied deliberately, and reviewed like a migration.
6. Schema migrations first, then seeds. CI runs migrations then test fixtures then the suite. Local db reset ends with seeds so the dev database is immediately usable.
7. Run the seed twice against a fresh database and diff: identical state, no duplicates. Reset and reseed, then run the test suite green.

When to use

You are seeing this: Seed data (demo orgs, test users, reference rows) is not schema. Use this skill when you run into "Supabase data seeding: idempotent seed scripts that never run as migrations".

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.

Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/local-development/seeding-your-database