maternal-app/docs/DATABASE_MIGRATIONS_CONSOLIDATED.md

# Database Migrations Consolidation

**Generated**: October 6, 2025
**Purpose**: Consolidated database migration strategy for fresh installs and upgrades

## Current Migration Issues

### Duplicate Version Numbers
The following version numbers have multiple migration files:
- **V008**: 4 different migrations
  - V008_create_photos.sql
  - V008_create_data_deletion_requests.sql
  - V008_add_user_photo_url.sql
  - V008_add_eula_acceptance.sql
- **V009**: 3 different migrations
  - V009_create_activity_partitions.sql
  - V009_add_photo_alt_text.sql
  - V009_add_performance_indexes.sql
- **V010**: 3 different migrations
  - V010_create_ai_conversations.sql
  - V010_add_mfa_fields.sql
  - V010_create_user_preferences.sql
- **V011**: 2 different migrations
  - V011_create_password_reset_tokens.sql
  - V011_add_webauthn_credentials.sql

## Consolidated Migration Order

### Phase 1: Core Authentication & Users
```
V001_create_core_auth.sql
V002_create_family_structure.sql
V003_create_refresh_tokens.sql
```

### Phase 2: Activity Tracking
```
V004_create_activity_tracking.sql
V005_add_user_preferences.sql
V006_create_audit_log.sql
```

### Phase 3: Communications & Media
```
V007_create_notifications.sql
V008_create_photos.sql
```

### Phase 4: User Profile Enhancements
```
V009_add_user_photo_url.sql
V010_add_photo_alt_text.sql
V011_add_eula_acceptance.sql
```

### Phase 5: Security Enhancements
```
V012_add_mfa_fields.sql
V013_add_webauthn_credentials.sql
V014_create_password_reset_tokens.sql
```

### Phase 6: AI Features
```
V015_create_ai_conversations.sql
V016_create_voice_feedback.sql
V017_create_conversation_embeddings.sql
```

### Phase 7: Compliance & Privacy
```
V018_create_data_deletion_requests.sql
V019_create_deletion_requests.sql
V020_add_coppa_compliance.sql
```

### Phase 8: Performance & Preferences
```
V021_create_activity_partitions.sql
V022_add_performance_indexes.sql
V023_create_user_preferences.sql
```

### Phase 9: Additional Features
```
V024_add_medicine_activity_types.sql
V025_add_child_display_preferences.sql
V026_create_multi_child_preferences.sql
V027_add_activity_bulk_operations.sql
```

## Renaming Strategy

To fix the duplicate version numbers, here's the renaming plan:

| Old Name | New Name | Purpose |
|----------|----------|---------|
| V001_create_core_auth.sql | V001_create_core_auth.sql | No change |
| V002_create_family_structure.sql | V002_create_family_structure.sql | No change |
| V003_create_refresh_tokens.sql | V003_create_refresh_tokens.sql | No change |
| V004_create_activity_tracking.sql | V004_create_activity_tracking.sql | No change |
| V005_add_user_preferences.sql | V005_add_user_preferences.sql | No change |
| V006_create_audit_log.sql | V006_create_audit_log.sql | No change |
| V007_create_notifications.sql | V007_create_notifications.sql | No change |
| V008_create_photos.sql | V008_create_photos.sql | Keep first V008 |
| V008_add_user_photo_url.sql | V009_add_user_photo_url.sql | Rename |
| V009_add_photo_alt_text.sql | V010_add_photo_alt_text.sql | Rename |
| V008_add_eula_acceptance.sql | V011_add_eula_acceptance.sql | Rename |
| V010_add_mfa_fields.sql | V012_add_mfa_fields.sql | Rename |
| V011_add_webauthn_credentials.sql | V013_add_webauthn_credentials.sql | Rename |
| V011_create_password_reset_tokens.sql | V014_create_password_reset_tokens.sql | Rename |
| V010_create_ai_conversations.sql | V015_create_ai_conversations.sql | Rename |
| V012_create_voice_feedback.sql | V016_create_voice_feedback.sql | Rename |
| V014_create_conversation_embeddings.sql | V017_create_conversation_embeddings.sql | Rename |
| V008_create_data_deletion_requests.sql | V018_create_data_deletion_requests.sql | Rename |
| V015_create_deletion_requests.sql | V019_create_deletion_requests.sql | Rename (duplicate?) |
| V016_add_coppa_compliance.sql | V020_add_coppa_compliance.sql | Rename |
| V009_create_activity_partitions.sql | V021_create_activity_partitions.sql | Rename |
| V009_add_performance_indexes.sql | V022_add_performance_indexes.sql | Rename |
| V010_create_user_preferences.sql | V023_create_user_preferences.sql | Rename |
| V013_add_medicine_activity_types.sql | V024_add_medicine_activity_types.sql | Rename |
| V017_add_child_display_preferences.sql | V025_add_child_display_preferences.sql | Rename |
| V018_create_multi_child_preferences.sql | V026_create_multi_child_preferences.sql | Rename |
| V019_add_activity_bulk_operations.sql | V027_add_activity_bulk_operations.sql | Rename |

## Master Migration Script

For fresh installations, we need a single script that runs all migrations in order:

```bash
#!/bin/bash
# master-migration.sh - Run all migrations for fresh install

DATABASE_NAME="${DATABASE_NAME:-parentflow_production}"
DATABASE_USER="${DATABASE_USER:-parentflow_user}"
DATABASE_HOST="${DATABASE_HOST:-localhost}"
DATABASE_PORT="${DATABASE_PORT:-5432}"

MIGRATION_DIR="./src/database/migrations"

# Array of migrations in correct order
MIGRATIONS=(
    "V001_create_core_auth.sql"
    "V002_create_family_structure.sql"
    "V003_create_refresh_tokens.sql"
    "V004_create_activity_tracking.sql"
    "V005_add_user_preferences.sql"
    "V006_create_audit_log.sql"
    "V007_create_notifications.sql"
    "V008_create_photos.sql"
    "V009_add_user_photo_url.sql"
    "V010_add_photo_alt_text.sql"
    "V011_add_eula_acceptance.sql"
    "V012_add_mfa_fields.sql"
    "V013_add_webauthn_credentials.sql"
    "V014_create_password_reset_tokens.sql"
    "V015_create_ai_conversations.sql"
    "V016_create_voice_feedback.sql"
    "V017_create_conversation_embeddings.sql"
    "V018_create_data_deletion_requests.sql"
    "V019_create_deletion_requests.sql"
    "V020_add_coppa_compliance.sql"
    "V021_create_activity_partitions.sql"
    "V022_add_performance_indexes.sql"
    "V023_create_user_preferences.sql"
    "V024_add_medicine_activity_types.sql"
    "V025_add_child_display_preferences.sql"
    "V026_create_multi_child_preferences.sql"
    "V027_add_activity_bulk_operations.sql"
)

echo "Starting database migration..."
echo "Database: $DATABASE_NAME@$DATABASE_HOST:$DATABASE_PORT"

for migration in "${MIGRATIONS[@]}"; do
    echo "Running migration: $migration"
    psql -h "$DATABASE_HOST" -p "$DATABASE_PORT" -U "$DATABASE_USER" -d "$DATABASE_NAME" -f "$MIGRATION_DIR/$migration"
    if [ $? -ne 0 ]; then
        echo "ERROR: Migration $migration failed!"
        exit 1
    fi
    echo "✓ Migration $migration completed"
done

echo "All migrations completed successfully!"
```

## Migration Tracking Table

Create a migration tracking table to record which migrations have been applied:

```sql
-- V000_create_migration_tracking.sql
CREATE TABLE IF NOT EXISTS schema_migrations (
    version VARCHAR(10) PRIMARY KEY,
    filename VARCHAR(255) NOT NULL,
    applied_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    checksum VARCHAR(64),
    description TEXT
);

-- Index for quick lookup
CREATE INDEX idx_schema_migrations_applied_at ON schema_migrations(applied_at);
```

## Action Items

1. **Rename duplicate migration files** to use sequential versioning
2. **Create migration tracking table** (V000_create_migration_tracking.sql)
3. **Create master migration script** for fresh installs
4. **Update TypeORM configuration** to use renamed migrations
5. **Test migration sequence** on fresh database
6. **Document rollback procedures** for each migration

## Rollback Strategy

Each migration should have a corresponding rollback script:

```
migrations/
  V001_create_core_auth.sql
  V001_create_core_auth.rollback.sql
  V002_create_family_structure.sql
  V002_create_family_structure.rollback.sql
  ...
```

## Notes for Developers

1. Always use sequential version numbers (V001, V002, etc.)
2. Never reuse version numbers
3. Include descriptive names after version number
4. Always test migrations on a copy of production data
5. Include both upgrade and rollback scripts
6. Document any data transformations
7. Check for dependencies between migrations

## Migration Validation Checklist

Before running migrations on production:

- [ ] All migrations tested on staging environment
- [ ] Backup of production database taken
- [ ] Rollback scripts prepared and tested
- [ ] Migration order verified
- [ ] No duplicate version numbers
- [ ] All foreign key constraints validated
- [ ] Indexes created for performance
- [ ] Data migration scripts tested (if applicable)
- [ ] Application code compatible with schema changes
- [ ] Monitoring alerts configured for migration issues