Migration Guide needs to cover out-of-order migrations

[nhorton]

This is a doc issue.

There was code introduced several versions ago that appears to handle the situation of a new migration appearing with a filename timestamp lower than the latest one run that will result in that migration still being run. That is different than how things worked at a point (and therefore there is now-incorrect data on the web for it) and important info in general.

This out-of-order behavior should be in the guide.

My personal suggestion would be having a section titled something like "Migrations and Version Control" that talks about it in the context of when you need to re-number migrations and when you don't since that is the main place this issue comes up.

[skipkayhil]

There was code introduced several versions ago that appears to handle the situation of a new migration appearing with a filename timestamp lower than the latest one run that will result in that migration still being run. That is different than how things worked at a point (and therefore there is now-incorrect data on the web for it) and important info in general.

I don't think I'm familiar with this scenario. When would a migration version less than the schema version be run?

[nhorton]

Apologies for the slow reply - someone on my team said they had tested this behavior and found it to be happening. I will check myself and get a repro to demonstrate, but it may be a few days.

[p8]

I don't think I'm familiar with this scenario. When would a migration version less than the schema version be run?

• Person A creates a PR X with migration 20240101
• Person B creates a PR Y with migration 20240501
• PR Y gets merged
• PR X gets merged (the migration version is less than the schema version).

This could be a problem if for example both migrations modify the same column.