Laravel Online Migrator Laravel Package

Technical Evaluation

Architecture fit

• The package targets a real and well-defined seam: Laravel's migration pipeline is one of the few places where a team can legitimately swap behavior (custom Migrator, custom schema grammar, or a wrapping Artisan command) without touching application code. Replacing a blocking ALTER TABLE with Percona pt-online-schema-change (and possibly gh-ost) is the right shape of solution for large InnoDB tables in MySQL.
• Fit is narrow by design. It presumes MySQL/MariaDB + InnoDB, a table large enough that a plain ALTER is an outage, and an execution environment that can shell out to a binary. There is no meaningful path for PostgreSQL (different tooling: CREATE INDEX CONCURRENTLY, different locking model), SQL Server, or SQLite — so the value is zero on polyglot data layers.
• The architectural crux is that the real dependency graph extends outside Composer: PHP → shell → Percona Toolkit → DB host. That makes binary provenance, network egress, DB credentials, and image contents part of your deploy topology, not just a package version constraint.

Integration feasibility

• Feasible, but not a composer require and go. Prerequisites: pt-osc installed on whatever machine runs artisan, a DB user with privileges to create/drop triggers, create/drop the shadow table, and read replication status, plus a plan for when the binary version moves under you.
• Version risk dominates. A last release of 2020-11-25 places it in the Laravel 6/7/8 window. Laravel 9 reworked schema operations away from doctrine/dbal, and 10/11/12 continued that direction; assume a compatibility fork is required before this runs on a current LTS. Budget a timeboxed spike to prove or kill that, not a delivery plan.
• Managed-database reality check comes first: RDS/Aurora/Cloud SQL constrain SUPER, trigger creation, and binlog settings in ways that materially affect pt-osc. Confirm privileges on the actual target before designing around the tool.

Technical risk

• Maintenance signal is weak: 44 stars, a single-release history, no visible downstream base. The blast radius of a defect here is production schema, so source review and a fork you control are prerequisites, not optional diligence.
• Correctness surface is subtle: wrapping/parsing DDL, mapping down() to a safe inverse, multi-statement migrations, index-name collisions with existing ghost/trigger artifacts, and foreign keys (--alter-foreign-keys-method, --preserve-triggers).
• Failure is non-atomic and unfamiliar to most Laravel teams. A killed pt-osc can leave triggers and a _table_new shadow table behind; MySQL has no transactional DDL, so "migration failed" can mean "schema is in an intermediate state."
• Performance backpressure: chunked copy roughly doubles disk usage and adds write amplification; on a busy primary it can push replica lag past read-path thresholds.

Key questions

• Which Laravel and PHP versions are actually supported today, and is the doctrine/dbal path still required for current framework versions?
• Does it intercept the entire migration run or opt in per migration? Can vanilla migrate remain in use for small tables?
• How is down() handled, and exactly what residue does a failed cutover leave, plus how is it cleaned up?
• Is gh-ost a first-class driver or a stub? Are --dry-run and --no-drop-old-table styles of safeguards exposed?
• What privileges does it demand, and does it work against our specific managed MySQL tier?
• Who owns a botched schema swap — is there a documented restore-and-verify path, and has anyone rehearsed it?

Integration Approach

Stack fit

• Good fit only when all three hold: Laravel on MySQL 8 (or 5.7), at least one table where a plain ALTER is a genuine outage (>~10–20M rows or a hot, heavily written table), and a deploy pipeline with a step that can reach the DB host.
• Poor fit where migrations run inside an ephemeral app container. Installing Percona Toolkit into the web image is possible but adds a heavyweight, privileged binary to your runtime artifact for something used minutes per quarter.
• Cleanest placement is a dedicated migration job — bastion, sidecar, or CI step — with its own pinned image, separate from the application runtime.

Migration path

• Phase 0 (spike, ~1 sprint): fork the repo, bump Laravel/PHP constraints, run against a staging replica with production-like volume. Do not touch production; the exit criterion is "a large-table migration completes cleanly and can be repeated."
• Phase 1: vendor the fork under a private namespace or VCS Composer repository; pin the pt-osc version and hash; add a CI smoke test that performs one trivial online migration per build.
• Phase 2: introduce as opt-in for a single already-risky table behind a flag; keep standard migrate for everything else. Prove the runbook, not the tool.
• Phase 3: only if Phase 2 is uneventful, standardize for large-table DDL. Otherwise keep it as a manually invoked tool with a written checklist and record the decision.

Compatibility

• Pin PHP, Laravel, MySQL, and pt-osc versions as one tested tuple and document it in the repo README of your fork.
• Verify behavior both with and without doctrine/dbal installed, since that changes the SQL the schema builder emits.
• Explicit test matrix: add column, drop column, add index, add unique index, change column type, rename column, and a migration containing a data UPDATE alongside DDL.

Sequencing

• Separate schema change from code deploy (expand → migrate → backfill → contract) so a failed cutover never leaves running code expecting a column that does not exist.
• Run the first production use in a low-traffic window even though it is "online" — you are rehearsing the runbook, not just the binary.
• Rehearse restore (snapshot restore or replica promotion) before the first use. A rollback plan that has never been executed is a hypothesis.
• Enforce a single migration runner at a time; add a lock so two deploys cannot start competing online DDL against the same table.

Operational Impact

Maintenance

• Assume you own the code. Upstream is dormant; the realistic posture is a maintained internal fork with one or two named owners who understand the internals.
• Recurring cost: every Laravel major upgrade now includes "patch the online migrator," a tax the rest of the team does not pay and will not anticipate in planning.
• Binary drift is a second maintenance axis — a distro or OS upgrade that bumps Perl/Percona Toolkit can change behavior silently. Pin, hash, and re-test.

Support

• No vendor, no commercial support, no SLA. Internal documentation — runbook, failure catalog, restore steps, contact tree — is a deliverable of the integration, not an afterthought.
• Define the paging route explicitly. A failed online DDL is a database incident, not an application incident; it must not land in a queue owned by people who cannot read a replication status.

Scaling

• It scales to large tables — that is the entire value proposition — but cost is roughly linear in table size and write rate, so duration can be hours. Plan deploys around that rather than pretending it is instantaneous.
• Concurrency limit: one online DDL per table. Batch/step execution and parallel deploys need coordination or they will race.
• The real capacity constraints are replica lag and free disk (roughly double the table). Size both before the first run, and set abort thresholds for each.

Failure modes

• Tool exits nonzero after creating triggers and a shadow table → residue that blocks the next attempt and can confuse later migrations.
• Lock-wait timeout at cutover → a brief write stall that presents to users as an outage.
• Replica lag spike during the copy → degraded read path and stale reads in code paths that assume freshness.
• Disk exhaustion from the doubled table on a volume nobody resized.
• Bookkeeping drift: migration recorded in the migrations table but DDL never applied, or applied and not recorded. Needs an explicit reconciliation check, not trust.
• Conflicts with tables that already carry application triggers or foreign keys, which pt-osc handles poorly or refuses outright.
• Human error: someone runs vanilla migrate and gets the blocking ALTER anyway. The tool must be the only path, enforced in the pipeline.

Ramp-up

• Engineering: ~2–3 days to understand the package plus the expand/contract pattern, plus several more days for the fork and compatibility work — call it one engineer for a sprint.
• Operations: meaningful DBA literacy is required (pt-osc flags, replication topology, restore drills). This is the dominant cost and none of it lives in the repository.
• Onboarding bar: anyone permitted to run a production migration should be able to explain what happens at cutover, what the abort looks like, and how to verify the resulting schema.
• Decision framing: worth the dependency only if large-table DDL is a recurring, scheduled pain and you have (or will fund) database expertise. For a team with one big table and no DB specialist, a documented manual pt-osc invocation with a checklist captures most of the benefit at a fraction of the maintenance and framework-upgrade risk.