usda-vision/supabase/README.md

Supabase Database Module

This directory contains all Supabase configuration, migrations, and seed data for the USDA Vision project.

Structure

supabase/
├── config.toml              # Supabase CLI configuration
├── migrations/              # Database migration files (run in order)
│   ├── 00001_extensions_and_utilities.sql
│   ├── 00002_users_and_roles.sql
│   └── ...
├── seed_01_users.sql        # Initial user data
└── seed_02_phase2_experiments.sql  # Initial experiment data

Usage

With Docker Compose (Recommended)

The Supabase containers are managed by the main docker-compose.yml at the project root. Migrations and seeds are automatically run on startup.

# From project root
docker compose up -d

With Supabase CLI

If you need to use Supabase CLI commands, run them from the project root (this directory's parent):

# From project root
cd /path/to/USDA-VISION

# Start Supabase (if not using docker-compose)
supabase start

# Run migrations manually
supabase db reset

# Generate types
supabase gen types typescript --local > management-dashboard-web-app/src/types/supabase.ts

Note: The Supabase CLI looks for the supabase/ directory in the current working directory. Since we've moved it to the root, you can now run Supabase commands from the project root instead of needing to cd into management-dashboard-web-app.

Migration Workflow

1. Create a new migration:

   supabase migration new migration_name
   

2. Apply migrations:

   • Automatically via docker-compose on startup
   • Manually: supabase db reset (from project root)

3. Check migration status:

   supabase migration list
   

Seed Data

Seed files are run automatically after migrations when using supabase db reset (see config.toml → [db.seed] → sql_paths). Currently only user seed is enabled:

• seed_01_users.sql: Creates admin user and initial user profiles (enabled)
• seed_02_phase2_experiments.sql: Initial experiment data (temporarily disabled; add back to sql_paths in config.toml to re-enable)

Configuration

The config.toml file contains all Supabase service configurations:

• Database port: 54322
• API port: 54321
• Studio port: 54323
• Inbucket (email testing): 54324

See config.toml for detailed configuration options.

Accessing Services

• Supabase Studio: http://localhost:54323
• API: http://localhost:54321
• Database: postgresql://postgres:postgres@localhost:54322/postgres
• Email Testing (Inbucket): http://localhost:54324

Best Practices

1. Migrations are versioned: Always use numbered prefixes (e.g., 00001_, 00002_)
2. Migrations should be idempotent: Use IF NOT EXISTS and CREATE OR REPLACE where possible
3. Test migrations locally: Always test migrations before committing
4. Document breaking changes: Add notes in migration files for schema changes

Related Documentation

• Supabase Docker Compose Integration
• Database Schema