Di chuyển cơ sở dữ liệu Room

Khi thêm và thay đổi các tính năng trong ứng dụng của mình, bạn cần sửa đổi các lớp thực thể Room và bảng cơ sở dữ liệu cơ bản để phản ánh những thay đổi này. Bạn cần lưu giữ dữ liệu người dùng đã có trong cơ sở dữ liệu trên thiết bị khi bản cập nhật ứng dụng thay đổi giản đồ cơ sở dữ liệu.

Room hỗ trợ cả các tuỳ chọn tự động và thủ công để di chuyển dần dần. Quá trình di chuyển tự động hoạt động với hầu hết các thay đổi cơ bản về giản đồ, nhưng bạn có thể cần xác định thủ công các đường dẫn di chuyển đối với những thay đổi phức tạp hơn.

Di chuyển tự động

Để khai báo quá trình di chuyển tự động giữa hai phiên bản cơ sở dữ liệu, hãy thêm chú giải @AutoMigration vào thuộc tính autoMigrations trong @Database:

Kotlin

// Database class before the version update.
@Database(
  version = 1,
  entities = [User::class]
)
abstract class AppDatabase : RoomDatabase() {
  ...
}

// Database class after the version update.
@Database(
  version = 2,
  entities = [User::class],
  autoMigrations = [
    AutoMigration (from = 1, to = 2)
  ]
)
abstract class AppDatabase : RoomDatabase() {
  ...
}

Java

// Database class before the version update.
@Database(
  version = 1,
  entities = {User.class}
)
public abstract class AppDatabase extends RoomDatabase {
  ...
}

// Database class after the version update.
@Database(
  version = 2,
  entities = {User.class},
  autoMigrations = {
    @AutoMigration (from = 1, to = 2)
  }
)
public abstract class AppDatabase extends RoomDatabase {
  ...
}

Thông số kỹ thuật di chuyển tự động

Nếu Room phát hiện các thay đổi giản đồ không rõ ràng và không thể tạo kế hoạch di chuyển nếu không có thêm thông tin, thì ứng dụng sẽ gửi lỗi thời gian biên dịch và yêu cầu bạn triển khai AutoMigrationSpec. Thông thường, trường hợp này xảy ra khi quá trình di chuyển liên quan đến một trong những thao tác sau:

  • Xoá hoặc đổi tên bảng.
  • Xoá hoặc đổi tên cột.

Bạn có thể sử dụng AutoMigrationSpec để cung cấp cho Room những thông tin bổ sung cần thiết nhằm tạo đường dẫn di chuyển chính xác. Xác định một lớp tĩnh triển khai AutoMigrationSpec trong lớp RoomDatabase của bạn và chú giải lớp đó bằng một hoặc nhiều lệnh sau:

Để sử dụng hoạt động triển khai AutoMigrationSpec cho quá trình di chuyển tự động, hãy đặt thuộc tính spec trong chú giải @AutoMigration tương ứng:

Kotlin

@Database(
  version = 2,
  entities = [User::class],
  autoMigrations = [
    AutoMigration (
      from = 1,
      to = 2,
      spec = AppDatabase.MyAutoMigration::class
    )
  ]
)
abstract class AppDatabase : RoomDatabase() {
  @RenameTable(fromTableName = "User", toTableName = "AppUser")
  class MyAutoMigration : AutoMigrationSpec

  ...
}

Java

@Database(
  version = 2,
  entities = {AppUser.class},
  autoMigrations = {
    @AutoMigration (
      from = 1,
      to = 2,
      spec = AppDatabase.MyAutoMigration.class
    )
  }
)
public abstract class AppDatabase extends RoomDatabase {
  @RenameTable(fromTableName = "User", toTableName = "AppUser")
  static class MyAutoMigration implements AutoMigrationSpec { }

  ...
}

Nếu ứng dụng của bạn cần làm nhiều việc hơn sau khi quá trình di chuyển tự động hoàn tất, bạn có thể triển khai onPostMigrate(). Nếu bạn triển khai phương thức này trong AutoMigrationSpec, thì Room sẽ gọi phương thức này sau khi quá trình di chuyển tự động hoàn tất.

Di chuyển thủ công

Trong trường hợp quá trình di chuyển kéo theo những thay đổi phức tạp của giản đồ, Room có thể không tự động tạo được đường dẫn di chuyển thích hợp. Ví dụ: Nếu bạn quyết định chia dữ liệu trong một bảng thành hai bảng, thì Room không thể phân tích quá trình chia này. Trong các trường hợp này, bạn phải xác định đường dẫn di chuyển theo cách thủ công bằng cách triển khai lớp Migration.

Mỗi lớp Migration xác định rõ một đường dẫn di chuyển giữa startVersionendVersion bằng cách ghi đè phương thức Migration.migrate(). Thêm các lớp Migration đã xác định vào trình tạo cơ sở dữ liệu bằng cách sử dụng phương thức addMigrations():

Kotlin

val MIGRATION_1_2 = object : Migration(1, 2) {
  override fun migrate(database: SupportSQLiteDatabase) {
    database.execSQL("CREATE TABLE `Fruit` (`id` INTEGER, `name` TEXT, " +
      "PRIMARY KEY(`id`))")
  }
}

val MIGRATION_2_3 = object : Migration(2, 3) {
  override fun migrate(database: SupportSQLiteDatabase) {
    database.execSQL("ALTER TABLE Book ADD COLUMN pub_year INTEGER")
  }
}

Room.databaseBuilder(applicationContext, MyDb::class.java, "database-name")
  .addMigrations(MIGRATION_1_2, MIGRATION_2_3).build()

Java

static final Migration MIGRATION_1_2 = new Migration(1, 2) {
  @Override
  public void migrate(SupportSQLiteDatabase database) {
    database.execSQL("CREATE TABLE `Fruit` (`id` INTEGER, "
      + "`name` TEXT, PRIMARY KEY(`id`))");
  }
};

static final Migration MIGRATION_2_3 = new Migration(2, 3) {
  @Override
  public void migrate(SupportSQLiteDatabase database) {
    database.execSQL("ALTER TABLE Book "
      + " ADD COLUMN pub_year INTEGER");
  }
};

Room.databaseBuilder(getApplicationContext(), MyDb.class, "database-name")
  .addMigrations(MIGRATION_1_2, MIGRATION_2_3).build();

Khi xác định đường dẫn di chuyển, bạn có thể sử dụng quá trình di chuyển tự động cho một số phiên bản và quá trình di chuyển thủ công cho những phiên bản khác. Nếu bạn xác định cả quá trình di chuyển tự động và di chuyển thủ công cho cùng một phiên bản, thì Room sẽ sử dụng quá trình di chuyển thủ công.

Kiểm thử các quá trình di chuyển

Quá trình di chuyển thường phức tạp và nếu được xác định không chính xác có thể khiến ứng dụng của bạn gặp sự cố. Để duy trì độ ổn định của ứng dụng, bạn nên kiểm thử quá trình di chuyển. Room cung cấp cấu phần phần mềm Maven room-testing để hỗ trợ quá trình kiểm thử cho cả quá trình di chuyển tự động và thủ công. Để cấu phần phần mềm này hoạt động, trước tiên, bạn phải xuất giản đồ của cơ sở dữ liệu.

Xuất giản đồ

Room có thể xuất thông tin giản đồ cơ sở dữ liệu của bạn vào tệp JSON vào thời gian biên dịch. Để xuất giản đồ, hãy đặt thuộc tính trình xử lý chú giải room.schemaLocation trong tệp app/build.gradle của bạn:

build.gradle

Groovy

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                arguments += ["room.schemaLocation":
                             "$projectDir/schemas".toString()]
            }
        }
    }
}

Kotlin

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                arguments += mapOf("room.schemaLocation" to "$projectDir/schemas")
            }
        }
    }
}

Các tệp JSON đã xuất sẽ đại diện cho nhật ký giản đồ cơ sở dữ liệu của bạn. Bạn nên lưu trữ các tệp này trong hệ thống quản lý phiên bản của mình, vì hệ thống này cho phép Room tạo các phiên bản cơ sở dữ liệu cũ hơn cho mục đích kiểm thử.

Kiểm thử một quá trình di chuyển

Để có thể kiểm thử các quá trình di chuyển, bạn phải thêm cấu phần phần mềm Maven androidx.room:room-testing từ Room vào các phần phụ thuộc kiểm thử và thêm vị trí của giản đồ đã xuất làm thư mục tài sản:

build.gradle

Groovy

android {
    ...
    sourceSets {
        // Adds exported schema location as test app assets.
        androidTest.assets.srcDirs += files("$projectDir/schemas".toString())
    }
}

dependencies {
    ...
      androidTestImplementation "androidx.room:room-testing:2.4.2"
}

Kotlin

android {
    ...
    sourceSets {
        // Adds exported schema location as test app assets.
        getByName("androidTest").assets.srcDir("$projectDir/schemas")
    }
}

dependencies {
    ...
    testImplementation("androidx.room:room-testing:2.4.2")
}

Gói kiểm thử cung cấp một lớp MigrationTestHelper, có thể đọc các tệp giản đồ được xuất. Gói này cũng triển khai giao diện TestRule JUnit4, nhờ đó có thể quản lý các cơ sở dữ liệu đã tạo.

Ví dụ sau đây minh hoạ hoạt động kiểm thử cho một quá trình di chuyển:

Kotlin

@RunWith(AndroidJUnit4::class)
class MigrationTest {
    private val TEST_DB = "migration-test"

    @get:Rule
    val helper: MigrationTestHelper = MigrationTestHelper(
            InstrumentationRegistry.getInstrumentation(),
            MigrationDb::class.java.canonicalName,
            FrameworkSQLiteOpenHelperFactory()
    )

    @Test
    @Throws(IOException::class)
    fun migrate1To2() {
        var db = helper.createDatabase(TEST_DB, 1).apply {
            // db has schema version 1. insert some data using SQL queries.
            // You cannot use DAO classes because they expect the latest schema.
            execSQL(...)

            // Prepare for the next version.
            close()
        }

        // Re-open the database with version 2 and provide
        // MIGRATION_1_2 as the migration process.
        db = helper.runMigrationsAndValidate(TEST_DB, 2, true, MIGRATION_1_2)

        // MigrationTestHelper automatically verifies the schema changes,
        // but you need to validate that the data was migrated properly.
    }
}

Java

@RunWith(AndroidJUnit4.class)
public class MigrationTest {
    private static final String TEST_DB = "migration-test";

    @Rule
    public MigrationTestHelper helper;

    public MigrationTest() {
        helper = new MigrationTestHelper(InstrumentationRegistry.getInstrumentation(),
                MigrationDb.class.getCanonicalName(),
                new FrameworkSQLiteOpenHelperFactory());
    }

    @Test
    public void migrate1To2() throws IOException {
        SupportSQLiteDatabase db = helper.createDatabase(TEST_DB, 1);

        // db has schema version 1. insert some data using SQL queries.
        // You cannot use DAO classes because they expect the latest schema.
        db.execSQL(...);

        // Prepare for the next version.
        db.close();

        // Re-open the database with version 2 and provide
        // MIGRATION_1_2 as the migration process.
        db = helper.runMigrationsAndValidate(TEST_DB, 2, true, MIGRATION_1_2);

        // MigrationTestHelper automatically verifies the schema changes,
        // but you need to validate that the data was migrated properly.
    }
}

Kiểm thử tất cả quá trình di chuyển

Mặc dù có thể kiểm thử một quá trình di chuyển dần dần, nhưng bạn nên kiểm thử tất cả quá trình di chuyển được xác định cho cơ sở dữ liệu của ứng dụng. Việc này đảm bảo rằng không có sự khác biệt giữa phiên bản cơ sở dữ liệu được tạo gần đây và phiên bản cũ hơn đi theo đường dẫn di chuyển đã xác định.

Ví dụ sau đây minh hoạ một hoạt động kiểm thử cho tất cả các quá trình di chuyển đã xác định:

Kotlin

@RunWith(AndroidJUnit4::class)
class MigrationTest {
    private val TEST_DB = "migration-test"

    // Array of all migrations
    private val ALL_MIGRATIONS = arrayOf(
            MIGRATION_1_2, MIGRATION_2_3, MIGRATION_3_4)

    @get:Rule
    val helper: MigrationTestHelper = MigrationTestHelper(
            InstrumentationRegistry.getInstrumentation(),
            AppDatabase::class.java.canonicalName,
            FrameworkSQLiteOpenHelperFactory()
    )

    @Test
    @Throws(IOException::class)
    fun migrateAll() {
        // Create earliest version of the database.
        helper.createDatabase(TEST_DB, 1).apply {
            close()
        }

        // Open latest version of the database. Room will validate the schema
        // once all migrations execute.
        Room.databaseBuilder(
            InstrumentationRegistry.getInstrumentation().targetContext,
            AppDatabase::class.java,
            TEST_DB
        ).addMigrations(*ALL_MIGRATIONS).build().apply {
            openHelper.writableDatabase.close()
        }
    }
}

Java

@RunWith(AndroidJUnit4.class)
public class MigrationTest {
    private static final String TEST_DB = "migration-test";

    @Rule
    public MigrationTestHelper helper;

    public MigrationTest() {
        helper = new MigrationTestHelper(InstrumentationRegistry.getInstrumentation(),
                AppDatabase.class.getCanonicalName(),
                new FrameworkSQLiteOpenHelperFactory());
    }

    @Test
    public void migrateAll() throws IOException {
        // Create earliest version of the database.
        SupportSQLiteDatabase db = helper.createDatabase(TEST_DB, 1);
        db.close();

        // Open latest version of the database. Room will validate the schema
        // once all migrations execute.
        AppDatabase appDb = Room.databaseBuilder(
                InstrumentationRegistry.getInstrumentation().getTargetContext(),
                AppDatabase.class,
                TEST_DB)
                .addMigrations(ALL_MIGRATIONS).build();
        appDb.getOpenHelper().getWritableDatabase();
        appDb.close();
    }

    // Array of all migrations
    private static final Migration[] ALL_MIGRATIONS = new Migration[]{
            MIGRATION_1_2, MIGRATION_2_3, MIGRATION_3_4};
}

Vui lòng xử lý các đường dẫn di chuyển bị thiếu

Nếu Room không tìm thấy đường dẫn di chuyển để nâng cấp cơ sở dữ liệu hiện có trên thiết bị lên phiên bản hiện tại, thì IllegalStateException sẽ xuất hiện. Nếu bạn có thể chấp nhận mất dữ liệu hiện có khi thiếu đường dẫn di chuyển, hãy gọi phương thức trình tạo fallbackToDestructiveMigration() khi bạn tạo cơ sở dữ liệu:

Kotlin

Room.databaseBuilder(applicationContext, MyDb::class.java, "database-name")
        .fallbackToDestructiveMigration()
        .build()

Java

Room.databaseBuilder(getApplicationContext(), MyDb.class, "database-name")
        .fallbackToDestructiveMigration()
        .build();

Phương thức này sẽ yêu cầu Room tạo lại toàn bộ các bảng trong cơ sở dữ liệu của ứng dụng (có thể gây thiệt hại) khi cần thực hiện quá trình di chuyển dần dần nếu không có đường dẫn di chuyển đã xác định nào.

Nếu bạn chỉ muốn Room tìm đến hoạt động tạo lại gây thiệt hại ở một số tình huống nhất định, thì có một vài phương án thay thế cho fallbackToDestructiveMigration():

  • Nếu các phiên bản cụ thể của nhật ký giản đồ gây ra các lỗi mà bạn không thể giải quyết bằng đường dẫn di chuyển, hãy sử dụng fallbackToDestructiveMigrationFrom() thay thế. Phương thức này cho biết rằng bạn chỉ muốn Room tìm đến hoạt động tạo lại gây thiệt hại khi di chuyển từ các phiên bản cụ thể.
  • Nếu bạn chỉ muốn Room tìm đến hoạt động tạo lại gây thiệt hại khi di chuyển từ phiên bản cơ sở dữ liệu cao hơn sang phiên bản cơ sở dữ liệu thấp hơn, hãy sử dụng fallbackToDestructiveMigrationOnDowngrade() thay thế.

Xử lý giá trị mặc định của cột khi nâng cấp lên Room 2.2.0

Ở Room 2.2.0 trở lên, bạn có thể xác định giá trị mặc định cho cột bằng cách sử dụng chú giải @ColumnInfo(defaultValue = "..."). Trong các phiên bản thấp hơn 2.2.0, cách duy nhất để xác định giá trị mặc định cho cột là xác định trực tiếp giá trị đó trong câu lệnh SQL được thực thi. Thao tác này sẽ tạo ra giá trị mặc định mà Room không biết. Nói cách khác, nếu ban đầu, cơ sở dữ liệu được tạo bằng phiên bản Room thấp hơn 2.2.0, thì việc nâng cấp cho ứng dụng của bạn sử dụng Room 2.2.0 có thể yêu cầu bạn cung cấp đường dẫn di chuyển đặc biệt cho giá trị mặc định hiện có mà bạn đã xác định khi không sử dụng API Room.

Ví dụ: Giả sử phiên bản 1 của cơ sở dữ liệu xác định thực thể Song:

Kotlin

// Song Entity, DB Version 1, Room 2.1.0
@Entity
data class Song(
    @PrimaryKey
    val id: Long,
    val title: String
)

Java

// Song Entity, DB Version 1, Room 2.1.0
@Entity
public class Song {
    @PrimaryKey
    final long id;
    final String title;
}

Giả sử thêm rằng phiên bản 2 của cùng một cơ sở dữ liệu đó thêm một cột NOT NULL mới và xác định đường dẫn di chuyển từ phiên bản 1 sang phiên bản 2:

Kotlin

// Song Entity, DB Version 2, Room 2.1.0
@Entity
data class Song(
    @PrimaryKey
    val id: Long,
    val title: String,
    val tag: String // Added in version 2.
)

// Migration from 1 to 2, Room 2.1.0
val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL(
            "ALTER TABLE Song ADD COLUMN tag TEXT NOT NULL DEFAULT ''")
    }
}

Java

// Song Entity, DB Version 2, Room 2.1.0
@Entity
public class Song {
    @PrimaryKey
    final long id;
    final String title;
    @NonNull
    final String tag; // Added in version 2.
}

// Migration from 1 to 2, Room 2.1.0
static final Migration MIGRATION_1_2 = new Migration(1, 2) {
    @Override
    public void migrate(SupportSQLiteDatabase database) {
        database.execSQL(
            "ALTER TABLE Song ADD COLUMN tag TEXT NOT NULL DEFAULT ''");
    }
};

Điều này gây ra sự khác biệt trong bảng cơ bản giữa các bản cập nhật và lượt cài đặt mới của ứng dụng. Vì giá trị mặc định cho cột tag chỉ được khai báo trong đường dẫn di chuyển từ phiên bản 1 sang phiên bản 2, nên mọi người dùng đã cài đặt ứng dụng bắt đầu từ phiên bản 2 sẽ không có giá trị mặc định cho tag trong giản đồ cơ sở dữ liệu của họ.

Ở các phiên bản Room thấp hơn 2.2.0, sự khác biệt này không gây hại. Tuy nhiên, nếu sau đó ứng dụng nâng cấp để sử dụng Room 2.2.0 trở lên và thay đổi lớp thực thể Song để có thể chứa giá trị mặc định cho tag bằng cách sử dụng chú giải @ColumnInfo, thì lúc đó Room có thể thấy sự khác biệt này. Điều này dẫn đến việc xác thực giản đồ không thành công.

Để đảm bảo rằng giản đồ cơ sở dữ liệu nhất quán ở tất cả người dùng khi các giá trị mặc định của cột được khai báo trong các đường dẫn di chuyển trước đó của bạn, hãy thực hiện như sau trong lần đầu tiên bạn nâng cấp ứng dụng của mình để sử dụng Room 2.2.0 trở lên:

  1. Khai báo giá trị mặc định của cột trong các lớp thực thể tương ứng bằng chú giải @ColumnInfo.
  2. Tăng số phiên bản cơ sở dữ liệu lên một số.
  3. Xác định đường dẫn di chuyển đến phiên bản mới triển khai chiến lược xoá (drop) và tạo lại (recreate) để thêm các giá trị mặc định cần thiết vào các cột hiện có.

Ví dụ sau đây minh hoạ quá trình này:

Kotlin

// Migration from 2 to 3, Room 2.2.0
val MIGRATION_2_3 = object : Migration(2, 3) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL("""
                CREATE TABLE new_Song (
                    id INTEGER PRIMARY KEY NOT NULL,
                    name TEXT,
                    tag TEXT NOT NULL DEFAULT ''
                )
                """.trimIndent())
        database.execSQL("""
                INSERT INTO new_Song (id, name, tag)
                SELECT id, name, tag FROM Song
                """.trimIndent())
        database.execSQL("DROP TABLE Song")
        database.execSQL("ALTER TABLE new_Song RENAME TO Song")
    }
}

Java

// Migration from 2 to 3, Room 2.2.0
static final Migration MIGRATION_2_3 = new Migration(2, 3) {
    @Override
    public void migrate(SupportSQLiteDatabase database) {
        database.execSQL("CREATE TABLE new_Song (" +
                "id INTEGER PRIMARY KEY NOT NULL," +
                "name TEXT," +
                "tag TEXT NOT NULL DEFAULT '')");
        database.execSQL("INSERT INTO new_Song (id, name, tag) " +
                "SELECT id, name, tag FROM Song");
        database.execSQL("DROP TABLE Song");
        database.execSQL("ALTER TABLE new_Song RENAME TO Song");
    }
};