db-env-switch

Original source / Raw SKILL.md

---
name: db-env-switch
description: Switch between local and production database environments by updating .env.local, killing running processes, and providing restart instructions. Use when user says "switch to local database", "switch to production database", or "change database environment".
allowed-tools: Read, Write, Bash, AskUserQuestion
version: 2.1.0
---

# Database Environment Switch

> Safely switch between local and production database configurations with process restart.

<when_to_use>

## When to Use

Invoke when user says:

- "switch to local database"
- "switch to production database"
- "use local Supabase"
- "connect to production"
- "change database environment"
  </when_to_use>

<workflow>
## Workflow Overview

| Phase | Action                                      | Reference                  |
| ----- | ------------------------------------------- | -------------------------- |
| 1     | Detect current environment                  | Read .env.local            |
| 2     | Safety check (production requires approval) | AskUserQuestion            |
| 3     | Update .env.local                           | Comment/uncomment sections |
| 4     | Kill running processes                      | Vite + Worker PIDs         |
| 5     | Verify + provide restart instructions       | Summary report             |

For detailed steps: [references/workflow-phases.md](references/workflow-phases.md)
</workflow>

<safety_rules>

## Critical Safety Rules

1. **ALWAYS confirm production switch** - Use AskUserQuestion before switching TO production
2. **Verify local Supabase is running** - Check `npx supabase status` before switching TO local
3. **Kill ALL processes** - Dev server and worker cache env vars; updating .env.local alone is NOT enough
   </safety_rules>

<environments>
## Environments

| Environment | URL                                        | Safe to Experiment       |
| ----------- | ------------------------------------------ | ------------------------ |
| LOCAL       | `http://127.0.0.1:54321`                   | Yes                      |
| PRODUCTION  | `https://<production-project-id>.supabase.co` | **NO - Real user data!** |

</environments>

<approval_gates>

## Approval Gates

| Gate               | Phase                            | Question                                                   |
| ------------------ | -------------------------------- | ---------------------------------------------------------- |
| Production Confirm | Switching TO production          | "Switch to PRODUCTION? All queries affect REAL USER DATA." |
| Local Supabase     | Switching TO local (not running) | "Start local Supabase now?"                                |

</approval_gates>

<quick_reference>

## Quick Reference

```bash
# Check current environment
grep "^VITE_SUPABASE_URL" .env.local

# Find processes (Windows)
wmic process where "commandline like '%vite%'" get processid 2>nul

# Kill by PID
taskkill //F //PID [pid]

# Restart services after switch
npm run dev
npm run worker:dev
```

For detailed commands: [references/commands-reference.md](references/commands-reference.md)
For error recovery: [references/error-recovery.md](references/error-recovery.md)
For safety reminders: [references/safety-reminders.md](references/safety-reminders.md)
</quick_reference>

<references>
## References

- [references/workflow-phases.md](references/workflow-phases.md) - Detailed 5-phase workflow
- [references/commands-reference.md](references/commands-reference.md) - Process and Supabase commands
- [references/error-recovery.md](references/error-recovery.md) - Troubleshooting failures
- [references/safety-reminders.md](references/safety-reminders.md) - Production warnings and checklists
  </references>

<version_history>

## Version History

- **v2.1.0** (2025-01-18): AI optimization updates
  - Add blockquote summary after title

- **v2.0.0** (2025-12-28): Refactored to follow skill-authoring-patterns
  - Added XML tags for structure
  - Created references/ for detailed content
  - Reduced from 916 to ~120 lines

- **v1.0.0** (2025-11-03): Initial release
  </version_history>


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/workflow-phases.md

```markdown
# Detailed Workflow Phases

## Phase 1: Detect Current State

### Step 1: Read Current Environment

```bash
Read C:\users\zac\eos-implementer-hub\.env.local
```

**Logic to determine current environment**:
- Look for uncommented `VITE_SUPABASE_URL=` line
- If contains `https://<production-project-id>.supabase.co` → **PRODUCTION**
- If contains `http://127.0.0.1:54321` → **LOCAL**

### Step 2: Determine Target Environment

Parse user request:
- "switch to local" / "use local" → TARGET = LOCAL
- "switch to production" / "connect to prod" → TARGET = PRODUCTION

If ambiguous, use AskUserQuestion to clarify.

### Step 3: Check If Switch Needed

If current == target:
```
✅ Already on [TARGET] environment
No changes needed.
```
**STOP execution**.

### Step 4: Find Running Processes

```bash
# Find Vite dev server
wmic process where "commandline like '%vite%' and name='node.exe'" get processid,commandline 2>nul

# Find worker
wmic process where "commandline like '%worker%' and name='node.exe'" get processid,commandline 2>nul
```

Extract PIDs from output for later termination.

---

## Phase 2: Safety Checks

### If Switching TO Production

**MUST use AskUserQuestion**:
```
⚠️ Switch to PRODUCTION database? All queries will affect REAL USER DATA.
- Yes, switch to production
- No, stay on local
```

If "No": **STOP execution**.

### If Switching TO Local

Check if local Supabase is running:
```bash
npx supabase status
```

If not running, offer options:
1. Start local Supabase now
2. Continue switch anyway
3. Cancel switch

---

## Phase 3: Update .env.local

### Switching TO LOCAL:

1. **Comment out production section**:
   ```
   # VITE_SUPABASE_URL=https://<production-project-id>.supabase.co
   # VITE_SUPABASE_ANON_KEY=...
   # SUPABASE_SERVICE_ROLE_KEY=...
   ```

2. **Uncomment local section**:
   ```
   VITE_SUPABASE_URL=http://127.0.0.1:54321
   VITE_SUPABASE_ANON_KEY=eyJhbGci...demo...
   SUPABASE_SERVICE_ROLE_KEY=eyJhbGci...demo...
   ```

### Switching TO PRODUCTION:

1. **Uncomment production section**
2. **Comment out local section**

### Verify Changes

Read back the file and confirm correct URL is active.

---

## Phase 4: Terminate Running Processes

**Why we kill processes**:
- Vite caches `import.meta.env` at startup
- Worker loads `.env.local` via dotenv at startup
- Simply updating .env.local is NOT sufficient

### Kill Vite Dev Server

```bash
taskkill //F //PID [vite_pid]
```

### Kill Worker

```bash
taskkill //F //PID [worker_pid]
```

---

## Phase 5: Verification & Next Steps

Display summary:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Database Environment Switch Complete!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

FROM: [SOURCE] database
TO:   [TARGET] database

Next Steps:
1. npm run dev          (restart Vite)
2. npm run worker:dev   (restart worker)
3. Verify in browser console
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

If switched to PRODUCTION: Show critical warnings about live data.
If switched to LOCAL: Show safe-to-experiment message.

```

### references/commands-reference.md

```markdown
# Commands Reference

## Environment Detection

```bash
# Check current environment
grep "^VITE_SUPABASE_URL" .env.local
```

## Process Management (Windows)

```bash
# Find running processes
wmic process where "commandline like '%vite%' and name='node.exe'" get processid,commandline 2>nul
wmic process where "commandline like '%worker%' and name='node.exe'" get processid,commandline 2>nul

# Kill processes
taskkill //F //PID [pid]
```

## Local Supabase

```bash
# Check status
npx supabase status

# Start local Supabase
npx supabase start

# Stop local Supabase
npx supabase stop
```

## Restart Services

```bash
# Restart Vite dev server
npm run dev

# Restart with custom port
PORT=8080 npm run dev

# Restart worker
npm run worker:dev
```

## Verification

```bash
# In browser console (F12):
console.log(import.meta.env.VITE_SUPABASE_URL)

# Expected LOCAL: http://127.0.0.1:54321
# Expected PROD:  https://<production-project-id>.supabase.co
```

## Environment Variables Modified

| Variable | LOCAL | PRODUCTION |
|----------|-------|------------|
| `VITE_SUPABASE_URL` | `http://127.0.0.1:54321` | `https://<production-project-id>.supabase.co` |
| `VITE_SUPABASE_ANON_KEY` | Demo anon key | Production anon key |
| `SUPABASE_SERVICE_ROLE_KEY` | Demo service role | Production service role |

All three MUST be switched together for consistent behavior.

```

### references/error-recovery.md

```markdown
# Error Recovery

## Scenario 1: .env.local File Not Found

**Problem**: Cannot locate .env.local

**Recovery**:
```
❌ .env.local file not found!

Expected location: C:\users\zac\eos-implementer-hub\.env.local

The file must be created manually. Template:

# LOCAL DATABASE (default)
VITE_SUPABASE_URL=http://127.0.0.1:54321
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...demo...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...demo...

# PRODUCTION DATABASE (uncomment to switch)
# VITE_SUPABASE_URL=https://<production-project-id>.supabase.co
# VITE_SUPABASE_ANON_KEY=<production anon key>
# SUPABASE_SERVICE_ROLE_KEY=<production service role key>
```

**STOP execution**.

---

## Scenario 2: Cannot Determine Current Environment

**Problem**: No uncommented `VITE_SUPABASE_URL` found

**Recovery**: Use AskUserQuestion to ask which environment user is on:
- Local (127.0.0.1)
- Production (<production-project-id>)
- Unknown/Other

If "Unknown": Show file contents, ask user to fix manually. **STOP**.

---

## Scenario 3: Local Supabase Not Running

**Problem**: Switching to LOCAL but Supabase not running

**Recovery**:
```
⚠️ Local Supabase is not running

Options:
1. Start local Supabase now (npx supabase start)
2. Continue switch anyway (manual start later)
3. Cancel switch
```

---

## Scenario 4: Processes Won't Terminate

**Problem**: taskkill fails (permission denied, etc.)

**Recovery**:
```
⚠️ Could not kill process automatically

Manual cleanup:
  taskkill //F //PID [pid]
  OR close the terminal window running the process

After killing manually:
  npm run dev          (for Vite)
  npm run worker:dev   (for worker)
```

**Continue** with switch even if kill fails.

---

## Scenario 5: Already on Target Environment

**Problem**: User requests switch but already on target

**Recovery**:
```
✅ Already on [TARGET] environment

Current configuration:
  VITE_SUPABASE_URL=[current URL]

No changes needed.
```

**STOP execution**.

---

## Scenario 6: User Cancels During Safety Check

**Problem**: User selects "No" or "Cancel"

**Recovery**:
```
❌ Switch cancelled by user

No changes made.
Current environment remains: [SOURCE]
```

**STOP execution** cleanly.

```

### references/safety-reminders.md

```markdown
# Safety Reminders

## Before Switching TO Production

1. Commit any uncommitted work
2. Understand all queries will hit live data
3. Be ready to switch back quickly if issues occur
4. Never run untested migrations on production
5. Never test email sending (will send to real users!)
6. Never experiment with destructive operations

## Before Switching TO Local

1. Ensure local Supabase is running (`npx supabase status`)
2. Ensure migrations are up to date (`npx supabase db reset` if needed)
3. Remember local data may be stale
4. Be aware of schema drift if migrations haven't been applied

## After ANY Switch

1. **ALWAYS restart dev server** (`npm run dev`)
2. **ALWAYS restart worker** (`npm run worker:dev`) if using automation
3. Verify in browser console that URL matches expectation
4. Test a simple query before proceeding
5. If worker was running, verify it reconnected

## Production Safety Rules

**When working on PRODUCTION database:**

**DO NOT**:
- Run destructive queries without WHERE clauses
- Test new features without thorough local testing first
- Experiment with schema migrations
- Send test emails
- Modify large amounts of data without backups
- Use worker automation without understanding what it does

**DO**:
- Query read-only operations only (SELECTs)
- Use production for debugging ONLY
- Switch back to local as soon as possible
- Keep session short and focused
- Have a backup plan / rollback strategy

```