room-entity-pattern

Structure Room entities consistently by applying a four-file pattern: XxxEntity, XxxDao, XxxMapper, and XxxRepository, which aligns domain logic with Room persistence and prevents inconsistent data layer implementations.

Handle Room many-to-many join tables by applying surrogate-PK rules with composite unique indices and REPLACE conflict-safe upserts, ensuring connection tables behave correctly without duplicate relation records.

Safely perform SQLite schema versioning in Room by executing a schema version bump, applying AutoMigration or manual Migration, verifying schema JSON, validating builds, and running on-device migration smoke tests.

You need to bump the Room database schema version whenever you add or modify Room entities, join tables, or dynamic query filters, triggering the required migration checklist to prevent unsafe schema changes.

AutoMigration handles many Room schema changes, but complex modifications may require manual Migration classes; both paths require schema JSON verification, build validation, and on-device migration smoke testing.

Room repository queries become inconsistent with domain models when missing a standardized mapper layer; implementing the XxxMapper file within the four-file pattern translates persistence entities into domain logic safely.