name: supabase-db-push-bypass-jwt

description: Run SQL migrations on Supabase Cloud when service role key returns 401 on REST API

Supabase DB Push — Bypass Broken JWT for Remote Migrations

When to Use

Supabase Cloud project where:

• - Service role key returns 401 Invalid API key on direct REST API calls
• - Edge Functions accept the service role key (JWT validated internally)
• - Management API (api.supabase.com) returns 403 Cloudflare for database endpoints
• - You need to run SQL migrations or modify RLS policies remotely

The Workaround

Use supabase db push — the CLI maintains its own authenticated connection to the remote database that bypasses broken JWT issues.

`bash

1. Navigate to the project's supabase/migrations directory

cd /var/www/documentos2/app/supabase/migrations

2. Mark old migrations as already-applied to avoid conflicts

supabase migration repair --status applied

3. Push new migration to remote

supabase db push --include-all --yes

`

Why This Works

• - The supabase CLI authenticates with its own method (project PAT or CLI session), NOT the service role JWT
• - It connects directly to the Postgres database remotely
• - Bypasses GoTrue JWT validation entirely

Key Constraints

• - Cannot use supabase db query — syntax not supported by all CLI versions
• - Cannot use Management API for pg/database/ endpoints (returns 403 Cloudflare)
• - Cannot access Postgres connection details — password is encrypted
• - supabase functions call does NOT work for this — use curl with anon key instead for Edge Functions

Debugging Checklist

1. Run supabase migration list to see applied vs local migrations

2. If old migrations conflict, move them to /tmp/old_migrations/ and mark as applied

3. Run supabase db push --include-all --yes and watch for NOTICE messages

4. Verify with supabase migration list — Remote column should show ✓ for the new migration

Related

• - Service role key may still work for Edge Functions (JWT validated internally by Deno runtime)
• - Anon key works for Edge Functions that validate JWT externally using JWT_SECRET
• - Management API only works for secrets management, not database operations