Framework updates
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
root
@@ -1,4 +1,4 @@
|
||||
# LLM-Friendly Migration System - Snapshot Implementation
|
||||
# LLM-Friendly Migration System - Automatic Snapshot Protection
|
||||
|
||||
## Problem Statement
|
||||
LLMs struggle with partial migration failures because:
|
||||
@@ -7,155 +7,94 @@ LLMs struggle with partial migration failures because:
|
||||
- LLMs get confused about what has/hasn't been applied
|
||||
- Recovery requires manual intervention or database reset
|
||||
|
||||
## Implemented Solution: Docker Snapshot System
|
||||
## Implemented Solution: Automatic 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.
|
||||
The `php artisan migrate` command automatically handles database snapshots in development mode. No separate commands needed.
|
||||
|
||||
### 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
|
||||
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. **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
|
||||
```
|
||||
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
|
||||
|
||||
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
|
||||
### 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
|
||||
|
||||
#### 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...
|
||||
```
|
||||
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 required):
|
||||
- `APP_ENV` is not 'production'
|
||||
1. **Development Mode** (snapshots enabled):
|
||||
- `RSX_MODE=development` in `.env`
|
||||
- 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
|
||||
2. **Debug/Production Mode** (no snapshots):
|
||||
- `RSX_MODE=debug` or `RSX_MODE=production`
|
||||
- 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
|
||||
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
|
||||
@@ -163,48 +102,32 @@ The system automatically detects the environment:
|
||||
- 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
|
||||
- One command: `php artisan migrate`
|
||||
- System handles all the complexity
|
||||
- Clear success/failure messaging
|
||||
|
||||
4. **Production Safety**
|
||||
- System automatically adapts to environment
|
||||
- No dangerous operations in production
|
||||
- Source code treated as read-only in debug/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
|
||||
2. **Development Only**: Not available in debug/production modes
|
||||
3. **Disk Space**: Requires space for MySQL data directory copy
|
||||
4. **Single Session**: Only one migration session at a time
|
||||
|
||||
### Future Enhancements
|
||||
### Implementation Files
|
||||
|
||||
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
|
||||
- `/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 over alternatives because:
|
||||
This implementation was chosen 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
|
||||
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
|
||||
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.
|
||||
Reference in New Issue
Block a user