Webman Migrations Laravel Package

Getting Started

leekung/webman-migrations gives Webman the migration workflow Laravel developers already know: timestamped migration files, up()/down(), and a migrations tracking table — running against Webman's webman/database (Illuminate) connection layer instead of Artisan.

Minimal steps:

1. composer require leekung/webman-migrations and make sure webman/database is installed with connections defined in config/database.php (the array shape is the same as Laravel's connections).
2. Open the plugin config first — config/plugin/leekung/webman-migrations/app.php (or plugin/leekung/webman-migrations/config/). This is where enable, the migrations path (typically database/migrations), and the connection name are set. This file is the single most important thing to read before your first run.
3. Confirm the registered commands with php webman — expect migrate, migrate:rollback, migrate:status, and a make:*-style generator. There is no php artisan; everything is a Webman console command.
4. Create database/migrations if it does not exist, drop in your first migration, and run php webman migrate.

First real use case: baselining an existing Webman app. Most teams adopting this package already have a hand-built schema. Write one "initial" migration that reproduces the current schema (or import a mysqldump and mark it as run), then let every subsequent change go through migrate. That immediately gives you a rollback path and a schema history in git, which is the whole point.

Implementation Patterns

Write migrations exactly like Laravel's. Use the Illuminate\Database\Schema\Blueprint API — Schema::create, Schema::table, $table->foreignId('user_id')->constrained(), $table->softDeletes(). Because webman/database is Illuminate under the hood, muscle memory transfers directly; the only difference is the entry point.

One logical change per file, never edit an applied migration. Same discipline as Laravel. If you got it wrong in staging, write a corrective migration rather than rewriting history — teammates and CI will already have the old checksum-less version applied.

Deploy-time execution. Run php webman migrate as a release step before (re)starting workers, not after. In a container pipeline this is typically an init/pre-start hook; in a VM setup it is part of your deploy script. Keep migrate:status in your health/debug tooling so on-call can see whether the schema is where it should be.

Connection-per-environment. Point the plugin at a named connection from config/database.php rather than hardcoding credentials. That lets the same migration set run against MySQL locally, a throwaway database in CI, and production without edits — and lets you deliberately run migrations against a read-write connection while the app's default connection may differ.

CI pattern. Spin up MySQL as a service, run php webman migrate from a clean database, then run your test suite against the migrated schema. This catches broken down() methods, ordering assumptions, and index-length issues before they reach a deploy.

Modular apps. If you split functionality into Webman plugins, register additional migration paths per plugin so each module owns its schema. This is the main extension point worth configuring early — retrofitting it later means reordering every migration.

Seeders and fixtures. Keep seed data in separate scripts or commands rather than in migrations; migrations should be pure DDL/DML that is safe on every environment, and demo data is not.

Gotchas and Tips

Read the 2.0.1 diff, not the changelog. The release notes consist only of a compare link (2.0.0...2.0.1), so there is no documented feature or fix. It is a patch bump, which normally means no API change — but since nothing is described, review the actual diff before upgrading in a production app, and pin the version in composer.json rather than floating on ^2.0.

Long-running workers vs. schema changes. Webman keeps processes alive; an open worker holds a live PDO connection and possibly cached metadata. Never run a destructive migration against a live pool — migrate, then php webman reload/restart. For column renames or drops, plan a two-phase deploy (add + backfill, then remove) rather than a single breaking change.

MySQL implicit commits. DDL statements commit implicitly, so a migration that fails halfway leaves the schema partially applied and the migrations row unwritten. Wrap multiple statements defensively, keep migrations small, and know that migrate:rollback will not "undo" a half-applied file cleanly.

Shared database with a Laravel app. Both frameworks default to a table named migrations and a batch column. If a Laravel app and a Webman app share one database, set a distinct repository table name for one of them — otherwise each will see the other's migrations as applied and skip real work.

down() is the part people skip. Review rollbacks in code review with the same rigor as up(). Prefer reversible operations; for genuinely destructive changes, make down() throw rather than silently drop data, so a rollback in production fails loudly.

Foreign keys need matching types and InnoDB. A bigint unsigned mismatch between foreignId and an existing int primary key is the most common first-migration failure — check the parent table before writing the child.

Config changes need a reload. Editing the plugin's app.php (path, connection, table name) has no effect until the process reloads; symptoms look like "my config is ignored." php webman reload (or a full restart) resolves it.

Timestamps convention. Use $table->timestamps() rather than custom created_at types so Eloquent models in Webman behave identically to Laravel's — mixing int timestamps with datetime columns is a recurring source of silent nulls.