Skip to content

feat(seed): add local fake database seeding script

title: "feat(seed): add local fake database seeding script"

🚀 Feature Request

Is your feature request related to a problem? Please describe.

There is currently no simple, repeatable way to populate the backend with a small local development dataset. Developers have to create test data manually, which slows down testing for phone/password login, user flows, record endpoints, categories, points, and record history/version features.

Describe the solution you'd like

Add a dedicated local database seed script for the backend that creates a small deterministic dataset.

The script should:

  • create 1 fake user with valid required fields
  • hash the password using the existing auth utility
  • assign the default user role
  • create a few sample records linked to that user
  • attach existing seeded categories to those records
  • create matching points events
  • create basic record history/version data for at least one record
  • support clearing and reseeding the seeded dataset with a --clear option
  • support Docker-based execution for local development

Suggested usage:

uv run python scripts/seed_database.py

uv run python scripts/seed_database.py --clear

uv run python -m scripts.seed_database

docker compose exec app uv run python -m scripts.seed_database

Describe alternatives you've considered

  • Creating test data manually through the API
  • Inserting rows directly into PostgreSQL
  • Expanding the existing DB initialization flow to always create fake users and records

These approaches are either slower, less repeatable, or too intrusive for normal project setup. A dedicated optional seed script keeps local testing simple without changing the default workflow.

Additional context

The seeded dataset should remain small and deterministic for easy reuse in development.

Suggested seeded data:

  • 1 fake user
  • 4 sample records across different media types
  • existing categories reused
  • points events for seeded records
  • one record with extracted text
  • one record with history/version metadata

Seeded login should use the backend’s existing phone/password login flow.

Edited by Kushal Lagichetty