# Migration Guide

**Last Updated**: 2025-01-09

## Overview

This guide provides instructions for migrating between versions of Sankofa Phoenix and migrating from other platforms.

## Table of Contents

- [API Version Migration](#api-version-migration)
- [Database Migration](#database-migration)
- [Configuration Migration](#configuration-migration)
- [Azure Migration](#azure-migration)
- [Deployment Migration](#deployment-migration)

---

## API Version Migration

### Migrating Between API Versions

See [API Versioning Guide](./api/API_VERSIONING.md) for detailed API migration instructions.

### Quick Steps

1. Review API changelog for breaking changes
2. Update client code to use new API version
3. Test all API interactions
4. Deploy updated client code
5. Monitor for issues

---

## Database Migration

### Schema Migrations

Database migrations are managed automatically:

```bash
# Run migrations
cd api
npm run db:migrate

# Rollback if needed
npm run db:rollback
```

### Manual Migration Steps

1. **Backup Database**: Always backup before migration
   ```bash
   pg_dump sankofa > backup_$(date +%Y%m%d).sql
   ```

2. **Run Migrations**: Execute migration scripts
   ```bash
   npm run db:migrate
   ```

3. **Verify Migration**: Check migration status
   ```bash
   npm run db:migrate:status
   ```

4. **Test Application**: Verify application functionality
5. **Monitor**: Watch for errors post-migration

### Data Migration

For data migrations:

1. **Export Data**: Export from source
2. **Transform Data**: Apply necessary transformations
3. **Import Data**: Import to new schema
4. **Validate**: Verify data integrity
5. **Update References**: Update any code references

---

## Configuration Migration

### Environment Variables

When updating configuration:

1. **Review Changes**: Check configuration changes in release notes
2. **Update `.env` Files**: Update environment variables
3. **Test Configuration**: Verify configuration is correct
4. **Deploy**: Deploy updated configuration

### Configuration Files

```bash
# Backup current configuration
cp .env.local .env.local.backup

# Update configuration
# Edit .env.local with new values

# Verify configuration
npm run config:validate
```

---

## Azure Migration

### From Azure to Sankofa Phoenix

See [Azure Migration Guide](./tenants/AZURE_MIGRATION.md) for comprehensive Azure migration instructions.

### Key Migration Areas

1. **Identity**: Migrate from Azure AD to Keycloak
2. **Resources**: Migrate VMs and resources
3. **Networking**: Update network configurations
4. **Storage**: Migrate data and storage
5. **Applications**: Update application configurations

---

## Deployment Migration

### Upgrading Deployment

1. **Review Release Notes**: Check for breaking changes
2. **Update Dependencies**: Update package versions
3. **Run Tests**: Ensure all tests pass
4. **Deploy**: Follow deployment procedures
5. **Verify**: Confirm deployment success

### Rolling Back Deployment

1. **Identify Issue**: Determine what needs rollback
2. **Stop Services**: Stop affected services
3. **Restore Previous Version**: Deploy previous version
4. **Restore Database** (if needed): Restore database backup
5. **Verify**: Confirm rollback success

---

## Common Migration Scenarios

### Scenario 1: Minor Version Update

**Steps:**
1. Review changelog
2. Update dependencies
3. Run tests
4. Deploy
5. Verify

### Scenario 2: Major Version Update

**Steps:**
1. Review migration guide for major version
2. Backup all data
3. Update configuration
4. Run database migrations
5. Update code for breaking changes
6. Test thoroughly
7. Deploy in staging first
8. Deploy to production
9. Monitor closely

### Scenario 3: Platform Migration

**Steps:**
1. Plan migration timeline
2. Set up new platform
3. Migrate data
4. Migrate applications
5. Update DNS/configurations
6. Test thoroughly
7. Cutover
8. Monitor and verify

---

## Migration Checklist

### Pre-Migration

- [ ] Review migration documentation
- [ ] Backup all data
- [ ] Test migration in staging
- [ ] Notify stakeholders
- [ ] Schedule migration window

### During Migration

- [ ] Execute migration steps
- [ ] Monitor progress
- [ ] Verify each step
- [ ] Document any issues

### Post-Migration

- [ ] Verify all functionality
- [ ] Test critical paths
- [ ] Monitor for errors
- [ ] Update documentation
- [ ] Communicate completion

---

## Troubleshooting

### Common Issues

1. **Migration Fails**: Check logs, rollback if needed
2. **Data Loss**: Restore from backup
3. **Configuration Errors**: Verify environment variables
4. **Service Downtime**: Check service status and logs

### Getting Help

- Check [Troubleshooting Guide](./TROUBLESHOOTING_GUIDE.md)
- Review migration documentation
- Check logs for specific errors
- Contact support if needed

---

## Related Documentation

- [API Versioning Guide](./api/API_VERSIONING.md)
- [Deployment Guide](./DEPLOYMENT.md)
- [Troubleshooting Guide](./TROUBLESHOOTING_GUIDE.md)
- [Azure Migration Guide](./tenants/AZURE_MIGRATION.md)

---

**Note**: Always backup data before performing migrations. Test migrations in a staging environment first.