rspade_system/docs/llm_migration_system.md

LLM-Friendly Migration System - Automatic Snapshot Protection

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: Automatic Docker Snapshot System

Core Design

The php artisan migrate command automatically handles database snapshots in development mode. No separate commands needed.

How It Works

1. Development Mode (RSX_MODE=development)

   • Automatically creates MySQL snapshot before migrations
   • Runs all pending migrations with validation
   • On success: commits changes, regenerates constants, recompiles bundles
   • On failure: automatically rolls back to snapshot

2. Debug/Production Mode (RSX_MODE=debug or production)

   • No snapshot protection (source code is read-only)
   • Migrations run directly
   • Schema normalization still runs
   • Constants and bundles NOT regenerated

Migration Flow

# Development - just one command does everything
$ php artisan migrate
 Development mode: Using automatic snapshot protection

[1/4] Creating database snapshot...
[OK] Snapshot created successfully.

[2/4] Running migrations...
[OK] All 3 migrations completed successfully

[3/4] Running schema quality check...
[OK] Schema quality check passed.

[4/4] Committing changes...
[OK] Snapshot committed - backup removed.

Running post-migration tasks...
[OK] Migration completed successfully!

Automatic Recovery on Failure

$ php artisan migrate
 Development mode: Using automatic snapshot protection

[1/4] Creating database snapshot...
[OK] Snapshot created successfully.

[2/4] Running migrations...

[ERROR] Migration failed!
 Automatically rolling back to snapshot...

[OK] Database restored to pre-migration state.

Fix your migration files and run "php artisan migrate" again.

Implementation Details

The unified migrate command in development mode:

1. Stops MySQL via supervisord
2. Creates backup of /var/lib/mysql to /var/lib/mysql_backup
3. Restarts MySQL and runs migrations
4. On success: removes backup, regenerates constants, recompiles bundles
5. On failure: restores backup, removes flag file

Environment Detection

The system automatically detects the environment:

1. Development Mode (snapshots enabled):

   • RSX_MODE=development in .env
   • Docker environment detected (/.dockerenv exists)

2. Debug/Production Mode (no snapshots):

   • RSX_MODE=debug or RSX_MODE=production
   • OR not running in Docker

Benefits for LLMs

1. Zero-Step Recovery

   • Failed migrations automatically restore database
   • No commands to remember
   • Just fix migration files and run migrate again

2. Safe Experimentation

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

3. Simple Mental Model

   • One command: php artisan migrate
   • System handles all the complexity
   • Clear success/failure messaging

4. Production Safety

   • System automatically adapts to environment
   • Source code treated as read-only in debug/production
   • Clear separation of dev/prod behaviors

Limitations

1. Docker Only: Snapshots require Docker environment with supervisord
2. Development Only: Not available in debug/production modes
3. Disk Space: Requires space for MySQL data directory copy

Implementation Files

• /app/RSpade/Commands/Migrate/Maint_Migrate.php - Unified migrate command
• /app/Http/Middleware/CheckMigrationMode.php - Web UI protection during migration

Why This Approach

This implementation was chosen because:

1. Complete Safety: Filesystem snapshots guarantee perfect rollback
2. Zero Friction: Single command handles everything
3. LLM-Friendly: No multi-step workflow to remember
4. Production Compatible: Gracefully adapts to environment
5. Laravel Integration: Works with existing migration system