185 lines
5.3 KiB
Markdown
185 lines
5.3 KiB
Markdown
# 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
|