There is a possibility that some app want to be distributed with
eraseDatabaseOnSchemaChange on. This is a door that has to remain open.
Now the flag is intended to nuke the db when the schema changes. Its current implementation has no false negatives (it spots all schema changes), but it may still have false positives (it may spot a change when there isn't). Such false positive may happen when the schema comparison is performed against a database that was created with a former version of SQLite, or a former version of GRDB. I didn't spend time trying to address those false positives yet (I don't even know for sure if they do exist for real, and/or if they can reliably be avoided). I have to look closely at the source code for https://www.sqlite.org/sqldiff.html.
I first and foremost want to avoid misleading users, and losing their data. I also want to avoid the many issues attached to the inspiration for this flag: Realm's deleteRealmIfMigrationNeeded.
That's why the documentation is extra careful, insists on the flag danger, and suggests hiding it behind
And I'm happy that you ask this question, because it proves that the doc has done its job: you had first thoughts and expectations, and those were modified.
Enough rationale. Did you have an alternative api in mind?