mtgonline/backend/TEST_PLAN.md

Alembic Migration Test Plan

Overview

Test the Alembic migration setup to verify all user data tables are created correctly in PostgreSQL.

Test Steps

1. Verify File Structure

• Create alembic.ini with database URL configuration
• Create alembic/env.py with async Alembic environment
• Create alembic/versions/001_initial_user_schema.py with migration script
• Create alembic/versions/__init__.py
• Create app/models/user_data.py with all new models
• Update app/models/__init__.py to import new models
• Update Dockerfile to run migrations on container startup
• Create scripts/run_migrations.sh for migration execution

2. Test Migration Execution

• Verify Alembic configuration is correct
• Test migration in offline mode
• Test migration in online mode (if database is available)
• Verify all tables are created with correct schema

3. Verify Schema Structure

• Check all 16 tables are created
• Verify foreign key relationships
• Verify indexes are created
• Verify constraints (UNIQUE, CHECK)

4. Test Data Operations

• Insert test data into each table
• Verify CASCADE deletes work correctly
• Verify UNIQUE constraints prevent duplicates
• Verify JSONB columns store data correctly

5. Test Rollback

• Execute downgrade migration
• Verify all tables are dropped
• Verify columns are removed from existing tables

Files Created

Core Alembic Files

1. alembic.ini - Alembic configuration with database URL
2. alembic/env.py - Async Alembic environment for PostgreSQL
3. alembic/versions/001_initial_user_schema.py - Initial migration script

New Models

4. app/models/user_data.py - All user data models (16 models)
   • UserSession, DeckVersion, GameReplay, ReplayPlayer
   • GameOutcome, UserStatistics, UserCardCollection, CardWishlist
   • UserGroup, GroupMember, GroupChatMessage
   • UserNetwork, NetworkMember, UserPreference, UserActivityLog

Updated Files

5. app/models/__init__.py - Added imports for new models
6. Dockerfile - Added migration step to container startup
7. scripts/run_migrations.sh - Migration execution script

Expected Tables

User Authentication

1. user_sessions - Session management with token hashing

Deck Management

2. mtgonline_decklist_files - Enhanced with description, format, etc.
3. deck_versions - Deck version history

Game Tracking

4. game_replays - Game replay recordings
5. replay_players - Players in game replays
6. game_outcomes - Game win/loss records
7. user_statistics - User game statistics summary

Card Collection

8. user_card_collection - User-owned cards
9. card_wishlist - Cards users want

Social Features

10. user_groups - User groups
11. group_members - Group membership
12. group_chat_messages - Group chat
13. user_networks - Extended social connections
14. network_members - Network membership

User Settings

15. user_preferences - User preferences and settings
16. user_activity_log - User activity tracking

Migration Commands

Run Migrations

# Online mode (requires database connection)
alembic upgrade head

# Offline mode (for testing schema generation)
alembic upgrade head --sql

# Check migration status
alembic current
alembic history

# Generate new migration (after model changes)
alembic revision --autogenerate -m "Description"

Test Commands

# Test alembic configuration
alembic --config alembic.ini current

# Test migration generation
alembic --config alembic.ini upgrade head --sql

# Run migration
alembic --config alembic.ini upgrade head

Success Criteria

• All 16 tables created successfully
• All foreign keys established correctly
• All indexes created for performance
• All constraints enforced properly
• Migration can be rolled back successfully
• Container starts with migrations applied

Potential Issues

1. Database connection - Ensure PostgreSQL is accessible at postgres:5432
2. Model imports - Verify all models are imported in env.py
3. Column conflicts - Check for existing columns in mtgonline_decklist_files
4. Index naming - Ensure index names don't conflict with existing indexes

Next Steps

1. Run the container and verify migrations execute
2. Test data insertion and retrieval
3. Verify CASCADE deletes work correctly
4. Test downgrade migration
5. Create API endpoints for new features