agmission/Development/server/scripts/MIGRATION_ENVIRONMENT_GUIDE.md

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)

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

Production Environment

# 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

# 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:

# 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

# 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

# 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 - Full migration documentation
• ADMIN_CONVERSION_SUMMARY.md - Admin conversion details
• REUSE_ENTITIES_ROLLBACK.md - Entity reuse documentation