Staging Environment Setup Guide

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• ✅ Isolated database environment
• ✅ Automatic migration sync via GitHub
• ✅ Cost-effective (included in plan)
• ✅ Easy switching between environments

​

Option A: Use Supabase Branch (Recommended)

​

Step 1: Verify Prerequisites

// Check current project
mcp_supabase_get_project_url()
// Expected: https://<project-ref>.supabase.co

// List existing branches
mcp_supabase_list_branches()
// Expected: Shows existing branches (if any)

# Verify CLI installed
supabase --version
# Expected: Supabase CLI 1.x.x

# Verify logged in
supabase projects list
# Expected: Lists your projects

​

Step 2: Create Persistent Staging Branch

# Create persistent staging branch
supabase --experimental branches create --persistent staging

# Note the branch project ID from output
# Example: Created branch staging with project ID: <branch-project-id>

​

Step 3: Verify Branch Creation

// List branches to confirm creation
mcp_supabase_list_branches()
// Expected: Shows 'staging' with status 'active'

​

Step 4: Link Local Project to Staging Branch

# Link to staging branch
supabase link --project-ref <staging-branch-project-id>

# Verify link
supabase status
# Expected: Shows linked to staging branch

​

Step 5: Apply All Migrations

# Push all migrations to staging branch
supabase db push

# Expected: All 393+ migrations apply successfully

// List applied migrations
mcp_supabase_list_migrations()
// Expected: 393+ migrations listed

​

Step 6: Verify Database State

// List all tables
mcp_supabase_list_tables({ schemas: ["public"] })

// Verify table counts by module
mcp_supabase_execute_sql({
  query: `
    SELECT 
      CASE 
        WHEN table_name LIKE 'pf_%' THEN 'PF'
        WHEN table_name LIKE 'hr_%' THEN 'HR'
        WHEN table_name LIKE 'fa_%' THEN 'FA'
        WHEN table_name LIKE 'fw_%' THEN 'FW'
        WHEN table_name LIKE 'rh_%' THEN 'RH'
        WHEN table_name LIKE 'gr_%' THEN 'GR'
        WHEN table_name LIKE 'fm_%' THEN 'FM'
        WHEN table_name LIKE 'lo_%' THEN 'LO'
        WHEN table_name LIKE 'it_%' THEN 'IT'
        ELSE 'Other'
      END as module,
      COUNT(*) as table_count
    FROM information_schema.tables
    WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
    GROUP BY module
    ORDER BY module;
  `
})

​

Step 7: GitHub Integration Setup (Recommended)

1. Go to Project Settings → Integrations → GitHub
2. Click “Connect to GitHub”
3. Authorize repository access
4. Configure branch mapping:
   • main Git branch → Supabase main project
   • staging Git branch → Supabase staging branch

1. Create a test Git branch
2. Add a simple migration
3. Push to Git
4. Check Supabase dashboard for auto-deployment

​

Step 8: Set Environment Variable

# Set staging project ID
export SUPABASE_PROJECT_ID=<staging-branch-project-id>

# Or add to .env.local (don't commit)
echo "SUPABASE_PROJECT_ID=<staging-branch-project-id>" >> .env.local

​

Option B: Create Separate Project (Alternative)

​

Step 1: Create Staging Project

1. Go to Supabase Dashboard
2. Click “New Project”
3. Configure:
   • Name: encoreos-staging
   • Database Password: Generate strong password (save securely)
   • Region: Same as production project
   • Pricing Plan: Free tier is sufficient for testing
4. Wait for project to be provisioned (~2 minutes)

​

Step 2: Link and Apply Migrations

# Get staging project reference ID from dashboard URL
# https://supabase.com/dashboard/project/{project-ref}

# Link to staging project
supabase link --project-ref <staging-project-ref>

# Apply all migrations
supabase db push

# Verify
supabase migration list

​

Step 3: Verify Database State

​

Quick Verification Checklist

​

MCP Checks

• mcp_supabase_list_branches() shows staging branch
• mcp_supabase_list_tables() returns ~465 tables
• mcp_supabase_list_migrations() shows 393+ migrations
• mcp_supabase_get_advisors({ type: "security" }) returns no critical issues

​

CLI Checks

• supabase status shows linked to staging
• supabase migration list shows all migrations applied

​

Troubleshooting

​

Issue: Branch creation fails

1. Check Supabase plan includes branching feature
2. Ensure CLI is latest version: npm install -g supabase
3. Verify authentication: supabase login

​

Issue: Cannot link to branch

1. Verify branch project ID is correct (from dashboard or MCP)
2. Check if project exists: supabase projects list
3. Re-authenticate if needed: supabase login

​

Issue: Migration fails with “relation already exists”

1. Some migrations may have been partially applied
2. Check migration history in Supabase dashboard
3. If safe, reset and reapply: supabase db reset (WARNING: deletes data)

​

Issue: Table counts don’t match expected

1. Check for migration errors in Supabase dashboard → Database → Migrations
2. Some tables may be in other schemas (check auth, storage)
3. Verify all migrations applied: mcp_supabase_list_migrations()

​

Issue: GitHub integration not auto-deploying

1. Verify GitHub integration is connected in dashboard
2. Check branch mapping is correct
3. Review webhook delivery logs in GitHub repository settings
4. Ensure migration files are in supabase/migrations/ directory

​

Seeding Staging Database

​

Seed File Structure

supabase/seeds/
├── base/                  # Core data (run first)
│   ├── 01_organizations.sql
│   ├── 02_users.sql
│   └── 03_sites.sql
└── modules/               # Module data (run after base)
    ├── 04_hr.sql
    ├── 05_fa.sql
    └── ... (06-11 for other modules)

​

Generate Seed Files

# Generate all seed files
npm run generate:seeds -- --all --orgs 2 --employees 50

# Generate specific module
npm run generate:seeds -- --module hr

​

Validate Seeds

npm run validate:seeds -- --verbose

​

Apply Seeds to Staging

# Dry run first (no changes)
npm run db:seed:dev -- --dry-run

# Apply for real
npm run db:seed:dev

​

Verify Seed Data

mcp_supabase_execute_sql --query "SELECT COUNT(*) FROM pf_organizations WHERE id LIKE '00000000-%'"

​

Safety Guidelines

• ⚠️ NEVER run seeds in production
• Seeds use deterministic UUIDs (00000000- prefix)
• Seeds use test email domain (@staging.encoreos.io)
• Always verify project/branch before seeding

​

Next Steps

1. Run SQL Audits: See SQL_AUDIT_INSTRUCTIONS.md
2. Create Fix Migrations: Use templates in supabase/migrations/TEMPLATE_*.sql
3. Generate TypeScript Types: See TYPE_GENERATION_GUIDE.md
4. Test Application: Point app at staging environment variables
5. Verify Environment Isolation: Run npm run test:isolation

​

Related Documentation

• Completion Plan - Full migration plan
• MCP Usage Guide - When to use MCP vs CLI
• Supabase Branching - Official docs