Laravel Online Migrator Laravel Package

Getting Started

This package is a niche operational tool: it helps you apply MySQL DDL through external online schema-change tooling, typically Percona Toolkit’s pt-online-schema-change, instead of issuing a blocking ALTER TABLE. It is not a general-purpose replacement for Laravel migrations. Use it only for lock-sensitive changes on large production tables.

Minimal steps:

1. Check compatibility before installing. The last release was 2020, so verify the package against your Laravel and PHP versions in a throwaway branch. Inspect its composer.json constraints, then run the test suite or a staging migration before trusting it.
2. Install the external tool. On the host that will run migrations, install Percona Toolkit and confirm:

   pt-online-schema-change --version
   

3. Require and configure the package.

   composer require orisintel/laravel-online-migrator
   

   Publish the package config using the provider/tag documented in its README. Then set the MySQL connection, binary path, and any extra CLI options. Clear config cache after changes:

   php artisan config:clear
   

4. Start on staging with a real-sized table. Do not make your first run against production. Use a staging clone or a table large enough to expose lock, trigger, foreign-key, and replication issues.
5. Verify what the package actually executes. Inspect the service provider, commands, and config. Confirm whether it wraps Laravel migration classes, provides a separate online migration command, or shells out to pt-online-schema-change directly. Do not assume Schema::table() is automatically intercepted.

First useful case: adding a composite index to a large orders table without a long metadata lock.

ALTER TABLE orders
ADD INDEX orders_customer_created_idx (customer_id, created_at);

Use the package’s documented online migration entry point to apply that DDL. If the package does not expose a dry-run, run the equivalent pt-online-schema-change --dry-run --print command manually first and compare it with what the package generates.

Where to look first:

• README for supported databases, Laravel versions, required binaries, and command names.
• config/ for connection, binary path, and extra arguments.
• src/Console/Commands and the service provider for the actual execution path.
• Tests/fixtures for the expected migration syntax.
• composer.json for Laravel, PHP, and dependency constraints.

Implementation Patterns

Separate online migrations from normal migrations. Keep lock-sensitive changes in a dedicated directory, namespace, or command path so they are run deliberately, not accidentally during every local php artisan migrate. Normal Laravel migrations remain fine for small tables, new tables, seed data, and non-production work.

Use a deployment gate. Run online schema changes as an explicit CI/CD or pre-deploy step, then deploy application code. If the package integrates with php artisan migrate, gate it by environment flag so local and test environments do not try to invoke Percona Toolkit.

# Example pipeline shape, not necessarily exact package commands
php artisan migrate:online --force   # or package-specific command
php artisan migrate --force

Confirm whether the package records applied migrations in Laravel’s migrations table. If it does not, add a normal no-op migration or manually record state so the same online change is not replayed.

Keep each online change small and reversible. Prefer one index or one column change per migration. pt-online-schema-change can handle multiple clauses in one ALTER, but smaller changes are easier to throttle, observe, and roll back.

Configure conservative production options. Use package config or extra CLI args to limit load:

// Example shape only; verify keys against the published config.
return [
    'connection' => env('ONLINE_MIGRATOR_CONNECTION', 'mysql'),
    'binary' => env('PT_OSC_BINARY', 'pt-online-schema-change'),
    'options' => [
        '--chunk-time' => '0.5',
        '--max-load' => 'Threads_running=30',
        '--critical-load' => 'Threads_running=60',
        '--sleep' => '0.1',
    ],
];

Use faster settings in staging; use throttling, replication-lag checks, and off-peak windows in production.

Add observability around the command. Capture start/end time, exit code, stdout/stderr, target table, generated DDL, and migration name. Monitor MySQL SHOW PROCESSLIST, replication lag, disk space, and InnoDB metrics while it runs. A successful package command without logs is not enough for production confidence.

Run sequentially per database server. Do not parallelize online migrations on the same MySQL instance. For multi-tenant or sharded databases, loop over connections one at a time with backoff between runs.

Have a fallback plan. If the package is incompatible with your Laravel version or lacks needed hooks, wrap pt-online-schema-change in your own Artisan command and keep the package only as reference. This is often safer than fighting an unmaintained integration layer.

Gotchas and Tips

• Maintenance risk is the biggest issue. Last release was 2020 and the package has low adoption. Test against Laravel 9/10/11 and modern PHP before relying on it. Pin the version or fork it if you need fixes.
• “Online” is not zero-impact. pt-online-schema-change creates a ghost table, installs triggers, copies rows, and doubles write load during the run. It can cause replication lag, disk pressure, and trigger conflicts. Take a backup or snapshot first.
• Confirm migration state handling. If the package bypasses Laravel’s migration repository, you may need to record the migration manually or pair it with a standard no-op migration.
• Know pt-online-schema-change limits. The table generally needs a primary key or unique index. Existing triggers can conflict unless --preserve-triggers is supported and used. Foreign keys may require --alter-foreign-keys-method. Table-name length limits can also bite because of generated ghost-table names.
• Prefer raw, verified ALTER TABLE SQL. Laravel’s schema builder can generate SQL that the external tool handles poorly. Test the exact generated DDL in staging, including table prefixes and quoted identifiers.
• Watch process timeouts. PHP max_execution_time, CI job timeouts, queue worker timeouts, and deploy timeouts can kill a long-running online migration. Run it from CLI with appropriate timeouts, not from a web request.
• Config cache and binary path are common failures. If config changes do not apply, run php artisan config:clear. Verify the binary is on PATH or provide an absolute path.
• Protect credentials. Avoid putting database passwords directly in process arguments or logs. Use a restricted MySQL config file or environment configuration supported by the package.
• Debug with dry runs and MySQL state. Use pt-online-schema-change --dry-run --print where possible. Then inspect SHOW TRIGGERS, SHOW PROCESSLIST, replication status, and leftover ghost/old tables.
• Plan rollback explicitly. A down() online migration is another online DDL operation, and the package may not handle it safely. Know the reverse ALTER and test it on staging.
• Extension points are likely thin. Look for configurable extra CLI arguments, a bindable process runner, or overridable command classes. If none exist, wrap the external tool yourself rather than patching vendor code.