Allow migrate command subclasses to customize the migration executor

[moaddib666]

Code of Conduct

• I agree to follow Django's Code of Conduct

Feature Description

Add an executor_class attribute to the migrate management command, defaulting to MigrationExecutor, so subclasses can customize migration execution without overriding the full command implementation.

This would follow the existing migration command pattern used by attributes such as autodetector.

Problem

The migrate command currently instantiates MigrationExecutor directly inside its implementation.

This makes customization difficult for projects or third-party packages that need a custom migration executor.

Today, the practical workaround is to subclass the migrate command and copy large parts of handle() just to replace the executor construction line.

That approach is fragile because the copied logic can drift from Django upstream over time. It also makes small customizations unnecessarily expensive to maintain.

This feature would provide a small, explicit extension point while preserving the current default behavior.

Request or proposal

proposal

Additional Details

The proposed change is backwards compatible.

Existing behavior would remain unchanged because executor_class would default to MigrationExecutor.

The intended usage would be:

from django.core.management.commands.migrate import Command as MigrateCommand
from .executors import CustomMigrationExecutor

class Command(MigrateCommand):
    executor_class = CustomMigrationExecutor

This is useful for projects that need to customize migration execution behavior while still relying on Django’s standard migrate command flow.

The change also aligns with the existing composition-style pattern used in Django’s migration commands, where collaborators can be exposed as class attributes rather than hard-coded directly inside command methods.

Implementation Suggestions

Add a class-level attribute to django.core.management.commands.migrate.Command:

class Command(BaseCommand):
    executor_class = MigrationExecutor

Then replace direct MigrationExecutor construction with self.executor_class.

For example:

executor = self.executor_class(connection, self.migration_progress_callback)

For consistency, BaseCommand.check_migrations() could also resolve the executor class from the command instance when available:

executor_class = getattr(self, "executor_class", MigrationExecutor)
executor = executor_class(connections[DEFAULT_DB_ALIAS])

Tests should cover:

• migrate.Command.executor_class defaults to MigrationExecutor
• migrate.Command.handle() uses self.executor_class
• BaseCommand.check_migrations() respects a custom executor_class
• existing behavior remains unchanged when executor_class is not overridden

Documentation should mention that subclasses of the migrate command may override executor_class to customize migration execution behavior.

POC:
django/django#21358

[github-actions]

Thank you moaddib666 for sharing your idea! We have a lot of them so please be patient. You can see the current queue here.

Community instructions

For commenters, please use the emoji reactions on the issue to express support, and/or concern easily. Please use the comments to ask questions or contribute knowledge about the idea. It is unhelpful to post comments of "I'd love this" or "What's the state of this?"

Reaction Guide

• 👍 This is something I would use
• 👎 This is something that would cause problems for me or Django
• 😕 I’m indifferent to this
• 🎉 This is an easy win

[codingjoe]

@nessita the PR was a five line change to improve inheritance which is generally welcome, right? At most I could argue for a cleanup ticket. Can you share your concerns to get a full picture?

[wspjoy2011]

We maintain a subclass of the migrate command that swaps in a custom MigrationExecutor, and right now the only way to do it is to copy the whole handle() body just to replace one constructor line. That copy drifts from upstream on every release that touches handle() - we already got bitten once when a Django update reworked the executor setup and our override silently kept running the old flow until a test caught it.

The autodetector attribute already sets this exact precedent on the same command, so executor_class reads as consistent rather than new surface area. One thing worth pinning down in the proposal: whether BaseCommand.check_migrations() should resolve the same attribute (getattr with a MigrationExecutor default) so a subclass that sets executor_class once gets consistent behavior across both migrate and the runserver migration check, instead of having to override in two places.

[codingjoe]

@wspjoy2011 I don't think anyone will argue about the code change. However, I would caution you against extending undocumented APIs. Though I haven't seen cleanup commits land in a version past the past its release, internal APIs are not subject to deprecation.

That being said, I think there is a long history of 3rd-party packages and projects extending private APIs while carrying the burden of testing and updating. So, use it at your own effort and risk :)

[wspjoy2011]

@codingjoe Thanks, that is a fair caution and honestly it cuts both ways. Right now we already depend on the private internals by copying handle(), so we are carrying the breakage risk either way - the only question is whether that dependency stays implicit and copy-pasted, or becomes one small documented seam. A blessed executor_class would not remove the risk you describe, but it would shrink the surface we have to babysit from "the whole method body" down to "one attribute", which is the part that appeals to us.

Either way, point taken that internal APIs come with no deprecation guarantees - we will keep owning the testing burden on our side regardless of which way this lands.

Appreciate you weighing in.

[nessita]

@nessita the PR was a five line change to improve inheritance which is generally welcome, right? At most I could argue for a cleanup ticket. Can you share your concerns to get a full picture?

Specifically for this issue, while the implementation is small, the PR introduces a new supported extension point and therefore a new feature/API contract (the executor customization is changed from an implementation detail to an intentionally supported extension mechanism). It was also missing both documentation and community discussion/consensus. Django is a community-driven project, and these decisions should be visible to the wider community before being merged.

The new feature process applies regardless of the size of the patch. The goal is not procedural overhead, but ensuring:

• visibility within the community,
• an opportunity for others to raise concerns or suggest alternative approaches,
• evaluating the long-term maintenance and compatibility implications of introducing a new supported extension point,
• and broader validation that this is an API surface Django wants to support long term.

There are many targeted improvements we could make to Django, but part of maintaining a mature and stable framework is being deliberate about which customization hooks and APIs become officially supported. Following the process also helps reviewers evaluate proposals consistently and keeps review time focused on changes that already have community support and clear project direction.

[nanuxbe]

I know this might be scope creep be if we are improving the subclassing of migrations, I would still love to see a migrated_app property (defaulting to the current app) instead of the current hard-coded behavior of always considering the migration to be for the app it's in.
This would make it easier to move migrations (ie: for swappable models, model-based packages, etc)

[ryanhiebert]

I haven't been able to sit down and figure out exactly what I'd need from it, but I would appreciate some better hooks into the migration system for django-safemigrate. The signal-handling approach to filtering the migrations to run is a bit strained, and I haven't yet been able to find good hook or subclassing APIs to make similar parallel commands for makemigrations and showmigrations, which would really help to make the package more usable.

For a safemakemigrations, I need to somehow be able to override how the migration subclass is written to the migration and add a new property. I'm not totally convinced there's no good extension point for that purpose yet, but when I went looking I did have trouble identifying one.

[codingjoe]

Thanks, @nessita, for the thoughtful response and sharing your insight. 💯 I see your point now. I was shortsighted. A feature is a feature, and even small burdens add extra complexity over time.

---

@moaddib666, I'd actually like to expand the feature creep from my previous comment. What would a good expansion model look like for Django CLI commands? Hooks, inheritance? How would we document this and ensure adoption and consistency across all CLI commands? There isn't really a precedent I can think of. So you'd be breaking new ground. But given the comments, I feel there is community interest.

[moaddib666]

Thanks for expanding on this — I’d definitely be interested in helping push this forward.

Do you think this is something that could land in the current LTS cycle, or is it more realistic for Django 6.x?

Asking as I need to plan the roadmap for the company internal SDK, that requires some custom logic on migrations.