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:

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

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