Skip to content

[2.x] feat(core): allow to run migrations in isolation - #4864

Open
DavideIadeluca wants to merge 3 commits into
flarum:2.xfrom
glowingblue:di/isolated-migrations
Open

[2.x] feat(core): allow to run migrations in isolation#4864
DavideIadeluca wants to merge 3 commits into
flarum:2.xfrom
glowingblue:di/isolated-migrations

Conversation

@DavideIadeluca

@DavideIadeluca DavideIadeluca commented Jul 31, 2026

Copy link
Copy Markdown
Contributor

Docs PR at flarum/docs#566

Fixes #0000
When Flarum is running in a multi container environment, it's possible that during startup (like during a deployment) multiple containers try to run new migrations at the same time. What can happen is that two containers are provisioned at nearly the identical time, both containers invoke Flarums Migrator and detect that there are new outstanding up migrations, one container successfully up migrates, the other container tries to up migrate the same new migrations, however will exit because e.g. a column already exists.

This becomes an issue in hosting environments like AWS ECS where a non successful exit code of just one single container means that the whole deployment gets rollbacked even though one container ran the new migration successfully.

Changes proposed in this pull request:

  • Allows commands to implement Laravels Isolatable interface to allow running them in isolation.
  • Implement this interface for the MigrateCommand

Reviewers should focus on:
As Flarum doesn't use Laravels Migrator, this PR (re) implements it similarly to how Laravel implements it. See more information about how Laravel does it at https://laravel.com/docs/13.x/migrations#isolating-migration-execution and https://laravel.com/docs/13.x/artisan#isolatable-commands

The new input option isn't used by default. However we can consider if we wanna pass this input in the UpdateController which invokes the MigrateCommand. From what I can tell there should be no negative side effects but technically it could be considered a breaking change which at this point may be undesired.

My recommendation tends to not use the new input for the migration command by default. The issue which this PR addresses only occurs in multi container environments where a vendor might already have a heavily customized setup where the migration command is run differently and can be changed to use the --isolated input

About the PHPStan Stub:
Laravel's CommandMutex docblock demands an Illuminate\Console\Command, but its implementation only duck-types the command (getName() and method_exists checks), so Flarum's Symfony-based commands are fully compatible at runtime.

Screenshot

Necessity

  • Has the problem that is being solved here been clearly explained?
  • If applicable, have various options for solving this problem been considered?
  • For core PRs, does this need to be in core, or could it be in an extension?
  • Are we willing to maintain this for years / potentially forever?

Confirmed

  • Frontend changes: tested on a local Flarum installation.
  • Backend changes: tests are green (run composer test).
  • Core developer confirmed locally this works as intended.
  • Tests have been added, or are not appropriate here.

Required changes:

  • Related documentation PR: (Remove if irrelevant)

@DavideIadeluca
DavideIadeluca marked this pull request as ready for review July 31, 2026 07:04
@DavideIadeluca
DavideIadeluca requested a review from a team as a code owner July 31, 2026 07:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant