Getting Started

Install via Composer: composer require yiisoft/db-migration. The 2.2.0 release adds a friendly error when running ./vendor/bin/yii-db-migration without a configuration file, so the first thing to do is publish/copy the config template and point it at your DB connection.
Look first at the package’s migration console entry point and the config file it expects. In 2.2.0 the CLI now fails gracefully if that file is missing, which makes initial setup less mysterious.
First use case: create a migration with yii-db-migration migrate:create <name>, inspect the generated class, then run migrate:up. If you are coming from Laravel, map Laravel’s php artisan migrate concepts onto this package’s console commands; the workflow is similar but the command vocabulary and config are Yii-specific.
For multiple databases, define named DB connections in config and immediately test --db=<name> against a scratch database. 2.2.0 gives each named database its own migration history table, so verify the history table is created/used per DB rather than shared.

Implementation Patterns

Multi-database migrations. Use the new named-database support (#360, #366, #371) to keep separate migration histories per connection. Run commands with --db=<name> and keep one migration directory per logical database where possible. This is the closest equivalent to Laravel’s per-connection migration setup, but here the history is explicitly separated.
Marking history without executing. migrate:mark (#363, #373) is useful for baselining an existing schema or syncing a fresh environment to a known version. Pattern: dump/restore production schema, then run migrate:mark <version> so future migrate:up runs only apply new migrations.
Transactional control. Use the new configurable transaction mode and --transactional / --no-transactional flags (#367) when generating migrations. For databases or DDL statements where transactions are not supported or cause implicit commits, generate with --no-transactional; for normal DML migrations, keep the default transactional behavior.
CI/CD pattern. In deployment scripts, run migrate:up --db=<name> per named database, then run application deploy steps. Because histories are separate, a failure on one DB does not corrupt another DB’s history, but your script should still stop on first failure.
Local development. Use migrate:create with the transactional option that matches the target engine. For MySQL DDL-heavy migrations, prefer non-transactional generation to avoid confusing partial-failure behavior.

migrate:mark does not execute migrations. It only moves history. Confirm the target schema actually matches the version you are marking, or later migrations may assume structures that do not exist.
Named databases are not the same as Laravel connections. The --db option selects a named database with its own migration history. If you omit --db, commands target the default database; do not assume they fan out across all configured databases.
Transaction mode is per generated migration, not a global runtime switch. Check the generated migration class after using --transactional / --no-transactional. Existing migrations are unaffected.
Configuration file is mandatory for CLI. The friendly error in 2.2.0 is an improvement, but it means you must wire the config before any command works. Keep the config path consistent across local, CI, and production.
Debugging failed migrations. Because histories are separate per named DB, inspect the correct history table for the DB you ran against. A migration that appears “missing” may simply have been recorded under another database’s history.
Extension point. If you need custom migration behavior, subclass or wrap the migration base class and override transaction handling rather than fighting the CLI flags. The new configurable transaction mode is the intended seam for engine-specific behavior.