# Local development
supabase start                    # Start local Supabase
supabase stop                     # Stop local Supabase
supabase status                   # Check status and get URLs/keys

# Database
supabase db reset                 # Reset local DB and apply migrations
supabase db diff --use-migra -f name  # Generate migration from changes
supabase db push                  # Push migrations to remote
supabase migration new name       # Create empty migration
supabase migration list           # List migrations
supabase gen types typescript --local > src/types/database.ts

# Edge Functions
supabase functions new name       # Create new function
supabase functions serve          # Serve locally for dev
supabase functions deploy         # Deploy all functions
supabase functions deploy name    # Deploy specific function

# Secrets
supabase secrets set KEY=value    # Set secret for Edge Functions
supabase secrets list             # List configured secrets

# Logs
supabase logs                     # View all logs
supabase logs --service postgres  # View specific service logs

{
  "stack": {
    "languages": ["typescript"],
    "workspaces": {
      "server": {
        "type": "web-server",
        "language": "typescript",
        "database": {
          "provider": "supabase",
          "orm": {
            "name": "drizzle",
            "schemaPath": "src/db/schema.ts"
          },
          "migrationStrategy": {
            "type": "hybrid",
            "serviceRange": { "start": "00100", "end": "00199" }
          }
        }
      }
    }
  }
}

{
  "stack": {
    "languages": ["typescript", "python", "rust"],
    "sharedDatabase": {
      "enabled": true,
      "provider": "supabase",
      "serviceRanges": {
        "server": "00100-00199",
        "api": "00200-00299",
        "rust-service": "00300-00399"
      }
    }
  }
}

+-----------------------------------------------------------------+
|              UNIVERSAL HYBRID WORKFLOW                          |
+-----------------------------------------------------------------+
|  ORM Schema (language-specific)                                 |
|  +- TypeScript: src/db/schema.ts (Drizzle)                      |
|  +- Python: src/db/models/*.py (SQLAlchemy)                     |
|  +- Rust: src/db/models/*.rs (SQLx)                             |
|       |                                                         |
|  Native Migration Generation                                    |
|  +- drizzle-kit generate -> drizzle/migrations/                 |
|  +- alembic revision --autogenerate -> alembic/versions/        |
|  +- sqlx migrate add -> migrations/                             |
|       |                                                         |
|  Copy to supabase/migrations/XXXXX_<service>_*.sql              |
+-----------------------------------------------------------------+
|  Supabase SQL (supabase/migrations/)                            |
|  +- 00000_extensions.sql (bootstrap)                            |
|  +- 00001_core_functions.sql                                    |
|  +- 001XX_node_*.sql (TypeScript service)                       |
|  +- 002XX_python_*.sql (Python service)                         |
|  +- 003XX_rust_*.sql (Rust service)                             |
|  +- 004XX_shared_*.sql (cross-service)                          |
|       |                                                         |
|  supabase db reset (local) / supabase db push (remote)          |
+-----------------------------------------------------------------+

- Operations complete within 2s CPU time
- Webhook handlers (Stripe, GitHub, etc.)
- External API proxy (hide API keys)
- Low-latency global API endpoints
- Background tasks via EdgeRuntime.waitUntil()
- Cron-triggered lightweight jobs

- CPU >2s (image processing, ML inference)
- npm packages requiring native binaries
- Long-running processes >6.5 minutes
- Complex job orchestration with BullMQ
- Worker threads, streaming responses
- Full Node.js ecosystem required

- Bulk INSERT/UPDATE/DELETE (zero latency)
- Triggers (audit logs, cascading ops)
- ACID transactions across tables
- Computed columns, row validation
- Complex aggregations avoiding multiple API calls

- User-driven CRUD operations
- Real-time subscriptions
- Public data without sensitive logic
- MVP/prototype development

- Per-IP or per-user rate limiting
- Custom API key validation
- Payment status checks
- Quota enforcement
- Operations bypassing RLS with service_role

- Building with Supabase from scratch
- Need deep RLS integration (auth.uid() in policies)
- Cost-sensitive at scale ($0.00325/MAU vs $0.02)
- Simple user authentication without orgs
- Want single vendor for auth + database

- Need polished pre-built auth UI fast
- Complex organization/team management
- Multi-tenant SaaS with role-based access
- Already using Clerk in existing projects
- Want dedicated auth infrastructure
- Need advanced features (MFA, SSO) with minimal setup

# For Prisma/Drizzle on Fly.io
DATABASE_URL="postgres://postgres.[PROJECT]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres?pgbouncer=true"
DIRECT_URL="postgresql://postgres:[PASSWORD]@db.[PROJECT].supabase.co:5432/postgres"

import jwt from 'jsonwebtoken';
import jwksClient from 'jwks-rsa';

const client = jwksClient({
  jwksUri: `https://${PROJECT_REF}.supabase.co/auth/v1/.well-known/jwks.json`,
  cache: true,
  cacheMaxAge: 600000
});

async function verifySupabaseToken(token) {
  const decoded = jwt.decode(token, { complete: true });
  const key = await client.getSigningKey(decoded.header.kid);
  return jwt.verify(token, key.getPublicKey(), {
    audience: 'authenticated',
    issuer: `https://${PROJECT_REF}.supabase.co/auth/v1`
  });
}

from fastapi import Depends, HTTPException, Request
from jose import jwt, JWTError
import httpx

SUPABASE_JWT_SECRET = os.getenv("SUPABASE_JWT_SECRET")
SUPABASE_URL = os.getenv("SUPABASE_URL")

async def get_current_user(request: Request) -> dict:
    auth_header = request.headers.get("Authorization", "")
    if not auth_header.startswith("Bearer "):
        raise HTTPException(status_code=401)

    token = auth_header[7:]
    try:
        payload = jwt.decode(
            token, SUPABASE_JWT_SECRET,
            algorithms=["HS256"],
            audience="authenticated"
        )
        return payload
    except JWTError:
        raise HTTPException(status_code=401)

use axum::{extract::State, http::{Request, StatusCode}, middleware::Next, response::Response};
use jsonwebtoken::{decode, DecodingKey, Validation, Algorithm};

pub async fn auth_middleware<B>(
    State(state): State<AppState>,
    mut request: Request<B>,
    next: Next<B>,
) -> Result<Response, StatusCode> {
    let token = request.headers()
        .get("Authorization")
        .and_then(|h| h.to_str().ok())
        .and_then(|h| h.strip_prefix("Bearer "))
        .ok_or(StatusCode::UNAUTHORIZED)?;

    let mut validation = Validation::new(Algorithm::HS256);
    validation.set_audience(&["authenticated"]);

    let token_data = decode::<Claims>(
        token,
        &DecodingKey::from_secret(state.jwt_secret.as_bytes()),
        &validation
    ).map_err(|_| StatusCode::UNAUTHORIZED)?;

    request.extensions_mut().insert(token_data.claims);
    Ok(next.run(request).await)
}

const { data } = await supabase.functions.invoke('my-function', {
  headers: { 'x-region': 'us-east-1' }
});

// supabase/functions/stripe-webhook/index.ts
import { serve } from "https://deno.land/[email protected]/http/server.ts"
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
import Stripe from 'https://esm.sh/[email protected]'

serve(async (req) => {
  const signature = req.headers.get('stripe-signature')!
  const body = await req.text()

  const stripe = new Stripe(Deno.env.get('STRIPE_SECRET_KEY')!)
  const event = stripe.webhooks.constructEvent(
    body, signature, Deno.env.get('STRIPE_WEBHOOK_SECRET')!
  )

  const supabase = createClient(
    Deno.env.get('SUPABASE_URL')!,
    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
  )

  // Process event and write to DB
  await supabase.from('payments').insert({
    stripe_event_id: event.id,
    type: event.type,
    data: event.data.object
  })

  return new Response(JSON.stringify({ received: true }), {
    headers: { "Content-Type": "application/json" }
  })
})

serve(async (req) => {
  const { userId } = await req.json()

  // Return immediately
  const response = new Response(JSON.stringify({ accepted: true }))

  // Continue processing after response
  EdgeRuntime.waitUntil((async () => {
    await generateEmbeddings(userId)
    await sendNotification(userId)
  })())

  return response
})

CREATE OR REPLACE FUNCTION handle_new_user()
RETURNS TRIGGER
LANGUAGE plpgsql
SECURITY DEFINER SET search_path = ''
AS $$
BEGIN
  INSERT INTO public.profiles (id, email, created_at)
  VALUES (NEW.id, NEW.email, NOW());

  -- Async webhook via pg_net
  PERFORM net.http_post(
    url := 'https://project.supabase.co/functions/v1/new-user-webhook',
    headers := jsonb_build_object(
      'Authorization', 'Bearer ' || current_setting('app.service_role_key'),
      'Content-Type', 'application/json'
    ),
    body := jsonb_build_object('user_id', NEW.id)
  );

  RETURN NEW;
END;
$$;

CREATE TRIGGER on_auth_user_created
  AFTER INSERT ON auth.users
  FOR EACH ROW EXECUTE FUNCTION handle_new_user();

-- Efficient: uses cached JWT claim
CREATE POLICY "Users can view own org data"
ON documents FOR SELECT
USING (
  org_id = (SELECT auth.jwt() ->> 'org_id')::uuid
);

-- Add index for policy column
CREATE INDEX idx_documents_org_id ON documents(org_id);

// Fly.io Node.js worker
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
)

async function processQueue() {
  while (true) {
    const { data: messages } = await supabase.rpc('pop_queue', {
      queue_name: 'heavy_jobs',
      batch_size: 10,
      visibility_timeout: 300
    })

    for (const msg of messages || []) {
      try {
        await processHeavyJob(msg.payload)
        await supabase.rpc('ack_message', { message_id: msg.id })
      } catch (error) {
        console.error('Job failed:', error)
        // Message returns to queue after visibility timeout
      }
    }

    await new Promise(r => setTimeout(r, 1000))
  }
}

processQueue()

kodo query "supabase patterns"
kodo query "database schema"

kodo reflect  # Capture decisions