# 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**
   ```bash
   # 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)
```bash
$ 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)
```bash
$ 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
```bash
$ php artisan migrate
🚀 Running in production mode (no snapshot protection)
Running migrations...
✅ Migrations completed successfully!
```

#### Bypass Snapshot in Development
```bash
$ 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.