Supabase

Supabase provides authentication and a Postgres database with Row Level Security.

Create a Project

1. Go to supabase.com and create an account
2. Create a new project
3. Wait for the project to be provisioned (takes ~2 minutes)

Get Your API Keys

Navigate to Settings → API in your Supabase dashboard and copy:

Run Database Migrations

Option 1: Supabase Dashboard

1. Go to SQL Editor in your Supabase dashboard
2. Open supabase/migrations/001_initial.sql from your project
3. Paste the contents and run the query

Option 2: Supabase CLI (Recommended)

# Link to your remote project
pnpm supabase link --project-ref <your-project-ref>

# Push migrations
pnpm supabase:push

Local Development

For local development, you can run Supabase locally:

# Start local Supabase (requires Docker)
pnpm supabase:start

# Stop when done
pnpm supabase:stop

# Reset database and run migrations
pnpm supabase:reset

Local Supabase runs at http://localhost:54321 with a dashboard at http://localhost:54323.

Row Level Security

VelocityKit uses account-scoped data access. All tables with user data have RLS policies.

Key principle: Data is scoped to account_id, not user_id. This allows for future team/organization features without migrations.

Example policy:

CREATE POLICY "Users can view their account's data"
ON items FOR SELECT
USING (account_id IN (
  SELECT account_id FROM account_users WHERE user_id = auth.uid()
));

Authentication Flow

1. User signs up → Supabase creates auth user
2. Trigger creates profile and account records
3. User signs in → Session stored in cookies
4. Auth proxy refreshes sessions automatically

Supported Auth Methods

• Email/password (default)
• Social login (Google, GitHub, etc.)
• Magic links
• MFA (optional)

To enable social providers, configure them in Authentication → Providers in your Supabase dashboard.

Generate TypeScript Types

After changing your database schema:

pnpm supabase:types

This generates types in src/types/supabase.ts for full type safety.