Supabase Deployment Operations Guide¶

Comprehensive guide for managing Supabase deployments, database migrations, and edge functions for the Micro-Learning Platform.

Table of Contents¶

Quick Reference
Environment Setup
Local Development
Database Operations
Edge Functions
Production Deployment
Secrets Management
Monitoring & Logs
Troubleshooting
Migration to Production

Quick Reference¶

Most Common Commands¶

# Local Development
deno task supabase:start          # Start local Supabase
deno task supabase:stop           # Stop local Supabase
deno task function:serve          # Serve edge functions locally

# Database
deno task db:status               # Check migration status
deno task db:migrate              # Apply pending migrations
deno task db:reset                # Reset local database (drops all data)
deno task db:new <name>           # Create new migration file

# Deployment
deno task deploy                  # Deploy all edge functions
deno task deploy:changed          # Deploy only modified functions
deno task deploy:full             # Full deployment (migrations + functions)
deno task deploy:check            # Health check deployed functions

# Monitoring
deno task supabase:status         # Project status overview
deno task supabase:logs <fn>      # View function logs
deno task logs                    # View all logs

Environment Setup¶

Prerequisites¶

Supabase CLI (latest version)

# macOS
brew install supabase/tap/supabase

# npm (alternative)
npm install -g supabase

Deno (v1.x or later)
```
# macOS
brew install deno
```
Supabase Account & Project
Create account at https://supabase.com
Create a new project for production

Authentication¶

# Login to Supabase CLI
supabase login

# Verify authentication
deno task supabase:status

Project Linking¶

Link your local project to the remote Supabase project:

# Interactive linking
deno task supabase:link

# Or manually
supabase link --project-ref <your-project-ref>

Find your project reference in the Supabase dashboard under Project Settings > General.

Local Development¶

Starting Local Supabase¶

# Start all services (PostgreSQL, Auth, Storage, Edge Functions)
deno task supabase:start

# Alternative: Direct Supabase CLI
supabase start

Local URLs:

Service	URL
API	http://127.0.0.1:54321
Studio (Dashboard)	http://127.0.0.1:54323
Database	postgresql://postgres:postgres@127.0.0.1:54322/postgres

Serving Edge Functions¶

# Start edge functions with hot reload
deno task function:serve

# Verbose mode (debug logging)
deno task function:serve:verbose

Local Function URLs:

http://127.0.0.1:54321/functions/v1/graph/*
http://127.0.0.1:54321/functions/v1/content/*
http://127.0.0.1:54321/functions/v1/home/*
http://127.0.0.1:54321/functions/v1/search/*
http://127.0.0.1:54321/functions/v1/user/*
http://127.0.0.1:54321/functions/v1/metadata/*
http://127.0.0.1:54321/functions/v1/snapshots/*

Stopping & Restarting¶

# Stop local Supabase
deno task supabase:stop

# Restart (stop + start)
deno task supabase:restart

Database Operations¶

Migration Status¶

View current migration status for local and remote:

deno task db:status

Output shows:

All migration files in supabase/migrations/
Applied migrations on the remote database
Pending migrations that need to be applied

Creating New Migrations¶

# Create a new migration file
deno task db:new add_user_preferences

# Creates: supabase/migrations/YYYYMMDDHHMMSS_add_user_preferences.sql

Migration Best Practices:

Use descriptive names: add_, update_, remove_, fix_
Keep migrations small and focused
Always test migrations locally before production
Never modify existing migrations after deployment

Applying Migrations¶

Local Development¶

# Apply migrations to local database
deno task db:migrate

Production¶

# Apply migrations to production (with confirmation prompts)
deno task db:migrate:production

Warning: Production migrations require double confirmation to prevent accidental changes.

Resetting Local Database¶

# Drop all data and re-apply all migrations
deno task db:reset

Warning: This destroys all local data. Only use for development.

Schema Comparison¶

# Compare local and remote schemas
deno task db:diff

Shows SQL statements needed to sync schemas.

Pulling Remote Schema¶

# Pull remote schema to local (overwrites local migrations)
deno task db:pull

Warning: This overwrites local migration files. Use with caution.

Edge Functions¶

Available Functions¶

Function	Auth	Description
`graph`	Public	Knowledge graph navigation
`content`	Optional	Lesson content delivery
`home`	Optional	Homepage aggregation
`search`	Required	Full-text search
`user`	Required	User profile & progress
`metadata`	Public	Static enumerations
`snapshots`	Required	Content versioning

Deploying Functions¶

Deploy All Functions¶

deno task deploy

Deploy Specific Functions¶

deno task deploy graph search user

Deploy Only Changed Functions¶

Uses git diff to detect modified functions:

deno task deploy:changed

Health Checks¶

Verify deployed functions are healthy:

deno task deploy:check

Checks each function's /health endpoint and reports status.

Creating New Functions¶

deno task function:create <function-name>

Creates the function structure in functions/<name>/.

Production Deployment¶

Pre-Deployment Checklist¶

All tests passing locally
Database migrations reviewed
Edge function code reviewed
Environment variables documented
Backup of production database (if needed)

Full Deployment Workflow¶

The recommended way to deploy to production:

# Full deployment: migrations + functions + health check
deno task deploy:full

This command:

Applies pending database migrations
Deploys all edge functions
Runs health checks on deployed functions

Manual Step-by-Step Deployment¶

If you prefer manual control:

# 1. Check current status
deno task supabase:status

# 2. Apply database migrations
deno task db:migrate:production

# 3. Deploy edge functions
deno task deploy

# 4. Verify deployment
deno task deploy:check

Deployment Verification¶

After deployment, verify:

# Check project status
deno task supabase:status

# View recent logs
deno task supabase:logs graph
deno task supabase:logs user

# Run E2E tests against production
deno task test:e2e

Secrets Management¶

Listing Secrets¶

deno task supabase:secrets
# or
deno task supabase:secrets list

Setting Secrets¶

# Set a single secret
deno task supabase:secrets set MY_API_KEY=secret_value

# Using supabase CLI directly
supabase secrets set MY_API_KEY=secret_value

Removing Secrets¶

deno task supabase:secrets unset MY_API_KEY

Required Secrets for Production¶

Secret	Description
`SUPABASE_SERVICE_ROLE_KEY`	Service role key for admin operations
`JWT_SECRET`	Custom JWT secret (if overriding default)

Environment Variables Reference¶

See .env.example for all available environment variables:

# View example configuration
cat .env.example

Monitoring & Logs¶

Viewing Function Logs¶

# View logs for a specific function
deno task supabase:logs graph
deno task supabase:logs user

# View with more lines
supabase functions logs graph --limit 500

# View all available functions
deno task supabase:logs

Real-time Logs¶

# Stream logs in real-time
supabase functions logs graph --follow

General Logging¶

# View all logs (custom script)
deno task logs

Troubleshooting¶

Common Issues¶

1. "Project not linked"¶

# Link your project
deno task supabase:link
# or
supabase link --project-ref <your-ref>

2. "Migration failed"¶

# Check migration status
deno task db:status

# View schema differences
deno task db:diff

# Reset local database if needed
deno task db:reset

3. "Function deployment failed"¶

# Check function health
deno task deploy:check

# View logs for errors
deno task supabase:logs <function-name>

# Redeploy specific function
deno task deploy <function-name>

4. "Authentication failed"¶

# Re-login to Supabase
supabase login

# Verify authentication
deno task supabase:status

5. "SDK build failed"¶

# Rebuild SDK manually
cd sdk && npm install && npm run build

# Then retry deployment
deno task deploy

Debug Mode¶

For verbose output during operations:

# Verbose function serving
deno task function:serve:verbose

# Debug logging in dev
LOG_LEVEL=debug LOG_FORMAT=pretty deno task dev

Rollback Procedures¶

Database Rollback¶

Identify the problematic migration
Create a new migration to reverse changes
Apply the rollback migration

# Create rollback migration
deno task db:new rollback_<original_migration>

# Edit the file to reverse changes
# Apply the rollback
deno task db:migrate:production

Function Rollback¶

Revert code changes in git
Redeploy functions

git revert <commit-hash>
deno task deploy

Migration to Production¶

Initial Production Setup¶

Follow these steps for first-time production deployment:

Step 1: Create Supabase Project¶

Go to https://supabase.com
Create a new project
Note the project reference ID

Step 2: Link Project¶

deno task supabase:link
# Enter your project reference when prompted

Step 3: Configure Secrets¶

# Set required secrets
deno task supabase:secrets set SUPABASE_SERVICE_ROLE_KEY=your_key

Step 4: Apply Initial Migrations¶

# Push all migrations to production
deno task db:migrate:production

Step 5: Deploy Functions¶

# Deploy all edge functions
deno task deploy

Step 6: Verify Deployment¶

# Check status
deno task supabase:status

# Health check
deno task deploy:check

# View logs
deno task supabase:logs graph

Ongoing Production Updates¶

For subsequent deployments:

# Option 1: Full deployment (recommended)
deno task deploy:full

# Option 2: Manual steps
deno task db:migrate:production  # If there are migrations
deno task deploy:changed         # Deploy modified functions
deno task deploy:check           # Verify

CI/CD Integration¶

For automated deployments, use the GitHub Actions workflow:

# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Deno
        uses: denoland/setup-deno@v1

      - name: Setup Supabase CLI
        uses: supabase/setup-cli@v1

      - name: Link Project
        run: supabase link --project-ref ${{ secrets.SUPABASE_PROJECT_REF }}
        env:
          SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}

      - name: Apply Migrations
        run: supabase db push
        env:
          SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}

      - name: Deploy Functions
        run: deno task deploy
        env:
          SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}

Command Reference¶

Database Commands (`db:*`)¶

Command	Description
`deno task db`	Show database operations help
`deno task db:status`	Show migration status
`deno task db:migrate`	Apply migrations to linked project
`deno task db:migrate:production`	Apply migrations with confirmation
`deno task db:reset`	Reset local database
`deno task db:diff`	Show schema differences
`deno task db:pull`	Pull remote schema
`deno task db:new <name>`	Create new migration

Supabase Commands (`supabase:*`)¶

Command	Description
`deno task supabase`	Show Supabase operations help
`deno task supabase:status`	Project status overview
`deno task supabase:start`	Start local Supabase
`deno task supabase:stop`	Stop local Supabase
`deno task supabase:restart`	Restart local Supabase
`deno task supabase:link`	Link to Supabase project
`deno task supabase:secrets`	Manage secrets
`deno task supabase:logs <fn>`	View function logs

Deployment Commands (`deploy:*`)¶

Command	Description
`deno task deploy`	Deploy all edge functions
`deno task deploy:changed`	Deploy modified functions only
`deno task deploy:full`	Full deployment workflow
`deno task deploy:check`	Health check functions

Local Environment Commands (`local:*`)¶

Command	Description
`deno task local:start`	Start local environment
`deno task local:stop`	Stop local environment
`deno task local:reset`	Reset local database
`deno task local:seed`	Seed test users
`deno task local:setup`	Reset + seed combined
`deno task test:e2e:all`	Run all E2E tests

Support¶

For issues or questions:

Check TROUBLESHOOTING.md
Review DEPLOYMENT_GUIDE.md
File issues at the repository

Supabase Deployment Operations Guide¶

Table of Contents¶

Quick Reference¶

Most Common Commands¶

Environment Setup¶

Prerequisites¶

Authentication¶

Project Linking¶

Local Development¶

Starting Local Supabase¶

Serving Edge Functions¶

Stopping & Restarting¶

Database Operations¶

Migration Status¶

Creating New Migrations¶

Applying Migrations¶

Local Development¶

Production¶

Resetting Local Database¶

Schema Comparison¶

Pulling Remote Schema¶

Edge Functions¶

Available Functions¶

Deploying Functions¶

Deploy All Functions¶

Deploy Specific Functions¶

Deploy Only Changed Functions¶

Health Checks¶

Creating New Functions¶

Production Deployment¶

Pre-Deployment Checklist¶

Full Deployment Workflow¶

Manual Step-by-Step Deployment¶

Deployment Verification¶

Secrets Management¶

Listing Secrets¶

Setting Secrets¶

Removing Secrets¶

Required Secrets for Production¶

Environment Variables Reference¶

Monitoring & Logs¶

Viewing Function Logs¶

Real-time Logs¶

General Logging¶

Troubleshooting¶

Common Issues¶

1. "Project not linked"¶

2. "Migration failed"¶

3. "Function deployment failed"¶

4. "Authentication failed"¶

5. "SDK build failed"¶

Debug Mode¶

Rollback Procedures¶

Database Rollback¶

Function Rollback¶

Migration to Production¶

Initial Production Setup¶

Step 1: Create Supabase Project¶

Step 2: Link Project¶

Step 3: Configure Secrets¶

Step 4: Apply Initial Migrations¶

Step 5: Deploy Functions¶

Step 6: Verify Deployment¶

Ongoing Production Updates¶

CI/CD Integration¶

Command Reference¶

Database Commands (db:*)¶

Supabase Commands (supabase:*)¶

Deployment Commands (deploy:*)¶

Local Environment Commands (local:*)¶

Support¶

Database Commands (`db:*`)¶

Supabase Commands (`supabase:*`)¶

Deployment Commands (`deploy:*`)¶

Local Environment Commands (`local:*`)¶