Upscheme Laravel Package

Getting Started

• Install via Composer: composer require aimeos/upscheme
• The package provides a console command upscheme to manage database schema evolution without relying on Laravel’s built-in migrations
• First use case: quickly create a new schema file by running php artisan upscheme:make CreateUsersTable—this generates a PSR-4 compliant PHP file in database/upscheme/
• Schema definitions use a fluent, table-agnostic API (inspired by Doctrine DBAL), allowing cross-database portability
• Unlike Laravel migrations, changes are declared declaratively, and upscheme computes the difference to apply automatically

Implementation Patterns

• Define all table schemas in dedicated files under database/upscheme/ using the Table and Column classes
• Use Upscheme::run() in AppServiceProvider::boot() to auto-apply schema changes on application startup (e.g., in dev/staging)
• For production, prefer php artisan upscheme:apply as a deployment step to preview and apply migrations explicitly
• Supports partial schema definitions—only define the target state; Upscheme calculates needed ALTER TABLE, ADD COLUMN, DROP INDEX, etc.
• Use Schema::table('table', fn ($table) => $table->...) for imperative updates if fine-grained control is needed (fallback to traditional migration style)
• Can be combined with Laravel’s migrations—just keep them in separate directories to avoid confusion

Gotchas and Tips

• Case sensitivity: Table/column names are lowercased unless quoted explicitly; avoid mixing cases in SQL identifiers
• Upscheme doesn’t track applied changes in migrations table—its own tracking happens via schema_version table (ensure it’s created first, ideally via upscheme:apply)
• If you rename a column or table, Upscheme may interpret it as a drop + add; use renameColumn() and renameTable() helpers if supported by the DB platform
• PostgreSQL users: enable doctrine/dbal’s platform option for accurate DDL generation (e.g., UUID support, sequences)
• Debug issues by running php artisan upscheme:show to preview the schema diff before applying
• Avoid manual DB edits—Upscheme expects full control over schema state; mixing manual changes can break diffs
• Extensibility: Register custom column types via Column::register('custom_type', Closure::fromCallable([...])) if needed for legacy DBs