wheels env switch

Switch to a different environment in your Wheels application.

Synopsis

wheels env switch [name] [options]

Description

The wheels env switch command changes the active environment for your Wheels application. It updates configuration files, environment variables, and optionally restarts services to apply the new environment settings.

Arguments

Argument	Description	Default
name	Target environment name	Required

Options

Option	Description	Default
--check	Validate before switching	true
--restart	Restart application after switch	false
--backup	Backup current environment	false
--force	Force switch even with issues	false
--quiet	Suppress output	false
--help	Show help information

Examples

Switch to staging

wheels env switch staging

Switch with application restart

wheels env switch production --restart

Force switch without validation

wheels env switch testing --force

Switch with backup

wheels env switch production --backup

Quiet switch for scripts

wheels env switch development --quiet

What It Does

1. Validates Target Environment:

   • Checks if environment exists

   • Verifies configuration

   • Tests database connection

2. Updates Configuration:

   • Sets WHEELS_ENV variable

   • Updates .wheels-env file

   • Modifies environment.cfm if needed

3. Applies Changes:

   • Clears caches

   • Reloads configuration

   • Restarts services (if requested)

4. Verifies Switch:

   • Confirms environment active

   • Checks application health

   • Reports status

Output Example

Switching environment...

Current: development
Target:  staging

✓ Validating staging environment
✓ Configuration valid
✓ Database connection successful
✓ Updating environment settings
✓ Clearing caches
✓ Environment switched successfully

New Environment: staging
Database: wheels_staging
Debug: Enabled
Cache: Partial

Environment File Updates

.wheels-env

Before:

development

After:

staging

Environment Variables

Updates system environment:

export WHEELS_ENV=staging
export WHEELS_DATASOURCE=wheels_staging

Validation Process

Before switching, validates:

1. Configuration:

   • File exists

   • Syntax valid

   • Required settings present

2. Database:

   • Connection works

   • Tables accessible

   • Migrations current

3. Dependencies:

   • Required services available

   • File permissions correct

   • Resources accessible

Switch Strategies

Safe Switch (Default)

wheels env switch production

• Full validation

• Graceful transition

• Rollback on error

Fast Switch

wheels env switch staging --force --no-check

• Skip validation

• Immediate switch

• Use with caution

Zero-Downtime Switch

wheels env switch production --strategy=blue-green

• Prepare new environment

• Switch load balancer

• No service interruption

Backup and Restore

Create Backup

wheels env switch production --backup
# Creates: .wheels-env-backup-20240115-103045

Restore from Backup

wheels env restore --from=.wheels-env-backup-20240115-103045

Manual Restore

# If switch fails
cp .wheels-env-backup-20240115-103045 .wheels-env
wheels reload

Service Management

With Restart

wheels env switch production --restart

Restarts:

• Application server

• Cache services

• Background workers

Service-Specific

wheels env switch staging --restart-services=app,cache

Pre/Post Hooks

Configure in .wheels-cli.json:

{
  "env": {
    "switch": {
      "pre": [
        "wheels test run --quick",
        "git stash"
      ],
      "post": [
        "wheels dbmigrate latest",
        "wheels cache clear",
        "npm run build"
      ]
    }
  }
}

Environment-Specific Actions

Development → Production

wheels env switch production
# Warning: Switching from development to production
# - Debug will be disabled
# - Caching will be enabled
# - Error details will be hidden
# Continue? (y/N)

Production → Development

wheels env switch development
# Warning: Switching from production to development
# - Debug will be enabled
# - Caching will be disabled
# - Sensitive data may be exposed
# Continue? (y/N)

Integration

CI/CD Pipeline

- name: Switch to staging
  run: |
    wheels env switch staging --check
    wheels test run
    wheels deploy exec staging

Deployment Scripts

#!/bin/bash
# deploy.sh

# Switch environment
wheels env switch $1 --backup

# Run migrations
wheels dbmigrate latest

# Clear caches
wheels cache clear

# Verify
wheels env | grep $1

Rollback

If switch fails or causes issues:

# Automatic rollback
wheels env switch production --auto-rollback

# Manual rollback
wheels env switch:rollback

# Force previous environment
wheels env switch development --force

Troubleshooting

Switch Failed

• Check validation errors

• Verify target environment exists

• Use --force if necessary

Application Not Responding

• Check service status

• Review error logs

• Manually restart services

Database Connection Issues

• Verify credentials

• Check network access

• Test connection manually

Best Practices

1. Always Validate: Don't skip checks in production

2. Use Backups: Enable backup for critical switches

3. Test First: Switch in staging before production

4. Monitor After: Check application health post-switch

5. Document Changes: Log environment switches

Security Considerations

• Production switches require confirmation

• Sensitive configs protected

• Audit trail maintained

• Access controls enforced

Notes

• Some changes require application restart

• Database connections may need reset

• Cached data cleared on switch

• Background jobs may need restart

See Also

• wheels env - Environment management overview
• wheels env list - List environments
• wheels env setup - Setup environments
• wheels reload - Reload application