hwhub/DB_README.md

Database & Backend Notes

This document is the operational source of truth for database setup and backend contracts used by the app.

Stack

• Supabase Postgres
• Supabase Auth
• Supabase Storage
• Supabase RPC functions

Scope

This file intentionally stays concise. Do not paste full raw data-dictionary exports here.

If you need snapshots, store them separately (for example in a local db_exports/ folder) and summarize only key outcomes in this file.

Environments

Document environment endpoints and ownership:

• Development: TBD
• Staging: TBD
• Production: TBD

Core App Tables

Keep this section focused on app-owned tables (not full Supabase system schemas).

• collections
• collection_members
• hotwheels
• global_cars
• car_votes
• car_reports

Key RPC Functions

• get_collection_counts
• get_collection_members
• get_user_id_by_email
• remove_collection_member
• create_collection_with_owner (atomic create path)

Atomic Collection Creation

App code now prefers a transactional RPC for collection creation:

• App integration: CollectionService.create()
• Migration script: db/atomic_create_collection_with_owner.sql

Apply

Run the script in Supabase SQL Editor:

• db/atomic_create_collection_with_owner.sql

RLS Expectations

For each core table, document:

• who can select
• who can insert
• who can update
• who can delete
• special policy conditions

Status: TBD

Storage

• Bucket: car-images (private)
• Access model: signed URLs from app/backend
• Ownership path pattern: {auth.uid()}/{entry.id}.jpg

Migration Workflow

1. Write SQL migration in repository (db/ or migration folder).
2. Validate in development.
3. Verify RLS impact.
4. Promote to staging.
5. Promote to production.
6. Record change summary in this document.

Operational Checklist

Before deploy:

• Migration SQL reviewed
• RLS policy impact checked
• RPC grant/permissions verified
• Rollback strategy identified
• App compatibility validated (flutter analyze, tests, smoke flows)

Known Risks / Notes

• Keep app and DB changes synchronized when changing RPC signatures.
• Favor DB-side transactional functions for multi-step write operations.
• Avoid exposing backend internals in user-facing error messages.

References

• App service integration: lib/services/collection_service.dart
• Atomic RPC migration: db/atomic_create_collection_with_owner.sql
• Security process: SECURITY.md