rspade_system/docs/llm_migration_system.md

LLM-Friendly Migration System - Snapshot Implementation

Problem Statement

LLMs struggle with partial migration failures because:

• MySQL DDL operations auto-commit and cannot be rolled back
• Partial migrations leave the database in an inconsistent state
• LLMs get confused about what has/hasn't been applied
• Recovery requires manual intervention or database reset

Implemented Solution: Docker Snapshot System

Core Design

The system uses filesystem-level snapshots of the MySQL data directory in Docker environments to provide complete rollback capability for migrations.

How It Works

1. Development Mode Only

   • System only enforces snapshots in development environments
   • Production migrations run normally without snapshots
   • Detects environment via APP_ENV and Docker presence

2. Migration Session Flow

   # 1. Start migration session (creates snapshot)
   php artisan migrate:begin
   
   # 2. Run migrations (with safety net)
   php artisan migrate
   
   # 3a. If successful, commit changes
   php artisan migrate:commit
   
   # 3b. If failed, rollback to snapshot
   php artisan migrate:rollback
   

3. Automatic Rollback on Failure

   • When migrations fail in development, system offers automatic rollback
   • LLM gets clear instructions on how to proceed
   • Database restored to exact pre-migration state

Implementation Details

Commands

migrate:begin

• Stops MySQL via supervisord
• Creates backup of /var/lib/mysql to /var/lib/mysql_backup
• Restarts MySQL
• Creates .migrating flag file
• Blocks web UI access (development only)

migrate:rollback

• Stops MySQL
• Replaces MySQL data directory with backup
• Restarts MySQL
• Removes flag file and backup
• Re-enables web UI

migrate:commit

• Removes backup directory
• Removes flag file
• Re-enables web UI

migrate:status

• Shows current migration session status
• Lists available commands
• Checks database connectivity
• Shows pending migrations count

Modified migrate Command

The existing Maint_Migrate command was enhanced to:

• Check for .migrating flag in development mode
• Require snapshot unless --production flag is used
• Offer automatic rollback on failure
• Run normally in production environments

Middleware Protection

CheckMigrationMode middleware:

• Only active in development environments
• Blocks HTTP requests during migration sessions
• Shows detailed error message with recovery instructions

Usage Examples

Successful Migration (Development)

$ php artisan migrate:begin
✅ Database snapshot created successfully!

$ php artisan migrate
✅ Migration mode active - snapshot available for rollback
Running migrations...
✅ Migrations completed successfully!

$ php artisan migrate:commit
✅ Migration changes committed successfully!

Failed Migration with Auto-Rollback (Development)

$ php artisan migrate:begin
✅ Database snapshot created successfully!

$ php artisan migrate
✅ Migration mode active - snapshot available for rollback
Running migrations...
❌ Migration failed!
Error: Column already exists

🔄 Database snapshot is available for rollback.
Would you like to rollback to the snapshot now? (yes/no) [no]: yes

Rolling back database...
✅ Database rolled back successfully!

You can now:
   1. Fix your migration files
   2. Run "php artisan migrate:begin" to create a new snapshot
   3. Run "php artisan migrate" to try again

Production Migration

$ php artisan migrate
🚀 Running in production mode (no snapshot protection)
Running migrations...
✅ Migrations completed successfully!

Bypass Snapshot in Development

$ php artisan migrate --production
⚠️  Running without snapshot protection!
Are you absolutely sure? This cannot be undone! (yes/no) [no]: yes
Running migrations...

Environment Detection

The system automatically detects the environment:

1. Development Mode (snapshots required):

   • APP_ENV is not 'production'
   • Docker environment detected (/.dockerenv exists)
   • No --production flag passed

2. Production Mode (no snapshots):

   • APP_ENV is 'production' OR
   • --production flag is passed OR
   • Not running in Docker

Benefits for LLMs

1. Clear Error Recovery

   • Failed migrations automatically offer rollback
   • No partial state confusion
   • Explicit instructions on next steps

2. Safe Experimentation

   • LLMs can try migrations without fear
   • Complete rollback always available
   • Learn from failures without consequences

3. Simple Mental Model

   • Migration session is atomic: all or nothing
   • Clear session lifecycle: begin → migrate → commit/rollback
   • Status command provides current state

4. Production Safety

   • System automatically adapts to environment
   • No dangerous operations in production
   • Clear separation of dev/prod behaviors

Implementation Files

• /app/Console/Commands/MigrateBeginCommand.php - Snapshot creation
• /app/Console/Commands/MigrateRollbackCommand.php - Snapshot restoration
• /app/Console/Commands/MigrateCommitCommand.php - Session completion
• /app/Console/Commands/MigrateStatusCommand.php - Status display
• /app/Console/Commands/Maint_Migrate.php - Enhanced migrate command
• /app/Http/Middleware/CheckMigrationMode.php - Web UI protection

Limitations

1. Docker Only: Snapshots require Docker environment with supervisord
2. Development Only: Not available in production environments
3. Disk Space: Requires space for MySQL data directory copy
4. Single Session: Only one migration session at a time

Future Enhancements

Potential improvements:

• Incremental snapshots for large databases
• Migration preview/dry-run mode
• Automatic migration file fixes for common errors
• Integration with version control for migration rollback

Why This Approach

This implementation was chosen over alternatives because:

1. Complete Safety: Filesystem snapshots guarantee perfect rollback
2. Simple Implementation: Uses existing tools (supervisord, cp, rm)
3. LLM-Friendly: Clear session model with explicit states
4. Production Compatible: Gracefully degrades in production
5. Laravel Integration: Works with existing migration system
6. Immediate Value: Solves the core problem without complexity

The snapshot approach provides the "all or nothing" behavior that makes migrations predictable and safe for LLM interaction, while maintaining full compatibility with Laravel's migration system and production deployments.