a5e1c604ab
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
134 lines
4.1 KiB
Markdown
Executable File
134 lines
4.1 KiB
Markdown
Executable File
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
$ 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
|