When to use db_alias in migration?

Hi, I noticed that in the documentation of RunPython there’s this line with db_alias = schema_editor.connection.alias. As far as I can see it’s supposed to be used when we have multiple databases and want to run operations against a certain one if we invoke migrate command with --database option. However it’s not used in any example in the writing migrations documentation (apart from the one, which prevents running code for specific db).

I just wonder what the standard is here. Should db_alias always be provided to querysets in migrations? It seems to me that there’s no point in doing so, even when we have multiple mirror databases. I find the RunPython’s documentation a bit confusing by adding db_alias in the main example and I think it may lead to copying this pattern unnecessarily and thus raise questions (like mine now).

It seems to me that you would always want to specify it.

By supplying it, you make your migrations completely compatible with all the automatically generated migrations, and it doesn’t cause any problems if the only database being used is 'default'.

By not including it, you could create a problem when someone tries to run your migration against a different database - possibly even introducing problems because of querying or altering a different database than the one specified on the command line.


1 Like

Thanks for a quick response @KenWhitesell! I think what you say is very reasonable.

On the other hand most migrations are one-time use only and it’s rather known in advance which database they will be run against. So it doesn’t really matter if we took care of making the migration database independent.

Anyway it’s more a matter of documentation inconsistency to me. I think it might be a good idea to add proper db handling to all examples in the writing migrations documentation if this should be the preferred approach, because currently it’s hard to tell. I could propose corrections to the documentation if there is positive feedback on this idea.