zaeem2396/schema-lens

Laravel package to preview migration files against current MySQL schema with destructive change detection and data export

v1.0.0 2025-12-26 19:15 UTC

Requires

• php: ^8.1
• illuminate/console: ^10.0|^11.0|^12.0
• illuminate/database: ^10.0|^11.0|^12.0
• illuminate/filesystem: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• laravel/pint: ^1.0
• orchestra/testbench: ^8.0|^9.0|^10.0
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^10.0|^11.0

MIT

• zaeem2396

• database
• cli
• mysql
• schema
• migration
• laravel
• artisan
• preview
• data-export
• destructive-changes

README

A Laravel package that extends the default Artisan CLI with commands to preview a single migration file against the current MySQL schema before execution. It provides comprehensive schema diff analysis, destructive change detection, automatic data export, and rollback simulation.

Features

• 🔍 Schema Diff Analysis: Compare migration operations against current MySQL schema
• ⚠️ Destructive Change Detection: Automatically flags dangerous operations
• 💾 Automatic Data Export: Exports affected data to CSV/JSON when destructive changes are detected
• 🔄 Rollback Simulation: Preview rollback impact and SQL statements
• 📊 Line-by-Line Mapping: Maps each database change back to exact lines in migration file
• 🎨 Clean CLI Output: Human-readable formatted output
• 📄 JSON Export: Optional JSON report for CI/CD integration
• 🗜️ Compression: Automatic compression of exported data
• 📦 Versioning: Automatic versioning of exports with restore metadata

Quick Start

composer require zaeem2396/schema-lens
php artisan schema:preview database/migrations/your_migration.php

📖 For detailed usage instructions, testing scenarios, and examples, see USAGE.md

Installation

composer require zaeem2396/schema-lens

The package supports:

• PHP 8.1+
• Laravel 10.x, 11.x, and 12.x

Configuration

Publish the configuration file (optional):

php artisan vendor:publish --tag=schema-lens-config

This will create config/schema-lens.php with the following options:

return [
    'export' => [
        'row_limit' => env('SCHEMA_LENS_EXPORT_ROW_LIMIT', 1000),
        'storage_path' => 'app/schema-lens/exports',
        'compress' => env('SCHEMA_LENS_COMPRESS_EXPORTS', true),
    ],
    'output' => [
        'format' => env('SCHEMA_LENS_OUTPUT_FORMAT', 'cli'),
        'show_line_numbers' => env('SCHEMA_LENS_SHOW_LINE_NUMBERS', true),
    ],
];

Usage

Basic Usage

Preview a migration file:

php artisan schema:preview database/migrations/2024_01_01_000000_create_users_table.php

Or use a relative path from the migrations directory:

php artisan schema:preview 2024_01_01_000000_create_users_table.php

JSON Output

Generate a JSON report for CI/CD:

php artisan schema:preview database/migrations/2024_01_01_000000_create_users_table.php --format=json

The JSON report will be saved to storage/app/schema-lens/report.json by default.

Skip Data Export

If you want to preview without exporting data (even if destructive changes are detected):

php artisan schema:preview database/migrations/2024_01_01_000000_create_users_table.php --no-export

Safe Migration (with auto-backup)

Run migrations with automatic destructive change detection and data backup:

php artisan migrate:safe

Options:

• --force - Force the operation to run in production
• --seed - Run seeders after migration
• --step - Run migrations one at a time
• --pretend - Dump the SQL queries that would be run
• --no-backup - Skip data backup for destructive changes

This command:

1. Analyzes all pending migrations for destructive changes
2. Automatically backs up affected data before proceeding
3. Asks for confirmation if destructive changes are detected
4. Runs the actual migration

What It Detects

Schema Changes

• Tables: Create, modify, drop
• Columns: Add, modify, drop, rename
• Indexes: Add, drop
• Foreign Keys: Add, drop
• Engine: Changes
• Charset: Changes
• Collation: Changes

Destructive Operations

The following operations are flagged as destructive:

• dropTable() / dropIfExists()
• dropColumn()
• dropIndex()
• dropForeign()
• renameColumn()
• Constraint removals

Data Export

When destructive changes are detected, Schema Lens automatically:

1. Exports affected table/column data to CSV and JSON
2. Compresses exports (if enabled)
3. Versions the export with metadata
4. Creates restore instructions

Export Structure

storage/app/schema-lens/exports/
└── 2024_01_01_000000_create_users_table_2024-01-15_10-30-45_v0001/
    ├── users.json
    ├── users.csv
    ├── users.zip (if compression enabled)
    └── restore_metadata.json

Restore Metadata

Each export includes a restore_metadata.json file with:

• Export version and timestamp
• Migration file reference
• Affected tables and columns
• Restore instructions
• File paths for all exported data

Output Examples

CLI Output

╔══════════════════════════════════════════════════════════════╗
║          Schema Lens - Migration Preview Report            ║
╚══════════════════════════════════════════════════════════════╝

📊 SUMMARY
────────────────────────────────────────────────────────────
Tables:        1
Columns:       5
Indexes:       2
Foreign Keys:  1
Engine:        0
Charset:       0
Collation:     0

⚠️  DESTRUCTIVE CHANGES: 1

⚠️  DESTRUCTIVE CHANGES DETECTED
════════════════════════════════════════════════════════════

  Risk Level: HIGH
  Operation:  column:drop
  Line:       45
  Tables:     users
  Columns:    users.email

📋 DETAILED CHANGES
────────────────────────────────────────────────────────────

📦 TABLES:
  ➕ [Line 12] Will create new table 'users'

📝 COLUMNS:
  ➕ [Line 15] Will add new column 'users.id'
  ➕ [Line 16] Will add new column 'users.name'
  🔴 [Line 45] Will DROP column 'users.email' (DESTRUCTIVE)

🔄 ROLLBACK SIMULATION
────────────────────────────────────────────────────────────
  Risk Level: HIGH
  Columns Affected: users.email

JSON Output

{
    "timestamp": "2024-01-15T10:30:45+00:00",
    "summary": {
        "tables": 1,
        "columns": 5,
        "indexes": 2,
        "foreign_keys": 1,
        "destructive_changes_count": 1,
        "has_destructive_changes": true
    },
    "diff": {
        "tables": [...],
        "columns": [...],
        "indexes": [...],
        "foreign_keys": [...]
    },
    "destructive_changes": [...],
    "rollback": {...},
    "exports": [...]
}

Rollback Simulation

Schema Lens analyzes the down() method of migrations to:

• Show rollback SQL statements
• Identify dependency break risks
• Warn about foreign key constraints
• Highlight affected tables and columns

Requirements

• PHP 8.1+
• Laravel 10.x, 11.x, or 12.x
• MySQL 5.7+ or MariaDB 10.2+
• Access to information_schema database

Environment Variables

You can configure Schema Lens using environment variables:

SCHEMA_LENS_EXPORT_ROW_LIMIT=1000
SCHEMA_LENS_COMPRESS_EXPORTS=true
SCHEMA_LENS_OUTPUT_FORMAT=cli
SCHEMA_LENS_SHOW_LINE_NUMBERS=true

CI/CD Integration

GitHub Actions Example

- name: Preview Migration
  run: |
    php artisan schema:preview database/migrations/2024_01_01_000000_create_users_table.php --format=json
    cat storage/app/schema-lens/report.json | jq '.destructive_changes'

GitLab CI Example

migration-preview:
  script:
    - php artisan schema:preview database/migrations/2024_01_01_000000_create_users_table.php --format=json
    - |
      if [ $(cat storage/app/schema-lens/report.json | jq '.summary.has_destructive_changes') = "true" ]; then
        echo "⚠️ Destructive changes detected!"
        exit 1
      fi

Limitations

• Currently supports MySQL/MariaDB only
• Requires direct database connection (no cloud services)
• Schema introspection uses information_schema tables
• Migration parser supports standard Laravel migration syntax

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This package is open-sourced software licensed under the MIT license.

Author

zaeem2396

GitHub: @zaeem2396

Support

For issues, questions, or contributions, please open an issue on GitHub.