seed-data

Seed Data Patterns

Thesis: Seed data uses stable UUIDs, idempotent upserts, and realistic content. Every new migration gets seed data immediately.

Reference files: dev_seed.sql

UUID Convention

Use stable, predictable UUIDs for cross-referencing:

-- Entity type encoded in the UUID for readability
-- users:     a0000000-0000-0000-0000-00000000000N
-- resources: a0000000-0000-0000-0000-0000000000N0
-- items:     a0000000-0000-0000-0000-000000000N00

Document the UUID mapping at the top of the file so they're easy to find.

Idempotency

Every INSERT must use ON CONFLICT ... DO UPDATE or ON CONFLICT ... DO NOTHING so the seed can be re-run safely:

INSERT INTO users (id, email, ...) VALUES (...)
ON CONFLICT (email) DO UPDATE SET
  registration_step = EXCLUDED.registration_step,
  email_verified = EXCLUDED.email_verified;

Rollback Validation

Before committing seed or migration-backed seed work, validate against a real Postgres database inside a rollback transaction. This catches FK ordering, enum, trigger, uniqueness, and idempotency bugs that schema reading misses, while leaving local/dev data untouched.

psql "$DATABASE_URL" -v ON_ERROR_STOP=1 \
  -c 'BEGIN;' \
  -f backend/migrations/000NNN_new_table.up.sql \
  -f backend/seeds/demo_seed.sql \
  -c "SELECT count(*) FROM expected_table;" \
  -c 'ROLLBACK;'

For seed-only changes, omit the migration file. Always assert at least one business-relevant count or state, not just "script exited 0".

Data Quality

• Realistic content — real-sounding names, descriptions, skills. Not "test123" or "Lorem ipsum".
• All profile fields populated — except file-based fields (resume_url, microview_url, etc.) which require actual uploads.
• Varied statuses — seed entities in different states (new, in_progress, complete, approved) to test all UI states.
• Realistic timestamps — use NOW() - INTERVAL 'N days' for created/updated dates to simulate a timeline.
• Minimum viable depth — seed the thinnest realistic slice first, then let demo/customer feedback decide whether more rows are worth authoring. One honest review per hero can be enough for v1 if the gap is explicit and easy to extend later.