room-migration

name	room-migration
description	Safely change the SubKan Room schema — add/rename/drop a column, add an entity or index — with a version bump, a tested Migration, and a regenerated schema JSON. Use whenever an @Entity in data/local/entity changes, before writing any UI that depends on the new shape.

Changing the SubKan database schema

The database lives on the user's device and holds the only copy of what the user entered. There is no server to restore from. Every schema change is therefore a migration, and the migration is tested.

The rule that matters most

Never add fallbackToDestructiveMigration(). It makes the crash go away by deleting everything the user recorded. If a migration is failing, fix the migration.

1. Change the entity

Edit the @Entity in data/local/entity/. New columns must be nullable or have a Kotlin default — existing rows have no value for them.

Update toDomain() / toEntity() in the same file, and the domain type in core/model if the new field is user-visible.

2. Bump the version

In data/local/SubKanDatabase.kt, increment version. Go up by exactly one.

3. Write the migration

Add it next to the database, and register it on the builder in data/di/DataModule.kt:

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(connection: SQLiteConnection) {
        connection.execSQL()
    }
}


Room.databaseBuilder(context, SubKanDatabase::.java, SubKanDatabase.NAME)
    .addMigrations(MIGRATION_1_2)
    .build()