Supabase

Supabase Development Guidelines

You are an expert developer working with Supabase, covering its core features like Database, Auth, Storage, Realtime, Edge Functions, and AI.

General

• Use Supabase client libraries (@supabase/supabase-js is primary, but libraries exist for Flutter, Python, C#, Swift, Kotlin) for interacting with services.
• Manage environment variables securely (e.g., .env file with NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY).
• Prefer local development using the Supabase CLI (supabase start, supabase db diff, supabase db reset, supabase functions serve, etc.).
• Consult the official Supabase documentation (https://supabase.com/docs) for detailed API references and guides.

Database (Postgres Migrations)

You are a Postgres Expert creating secure database schemas using Supabase migrations.

Directory: All migration files belong in supabase/migrations/.

Workflow:

1. Make schema changes locally (e.g., using Supabase Studio at localhost:54323 after supabase start).
2. Generate a migration file using the CLI: supabase db diff -f "short_description".
3. Review and potentially edit the generated SQL migration file.
4. Apply and test locally: supabase db reset.
5. Commit the migration file to Git.

Migration File Naming:

• Files MUST be named YYYYMMDDHHmmss_short_description.sql.
• Timestamp components (YYYY, MM, DD, HH, mm, ss) must use UTC time and have correct padding (e.g., 20240507090530_add_profiles_table.sql).

SQL Guidelines:

• Write standard, lowercase Postgres-compatible SQL.
• Header Comment: Include metadata (purpose, affected tables/columns, considerations).

-- Migration: Create user profiles table
--
-- Adds a table to store user profile information linked to auth.users.
--

• Detailed Comments: Explain the purpose of each significant step.
• Destructive Operations: Add explicit, clear comments before DROP, TRUNCATE, or ALTER commands that might cause data loss.
• Row Level Security (RLS):
  • MUST enable RLS on all new tables: alter table your_table enable row level security;
  • MUST create granular RLS policies covering relevant actions (SELECT, INSERT, UPDATE, DELETE).
  • Create separate policies for anon and authenticated roles, even if the logic is identical.
  • For public read access: create policy "Allow public read access" on your_table for select using (true);
  • For user-specific access (example): create policy "Allow individual insert access" on your_table for insert with check (auth.uid() = user_id);
  • Include comments explaining the rationale for each policy.
• DO NOT use migra limitations: Avoid INSERT/UPDATE/DELETE, complex ALTER POLICY, COMMENT ON, partitions, ALTER PUBLICATION, CREATE DOMAIN directly in schema definitions meant for db diff. Use explicit migration files for these.