f6fac6c4bc
Fix bin/publish: use correct .env path for rspade_system Fix bin/publish script: prevent grep exit code 1 from terminating script 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
210 lines
6.5 KiB
Markdown
Executable File
210 lines
6.5 KiB
Markdown
Executable File
# 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. |