Laravel Multi Database Commands Laravel Package

Getting Started

• Install with composer require henryavila/laravel-multi-database-commands. v2.1.0 adds Laravel 11 support (PHP 8.2+), alongside the existing Laravel 10 line; there are no documented breaking changes from v2.0.0, so upgrading is a composer update away. On Laravel 11, run php artisan vendor:publish --tag=multidatabase-config (or check config/multidatabase.php) to review the connection list.
• Look first at config/multidatabase.php (or config/database.php if the package reads connections directly). This is where you declare which connections the *:all-style Artisan commands should iterate. The default typically mirrors every entry in config/database.php, which is rarely what you want in production.
• First use case: register a second connection (e.g. analytics, a tenant shard, or a read replica), then run php artisan migrate:all (or the package's migrator command) to push the same migrations across every configured connection in one shot. Verify with php artisan migrate:status:all before trusting it in any shared environment.

Implementation Patterns

• Fan-out migrations for multi-tenant shards. Enumerate tenant connections dynamically in config/multidatabase.php (or resolve them in a service provider), then run the package's migrate:all / migrate:fresh:all commands. This is the core workflow the package exists for — one artisan invocation, N databases.
• CI/CD fan-out. Wire php artisan migrate:all --force into your deploy pipeline for environments with multiple databases. Because the command loops connections sequentially, a failure on one connection usually halts or surfaces immediately — pair it with your existing migrate health checks per connection.
• Seeding parity. Use the db:seed:all (or equivalent) command to keep reference/lookup data synchronized across connections without writing custom loops.
• Tenant onboarding. Call the package commands programmatically via Artisan::call('migrate:all', [...]) inside a job or tenant-provisioning service so new tenant databases get the current schema on creation.
• Local dev parity. Developers with a single local DB can leave the connection array minimal; CI and staging can extend it. Keep the config environment-aware (app()->environment() checks) so local runs don't accidentally hit replica or shard connections.
• Verification loop. After migrate:all, run the status command across connections and diff the results in your own script — the package gives you the fan-out, not a cross-connection drift report.

Gotchas and Tips

• Config caching bites. Connection arrays generated dynamically (e.g. from a tenants table) must be resolved at runtime, not baked into config/multidatabase.php, or php artisan config:cache will freeze them. Resolve tenant lists in a service provider or pass them at call time instead.
• Ordering is not guaranteed to be meaningful. The commands iterate in config order. If migrations have cross-database foreign keys (rare but real), you control correctness by ordering the array — the package will not infer dependencies.
• No transactional safety across connections. A failure mid-fan-out leaves earlier connections migrated and later ones untouched. Design migrations to be idempotent and re-runnable (migrate:all again should be safe), and always take a snapshot before running migrate:fresh:all anywhere non-local.
• migrate:fresh:all is destructive across every connection. Confirm the connection list is scoped (e.g. excludes a production/archive connection) before running. A stray default config is the most common way this goes wrong.
• Laravel 11 upgrade specifics. v2.1.0 is a compatibility release, not a feature release — there are no new commands in this version. If you're upgrading the host app to Laravel 11, update the package in the same deploy; older versions won't be tested against L11 and the console kernel/command registration changes may cause the commands not to surface. After upgrading, run php artisan list and confirm the *:all commands are present.
• Command discovery on Laravel 11. L11's slimmer console kernel auto-discovers commands from the package's service provider; if a command disappears post-upgrade, clear bootstrap/cache and php artisan optimize:clear before assuming a package regression.
• Debugging a stuck fan-out. Add -v to see per-connection output; the commands typically echo the connection name before each run, which is your fastest signal for which connection is failing.
• Seeder class resolution. Seeders reference classes by namespace; if you use a shared seeder across tenants, ensure DatabaseSeeder resolves correctly per connection rather than referencing a connection-pinned model.