supabase-seeding

# Supabase Database Seeding

Toolkit for populating Supabase databases with seed data.

**Helper Scripts Available** (uv scripts - no install needed):
- `scripts/run_seeds.py` - Run seed files with progress monitoring
- `scripts/generate_seed.py` - Generate seed data from schema (uses Faker)

**Always run scripts with `--help` first** to see usage:
```bash
uv run scripts/run_seeds.py --help
uv run scripts/generate_seed.py --help
```

## Decision Tree: Seeding Approach

```
Task → What type of data?
    ├─ Lookup tables (categories, statuses, roles)
    │   └─ Write INSERT with ON CONFLICT DO NOTHING
    │
    ├─ Test/dev data (<1000 rows)
    │   └─ Write INSERT statements in seed file
    │
    ├─ Large dataset (>1000 rows)
    │   └─ Use COPY from CSV
    │       └─ File >1MB? Track with DVC
    │
    └─ Generated data (users, transactions)
        └─ Run: uv run scripts/generate_seed.py --help
```

## Directory Structure

```
supabase/
├── migrations/          # Schema only (DDL) - NO INSERTs
└── seed/                # Data population (DML)
    ├── 01_lookup_tables.sql
    ├── 02_dev_users.sql
    ├── 03_test_data.sql
    └── large_dataset.sql.dvc  # DVC-tracked
```

## Seed File Template

```sql
-- seed/01_lookup_tables.sql
BEGIN;

INSERT INTO tb_categories (id, name, sort_order_num) VALUES
    ('cat-electronics', 'Electronics', 1),
    ('cat-clothing', 'Clothing', 2),
    ('cat-books', 'Books', 3)
ON CONFLICT (id) DO NOTHING;

INSERT INTO tb_statuses (id, name, description_txt) VALUES
    ('active', 'Active', 'Item is active and visible'),
    ('inactive', 'Inactive', 'Item is hidden from users'),
    ('archived', 'Archived', 'Item is archived for records')
ON CONFLICT (id) DO NOTHING;

COMMIT;
```

## Running Seeds

**Single file:**
```bash
psql $DATABASE_URL < supabase/seed/01_lookup_tables.sql
```

**All files in order with progress:**
```bash
uv run scripts/run_seeds.py supabase/seed/
```

**With Supabase CLI (runs seed.sql on reset):**
```bash
supabase db