Skip to main content

Quick Environment Guide

TL;DR - What Database Should I Use?​

┌────────────────────────────────────────────────────────────┐
│  Scenario              │  Database                         │
├────────────────────────────────────────────────────────────┤
│  Everyday coding       │  ✅ Docker PostgreSQL (local)    │
│  Testing migrations    │  ✅ Docker PostgreSQL (local)    │
│  Testing RLS policies  │  ✅ Docker PostgreSQL (local)    │
│  Testing Supabase Auth │  🔌 Remote Supabase (dev)        │
│  Team staging          │  🎯 Remote Supabase (staging)    │
│  Production            │  🚀 Remote Supabase (production) │
└────────────────────────────────────────────────────────────┘

Your Typical Week​

Monday - Friday (Everyday Development)​

Use: Dev container with local Docker PostgreSQL

# 1. Open VS Code
code .

# 2. Reopen in container (first time takes 3-5 min)
# Command Palette: "Dev Containers: Reopen in Container"

# 3. Everything auto-configured!
# - PostgreSQL running at localhost:5432
# - All dependencies installed
# - Database migrations run
# - Test data seeded

# 4. Start coding
pnpm db:console     # Check database
pnpm test:rls       # Test RLS policies
pnpm db:reset       # Safe to destroy and rebuild

Why local?

  • ⚡ Fast: <1ms query latency
  • 🔒 Isolated: Your own database, can't break anyone else
  • 💰 Free: No API limits
  • 📡 Offline: Work without internet
  • 🧪 Safe: Reset database 100x a day if needed

Occasionally (Integration Testing)​

Use: Remote Supabase dev project (optional)

# When you need to test:
# - Supabase Auth (Google OIDC, magic links)
# - Supabase Storage (file uploads)
# - Supabase Realtime (websockets)
# - External API integrations (Hostaway, Stripe)

# Setup (one-time):
# 1. Create separate Supabase project: "tvl-dev-integration"
# 2. Get connection string from Supabase dashboard
# 3. Update DATABASE_URL in .env.local temporarily

DATABASE_URL=postgresql://postgres:password@abc123.supabase.co:5432/postgres

# 4. Run your integration tests
pnpm test:integration

# 5. Switch back to local when done
DATABASE_URL=postgresql://tvl_user:tvl_password@localhost:5432/tvl_dev

Why remote dev project?

  • 🔌 Test Supabase-specific features
  • 🌐 Test webhooks from external services
  • 👥 Share test environment with QA (optional)

Feature Complete (Staging Deployment)​

Use: Remote Supabase staging project (via CI/CD)

# You don't manually deploy - CI/CD does this!

# Process:
# 1. Push code to feature branch
# 2. Create PR
# 3. CI runs tests with local PostgreSQL
# 4. Merge to main
# 5. CI deploys to staging Supabase automatically
# 6. Team tests at https://staging.thevillalife.com

Why staging?

  • 🎯 Production parity
  • 👥 Team collaboration
  • 🧪 QA and UAT
  • 📊 Performance testing with real-like data

Going Live (Production)​

Use: Remote Supabase production project (via CI/CD only)

# Manual approval required for production deployments

# Process:
# 1. Staging testing complete
# 2. Create production release PR
# 3. Team review and approval
# 4. CI deploys to production Supabase
# 5. Monitor at https://app.thevillalife.com

Why production Supabase?

  • 🚀 Managed service (PostgreSQL + API + Auth + Storage)
  • 📈 Scalable (auto-scaling, connection pooling)
  • 💾 Automated backups
  • 🔒 Enterprise security
  • 📊 Built-in monitoring

Quick Setup Commands​

First Time Setup​

# 1. Clone repo
git clone https://github.com/your-org/the-villa-life.git
cd the-villa-life

# 2. Open in VS Code
code .

# 3. Install Dev Containers extension
# https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers

# 4. Reopen in container
# Command Palette (F1): "Dev Containers: Reopen in Container"

# 5. Wait for setup (3-5 minutes first time)
# - Builds Docker images
# - Installs pnpm dependencies
# - Sets up PostgreSQL
# - Runs migrations
# - Seeds test data

# 6. You're ready! 🚀
pnpm db:console  # Verify database works

Daily Development​

# Start your day
code .  # Opens in dev container automatically if configured

# Database commands (all safe on local)
pnpm db:migrate           # Run pending migrations
pnpm db:migrate:create    # Create new migration
pnpm db:rollback          # Rollback last migration
pnpm db:seed              # Load test data
pnpm db:reset             # Destroy + rebuild everything

# Testing
pnpm test                 # All tests
pnpm test:rls             # RLS policy tests
pnpm test:db              # Database tests

# Coding
# Just edit files - hot reload enabled

Switching to Remote Supabase (Rare)​

# Only when you need Supabase-specific features

# Option 1: Temporary switch (in dev container terminal)
export DATABASE_URL="postgresql://postgres:password@abc123.supabase.co:5432/postgres"

# Option 2: Edit .env.local
# Change DATABASE_URL line, save, restart dev server

# Option 3: Create separate config
cp .env.example .env.local.remote
# Edit .env.local.remote with Supabase connection
# Swap files when needed

# Remember to switch back!

Common Questions​

Q: Can I use remote Supabase for everyday dev?​

A: You can, but you shouldn't. It's slower (100-500ms vs <1ms), costs money, requires internet, and you risk breaking shared environments. Local Docker is purpose-built for fast iteration.

Q: How do I test Supabase Auth locally?​

A: You have two options:

  1. Mock it - Create mock auth functions for local testing (recommended)
  2. Use remote - Temporarily point to remote Supabase dev project

Q: Do migrations run automatically?​

A:

  • Local dev: Yes, on first container start
  • Staging/Production: Via CI/CD only, never manually

Q: Can I reset the production database?​

A: No! Never! Only local dev database can be reset safely.

Q: What if I need to work offline?​

A: Dev container with local PostgreSQL works completely offline. This is a huge advantage over remote-only setups.

Q: How much does this cost?​

A:

  • Local dev: $0 (Docker is free)
  • Supabase Staging: ~$25/month (Pro plan)
  • Supabase Production: ~$25/month (Pro plan)
  • Total: $50/month for all non-local environments

File Structure​

your-project/
├── .env.example           # Template (committed to git)
├── .env.local             # Local dev (Docker PostgreSQL) - auto-created
├── .env.local.remote      # Optional: remote Supabase dev - create if needed
├── .env.staging           # Staging (NEVER COMMIT) - CI/CD only
├── .env.production        # Production (NEVER COMMIT) - CI/CD only
└── .devcontainer/
    ├── devcontainer.json  # Dev container config
    ├── docker-compose.yml # Services (app + postgres + pgadmin)
    └── Dockerfile         # Development environment

Troubleshooting​

Dev container won't start​

# Rebuild container
# Command Palette: "Dev Containers: Rebuild Container"

Can't connect to PostgreSQL​

# In dev container terminal:
docker ps  # Check if postgres is running
psql postgresql://tvl_user:tvl_password@localhost:5432/tvl_dev

Migrations failing​

# Check migration status
pnpm db:migrate:status

# Reset and try again (local only!)
pnpm db:reset

Remote Supabase won't connect​

# Test connection
psql "postgresql://postgres:[PASSWORD]@[REF].supabase.co:5432/postgres"

# Check credentials at: https://app.supabase.com/project/_/settings/database

Next Steps​

  1. ✅ Read this guide - You're here!
  2. 📖 Full guide: Environment Configuration
  3. 🏗️ Multi-tenancy: Multi-Tenancy Implementation
  4. 🔒 RLS Policies: RLS Policy Patterns
  5. 🚀 Start coding!

Remember​

  • 🏠 Local dev = Docker PostgreSQL (99% of your time)
  • 🔌 Remote dev = Supabase (when testing integrations)
  • 🎯 Staging = Supabase (team testing via CI/CD)
  • 🚀 Production = Supabase (live via CI/CD)

Keep it simple. Start local. Scale when needed. 🎯