Db Migration Laravel Package

Technical Evaluation

Package identity correction (first-order concern). The release notes describe yiisoft/db-migration 2.2.0 — a Yii Framework migration engine built on yiisoft/db, driven by yii-console commands, with its own CLI entry point at ./vendor/bin/yii-db-migration. It is not a Laravel package. Any assessment framed as "Laravel/PHP package" must be split into two conclusions: (a) as a PHP migration tool it is credible and actively maintained; (b) as a Laravel dependency it is a poor architectural fit because Laravel ships Illuminate\Database\Migrations with first-class Artisan, schema-builder, and rollback semantics. Treat this as a Yii/standalone-PHP candidate, not a Laravel one, unless the intent is a mixed-framework estate.

Architecture fit. The package is a thin, purpose-built layer: it discovers migration files, applies them through yiisoft/db's connection abstraction, and records applied versions in a history table. 2.2.0 strengthens this core rather than adding surface area:

• Multi-database with per-database migration history (#360, #366, #371) is the headline. This moves the package from "one migration namespace per application" to "named databases, each with its own version ledger, selectable via --db." For a TPM this is the difference between supporting a single-monolith deployment story and supporting sharded, multi-tenant, or read/write-split topologies where independent schemas evolve on independent schedules.
• migrate:mark (#363, #373) enables baselining — writing a version into history without executing it. This is the standard operational escape hatch for adopting an existing database, restoring from a dump, or recovering a migration that was applied out-of-band. Its value is real; so is its capacity for harm.
• Configurable transaction mode + --transactional / --no-transactional (#367) acknowledges that DDL-in-transaction is not portable. MySQL/MariaDB implicitly commit DDL, so a "transactional migration" there is a partial guarantee at best. Making this explicit at generation time prevents a class of silent-failure incidents where a migration half-applies and the history row is or isn't written.
• Friendly error without a config file (#255) is minor but signals attention to the first-run experience, which is a leading indicator of support-ticket volume.

Integration feasibility. Low friction inside a Yii app: composer require, a config file, a console entry point. Outside it — Laravel, Symfony, plain PHP — feasibility drops sharply. You would be wiring yiisoft/db alongside (or instead of) an existing connection layer, reimplementing the console invocation, and owning the impedance mismatch between two migration ledgers. That is a net-new integration project, not an adoption decision.

Technical risk. Three risks dominate. First, framework-ecosystem lock-in: adopting this in a Laravel codebase means running two migration systems or discarding Laravel's — both are expensive and hard to reverse. Second, migrate:mark as an unguarded footgun: it is a baseline/recovery tool that, if run against the wrong --db or wrong version, silently desynchronises history from actual schema, and the failure surfaces later as a failed migration on a table that already exists. Third, transaction mode drift: the new per-migration-generation flag means two developers can produce migrations with different atomicity assumptions in the same repo, and the difference is invisible in review unless it is policy.

Key questions.

1. Is there any Laravel codebase actually in scope, or is "Laravel/PHP" shorthand for a PHP estate that includes Yii? The answer changes the recommendation entirely.
2. What PHP and yiisoft/db versions does 2.2.0 require, and does that align with the runtime fleet? (Verify from composer.json, not the changelog.)
3. Does the multi-DB history feature require separate history-table configuration per database, or is naming implicit? This determines migration effort for existing installs.
4. Is migrate:mark intended to be permission-gated in production, or is it a developer-only command? Absent a documented guard, we must supply one.
5. Which database engines are in scope? Transaction mode must be policy-set per engine, not left to individual authors.

Integration Approach

Stack fit. Green light only for: (i) existing Yii 2 / Yii 3 applications, and (ii) standalone PHP services already using yiisoft/db where no competing migrator exists. Red light for Laravel — do not introduce a second migration engine alongside Illuminate\Database\Migrations; the overlap is near-total and the reconciliation cost is permanent. If the org is Laravel-centric and this came up as a candidate, the correct output of this evaluation is a documented no, with the multi-DB and baselining needs mapped onto Laravel's own --database connection targeting and a hand-rolled baseline command.

Migration path (2.1.1 → 2.2.0). This is a minor, semver-compatible release: new features and enhancements, no removals or deprecations called out in the notes. Upgrade risk is low and should be a routine composer update. Existing single-database setups should be unaffected, since --db is additive and the default path is unchanged. Validate this claim rather than assume it: the config schema and history-table naming are the two places an additive feature can still break an existing install.

Compatibility and prerequisites.

• Confirm PHP and yiisoft/db constraint changes in composer.json; a bumped minimum PHP is the most common reason a "minor" release stalls mid-fleet.
• Confirm the console runner version expected by ./vendor/bin/yii-db-migration; the friendlier error in #255 implies the binary's bootstrap changed, which is exactly where a minor release can alter exit codes — and CI scripts assert on exit codes.
• For multi-DB: enumerate every named database, confirm each gets a distinct history ledger, and decide whether a single command can target all of them (fan-out) or must be invoked per --db.

Sequencing.

1. Upgrade the library (2.1.1 → 2.2.0) with no behaviour change; run the existing suite and a dry-run against a staging clone. Low effort, unblocks everything else.
2. Set transaction-mode policy before anyone uses the new flags. Pick a default in config, document it per engine (--no-transactional as the forced default for MySQL DDL), and treat per-migration overrides as requiring reviewer sign-off.
3. Adopt multi-DB incrementally. Start with one non-critical secondary database to prove the separate-history model, then expand. Do not convert the primary database's history ledger in the same change.
4. Restrict migrate:mark to a break-glass path. Do not expose it in standard runbooks; require an incident or onboarding ticket, a captured pre-state, and a second reviewer.
5. Update CI and runbooks to pass --db explicitly rather than relying on defaults, so that a future default change cannot silently retarget a deployment.

Operational Impact

Maintenance. Low and improving. Active maintainers (@samdark, @vjik) with a steady release cadence, a documented changelog, and issue-linked changes are the signals that matter for a dependency you intend to keep for years. Budget for the ordinary cost of tracking a PHP dependency — quarterly review of minor releases, annual check of major-version direction — not for heroic maintenance.

Support. Two support surfaces. The first is the tool itself: migration failures are high-severity by nature, and the debugging path runs through Yii's console and yiisoft/db connection semantics. Ensure at least one engineer holds that knowledge; it does not transfer from Laravel experience. The second is policy support: once --db and migrate:mark exist, engineers will use them, and without a written rule about which database a command defaults to and when baselining is permitted, you will field incidents that are procedural rather than technical.

Scaling. The multi-DB feature is the scaling story and it is meaningfully better than 2.1.x. It supports independent schema lifecycles per named database, which is what multi-tenant and service-per-schema topologies need. Note the limits: this is not a distributed migration orchestrator. There is no built-in lock coordination across databases, so concurrent deploys targeting the same --db still rely on the underlying database's advisory locking or on your deploy pipeline serialising the step. Treat migration execution as a single-writer activity and enforce it in the pipeline, not in hope.

Failure modes.

• Desynchronised history via migrate:mark. Wrong version or wrong --db writes a history row for a schema that was never applied. Symptom: subsequent migrations fail on "table already exists" or skip needed DDL. Mitigation: break-glass gating, pre/post schema diff, reviewer requirement.
• Wrong-database execution. A missing --db on a multi-database setup applies migrations to the default connection. Symptom: a database left stale while history claims otherwise. Mitigation: always pass --db explicitly in CI and runbooks; consider a pipeline check that rejects invocations without it.
• Partial application under --no-transactional. A migration failing mid-file leaves the schema in an intermediate state with no automatic rollback. Symptom: manual repair. Mitigation: transaction-mode policy per engine, small idempotent migrations, forward-fix discipline over rollback.
• Transaction mode assumed but not delivered. Authors mark a migration transactional on MySQL, DDL implicitly commits, and the guarantee evaporates silently. Symptom: the failure only appears during an incident. Mitigation: enforce engine-appropriate defaults in config so the flag is rarely used manually.
• Two-migrator divergence (if adopted alongside Laravel). Symptom: duplicated schema definitions and drift. Mitigation: reject the adoption in Laravel contexts up front.

Ramp-up. For a Yii or standalone-PHP team: roughly a day for basic use, a week to internalise multi-DB history and transaction semantics safely. For a Laravel team: not a ramp-up at all — it is a framework-context switch, which is why the recommendation is to decline. The productive investment is not training on the CLI but writing the two short policy documents — transaction-mode defaults per engine, and baselining authority — that make the new 2.2.0 capabilities safe to have in the toolbox.