Filament v3 upgrade command leaves migration sequencing undefined for zero-downtime deploys

Answer

For small applications targeting zero downtime on Filament v3.2+, use a database-first, backward-compatible rollout: run additive migrations while v2 code is still live, build and publish Vite assets before switching PHP, then deploy v3 code across nodes. If you can provision a separate server pool, a blue-green cutover is preferable because it eliminates the mixed-version window entirely.

Likely Explanation

The filament:upgrade command updates Composer dependencies and publishes configuration, but it does not orchestrate migration order, asset builds, or cache clearing. During a rolling deploy, some workers may serve v2 PHP while others serve v3 PHP. If Livewire renders a component against one asset hash and the browser loads another, the mismatch produces a checksum failure. Schema changes that run while old workers are active can also cause query errors against the old schema.

Confirmed Facts

• Filament v3 internal tables such as filament_users require migrations before the panel boots.
• Livewire ties component rendering to compiled asset hashes; mismatched PHP and asset versions trigger checksum failures.
• Laravel does not automatically serialize migrations across multiple application servers.

Deployment Steps

1. Create additive migrations only. Add tables or columns. Do not rename or drop columns until all nodes run v3 code.
2. Run migrations on a single node. Serialize execution with a migration lock or single worker to prevent race conditions.
3. Build Vite assets in CI. Run npm run build before deployment and publish the public/build manifest with the release.
4. Deploy assets before PHP code. Make the new asset bundle available to the load balancer or CDN before any node serves v3 PHP.
5. Roll out v3 PHP code. Update servers one at a time or switch a blue-green pool. Keep v2 and v3 assets compatible during the window.
6. Clear configuration cache. Run php artisan config:clear after assets and code are in place.
7. Run cleanup migrations last. Remove legacy v2 columns only after every worker has stopped serving v2 code.

Verification

• Monitor application logs for checksum mismatch exceptions during the rollout.
• Confirm the public/build manifest timestamp matches the deployed PHP release on each node.
• Smoke test Filament resource create, update, and delete on every node after cutover.

Assumptions

This guidance assumes a standard Laravel/Vite setup and idempotent migrations. Destructive schema changes, such as changing a column type, require a maintenance window or full blue-green cutover because they break backward compatibility with v2 workers.

Diagnostic detail needed: Are your application servers sharing a single filesystem for public/build, or does each node deploy its own asset copy? This determines whether atomic symlinks or CI-published assets are required.