Server teams migrate one database, on a schedule, with a rollback plan. Mobile teams migrate millions of them, one per device, at whatever moment each customer opens the app, on data the company cannot see. It runs once. If it is wrong, there is no second attempt.
Two Ways to Fail, One of Them Quiet
Android's standard database library fails loudly by default. "If Room can't find a migration path to upgrade an existing database on a device to the current version, an IllegalStateException occurs" (Android). The app crashes, the crash is reported, the team finds out.
There is a setting that makes the crash go away. The same guide describes what it does instead: "Room permanently deletes all data from the tables in the user's database when it attempts to perform a migration and there's no defined migration path." No crash report, no alert. The customer opens the app and their work is gone. That setting is reasonable for a cache. It should never be near anything a customer typed.
The Device Decides What Is Possible
A migration is also limited by the database engine built into each phone, and older phones carry older engines. Removing a column directly needs a version of SQLite released in March 2021, which Android's own table shows only from API level 34. A change that passes on the team's new test phones can fail on the older half of the customer base.
The Test That Matters
Testing each step is necessary and not enough. The guide asks for one more test, across the whole chain from the first version to the latest, because it "helps ensure that there's no discrepancy between a recently created database instance and an earlier instance that followed the defined migration paths". That test represents the customer who skipped four releases. Most suites do not have it.
Our article on this subject was rewritten this month: the library shipped a new major version in July 2026, and our own text had a factual error about what it can automate.
What to Ask Your Team
- Is destructive fallback enabled anywhere? If yes, on which data, and who approved it?
- Do we test the upgrade from our oldest supported version?
- Which operating system version do our migration tests run on? It should include the oldest one we support.
-Rocky
#DataIntegrity #MobileEngineering #ReleaseRisk #EngineeringDreams #StrategiaX
Originally published on ANDROID-ARCHITECT, the Android engineering blog of Strategia-X, with the migration code and the SQLite version table.