# Migration Scripts Environment Configuration Guide

## Overview

Both the migration and rollback scripts support custom environment files via the `--env` flag, allowing you to easily switch between development and production databases.

## Quick Reference

### Development Environment (Default)

```bash
# Uses ../environment.env by default
node scripts/migrateCustomerData.js --sources SOURCE --destination DEST --preview
node scripts/rollbackMigration.js
```

### Production Environment

```bash
# Use --env flag to specify production environment
node scripts/migrateCustomerData.js \
  --env ../environment_prod.env \
  --sources SOURCE --destination DEST --preview

node scripts/rollbackMigration.js --env ../environment_prod.env
```

### Custom Environment File

```bash
# Relative path from scripts/ directory
node scripts/migrateCustomerData.js \
  --env ../custom_environment.env \
  --sources SOURCE --destination DEST

# Absolute path
node scripts/migrateCustomerData.js \
  --env /full/path/to/environment.env \
  --sources SOURCE --destination DEST
```

## Environment File Requirements

Your environment file must contain these database connection variables:

```bash
# Database Configuration
DB_HOSTS=127.0.0.1:27017
DB_NAME=agmission
DB_USR=agm
DB_PWD=your_password
DB_AUTH_SOURCE=agmission
DB_REPLSET=rs0
DB_MAX_POOLSIZE=8
DB_USE_TLS=true
DB_TLS_CA_FILE=/path/to/ca.crt
DB_TLS_CERT_FILE=/path/to/cert.pem
```

## Workflow Examples

### Safe Production Migration Workflow

```bash
# 1. Preview on production to verify data
node scripts/migrateCustomerData.js \
  --env ../environment_prod.env \
  --sources karinna.oliveira@amaggi.com.br,jean.tornich@amaggi.com.br \
  --destination karinna.oliveira@amaggi.com \
  --reuse-existing-entities \
  --preview

# 2. Review the preview output carefully

# 3. Execute the migration
node scripts/migrateCustomerData.js \
  --env ../environment_prod.env \
  --sources karinna.oliveira@amaggi.com.br,jean.tornich@amaggi.com.br \
  --destination karinna.oliveira@amaggi.com \
  --reuse-existing-entities

# 4. If something goes wrong, rollback immediately
node scripts/rollbackMigration.js --env ../environment_prod.env
```

### Test on Development, Execute on Production

```bash
# 1. Test migration on development database first
node scripts/migrateCustomerData.js \
  --sources test_source@example.com \
  --destination test_dest@example.com \
  --preview

# 2. Execute on development to verify
node scripts/migrateCustomerData.js \
  --sources test_source@example.com \
  --destination test_dest@example.com

# 3. Test rollback on development
node scripts/rollbackMigration.js

# 4. Once confident, execute on production
node scripts/migrateCustomerData.js \
  --env ../environment_prod.env \
  --sources real_source@example.com \
  --destination real_dest@example.com \
  --preview

# 5. Execute production migration
node scripts/migrateCustomerData.js \
  --env ../environment_prod.env \
  --sources real_source@example.com \
  --destination real_dest@example.com
```

## Verification

The script will always print which environment file it's loading:

```
Loading environment from: /home/user/server/environment_prod.env
```

**Always verify this line** to ensure you're connecting to the correct database!

## Best Practices

1. ✅ **Always use `--preview` first** on production
2. ✅ **Verify the environment file path** in the output
3. ✅ **Backup production database** before migration
4. ✅ **Test on development** environment first
5. ✅ **Keep environment files secure** (add to .gitignore)
6. ✅ **Document which environment was used** in your notes

## Common Mistakes to Avoid

❌ **Don't**: Test on production without preview  
✅ **Do**: Always run `--preview` first on production

❌ **Don't**: Forget to specify `--env` for production  
✅ **Do**: Always use `--env ../environment_prod.env` for production

❌ **Don't**: Assume the default is production  
✅ **Do**: Remember the default is `environment.env` (development)

❌ **Don't**: Run rollback without knowing which environment  
✅ **Do**: Always specify `--env` for rollback to match migration environment

## Troubleshooting

### "Loading environment from" shows wrong path

**Problem**: The script loaded the wrong environment file

**Solution**: Check that:
- You spelled `--env` correctly
- The path is correct (relative to scripts/ directory or absolute)
- The environment file exists

### Database connection errors

**Problem**: Cannot connect to database after using `--env`

**Solution**: Verify that:
- The environment file contains all required DB_* variables
- The database credentials are correct
- The database server is accessible from your machine
- TLS certificates paths are correct

### Migration worked but rollback fails

**Problem**: Migration succeeded but rollback throws errors

**Solution**: Ensure:
- You're using the **same environment file** for rollback as you used for migration
- The `migration_history.json` file exists and wasn't deleted
- You haven't manually modified the database between migration and rollback

## Related Documentation

- [README_CUSTOMER_MIGRATION.md](./README_CUSTOMER_MIGRATION.md) - Full migration documentation
- [ADMIN_CONVERSION_SUMMARY.md](../ADMIN_CONVERSION_SUMMARY.md) - Admin conversion details
- [REUSE_ENTITIES_ROLLBACK.md](../REUSE_ENTITIES_ROLLBACK.md) - Entity reuse documentation