room-schema-governance

Locate the abstract class annotated with @Database and increment its version number by exactly one. Add the new entity class to the entities array with trailing commas, then run a clean build to verify the Room annotation processor output.

During development, use .fallbackToDestructiveMigration() in the Room database builder to allow rapid schema changes without writing migration scripts. For stable or release branches, implement a manual Migration class instead to preserve user data.

Room throws IllegalStateException when the database version does not match the schema hash of the entities, typically because the version was not incremented after modifying an @Entity. Incrementing the version and providing a migration or destructive fallback resolves it.

Yes, when exportSchema is set to true, Room generates a schema JSON file for each version that should be tracked in version control. These files enable migration testing and document the schema history.

Avoid destructive fallback on stable or release branches because it deletes all existing user data when the schema changes. Use it only during active development, and write explicit Migration implementations before shipping to production.