KotlinのRoomでデータベースマイグレーションを行う基本手順を初心者向けに解説！

1. Roomのデータベースマイグレーションとは？

1. Roomのデータベースマイグレーションとは？

マイグレーションとは、古いバージョンのデータベースを新しい形に変える処理のことです。

たとえば、アプリのバージョン1では「名前と年齢」しかなかったけれど、バージョン2では「メールアドレス」も保存したくなったとします。こういうときに、すでにインストール済みの人のデータを壊さずに新しい構造に変えるための手順が「マイグレーション」です。

2. マイグレーションが必要になる場面とは？

2. マイグレーションが必要になる場面とは？

Roomを使ったアプリでは、データベースのversionを上げたときに、過去のデータと新しい構造の整合性が必要になります。

• カラム（列）を追加した
• テーブルを新しく作った
• テーブル名を変更した

これらの変更を正しくアプリに反映するには、マイグレーション処理を設定する必要があります。

3. KotlinのRoomでマイグレーションする基本の書き方

3. KotlinのRoomでマイグレーションする基本の書き方

ここでは、ユーザーテーブルに「email」というカラムを追加する例で、Roomのマイグレーション処理を見てみましょう。

① 新しいエンティティを作る

@Entity(tableName = "users")
data class User(
    @PrimaryKey val id: Int,
    val name: String,
    val age: Int,
    val email: String // 新しく追加されたカラム
)

② データベースバージョンを上げる

RoomDatabaseのversionを1から2に上げます。

@Database(entities = [User::class], version = 2)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}

③ Migrationオブジェクトを定義する

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL("ALTER TABLE users ADD COLUMN email TEXT NOT NULL DEFAULT ''")
    }
}

④ Roomのビルダーにマイグレーションを追加する

val db = Room.databaseBuilder(
    context,
    AppDatabase::class.java, "my_database"
).addMigrations(MIGRATION_1_2).build()

4. execSQLって何？

4. execSQLって何？

execSQLは、データベースに直接SQL文（命令文）を送る関数です。Roomの裏ではSQLite（エスキューライト）という仕組みが動いており、execSQLを使ってテーブルの形を変更します。

「カラムを追加する」には、ALTER TABLE テーブル名 ADD COLUMN カラム名 型 DEFAULT 初期値 という命令を使います。

5. DEFAULTの設定を忘れずに！

5. DEFAULTの設定を忘れずに！

新しくカラムを追加するとき、すでに入っている古いデータにはそのカラムがありません。だからこそ、初期値（DEFAULT）を必ずつける必要があります。

例えば、emailを追加したけど、今までのデータにはメールアドレスがない…というとき、''（空文字）を入れておくことでエラーを防げます。

6. バージョン番号は必ず1ずつ上げよう

6. バージョン番号は必ず1ずつ上げよう

Roomのマイグレーションでは、versionを飛び越えることはできません。たとえば、バージョン1から3にするには、

• MIGRATION_1_2
• MIGRATION_2_3

のように順番に設定する必要があります。ひとつひとつの段階を丁寧に用意していきましょう。

7. マイグレーションを使えばデータを壊さずアップデートできる

7. マイグレーションを使えばデータを壊さずアップデートできる

KotlinとRoomを使ってアプリを作ると、あとから「もっと情報を保存したい」と思うことがよくあります。

そんなときでも、マイグレーションを正しく設定しておけば、ユーザーの大切なデータを消すことなく、新しい形に安全に更新できます。

初心者のうちは怖く感じるかもしれませんが、流れさえ分かれば意外とシンプルです。何度も練習して慣れていきましょう。

まとめ

まとめ

KotlinでAndroidアプリを開発するとき、Roomを使えばSQLiteデータベースを比較的わかりやすく扱うことができます。しかし、アプリを公開して運用を続けていると、最初に設計したデータベースの形をあとから変更したくなる場面が出てきます。ユーザー情報に新しい項目を追加したい、保存するデータが増えたので新しいテーブルを作りたい、既存のテーブル構造を変更したいといった場合です。このようなデータベースの変更を、すでに保存されているデータをできるだけ維持しながら新しい構造へ移行する仕組みが、Roomのデータベースマイグレーションです。

Roomのマイグレーションを理解するときに最も大切なのは、アプリを更新する利用者の端末には、すでに古いバージョンのデータベースが存在している可能性があるという点です。開発中の自分の端末だけで考えると、データベースを削除して作り直せば簡単に解決できるように見えます。しかし、実際に利用されているアプリでデータベースを作り直してしまうと、ユーザーがこれまで登録した情報まで失われる可能性があります。そのため、Roomではデータベースのバージョンを管理し、古い構造から新しい構造へ段階的に変更するためのMigrationを用意します。

Roomのマイグレーションが必要になる理由

KotlinとRoomを使ったAndroidアプリでは、エンティティの内容を変更しただけでは、すでに作成されているSQLiteデータベースの構造が自動的に都合よく変更されるとは限りません。たとえば、最初のバージョンでは利用者の名前と年齢だけを保存していたものの、次のバージョンからメールアドレスも保存する仕様になったとします。

新規インストールする利用者であれば、最初から新しい構造のデータベースを作成できます。しかし、すでに旧バージョンを使っている利用者の端末には、メールアドレスのカラムが存在しない古いテーブルが残っています。この差を正しく埋めるために、RoomDatabaseのversionを変更し、Migrationオブジェクトを定義して、必要なSQLを実行します。

基本の流れはエンティティ変更から始まる

Roomでカラムを追加する場合、最初に新しいデータベース構造に合わせてエンティティを変更します。エンティティは、Roomでテーブルの構造を表現する重要なクラスです。今回の例では、利用者情報を保存するUserにemailという新しい項目を追加します。

@Entity(tableName = "users")
data class User(
    @PrimaryKey val id: Int,
    val name: String,
    val age: Int,
    val email: String
)

エンティティに新しい項目を書くだけでは、すでに端末内に存在している古いusersテーブルにemailカラムが追加されるわけではありません。ここがRoomのマイグレーションで初心者が混乱しやすいポイントです。Kotlin側のクラス定義とSQLite側の実際のテーブル構造の両方を一致させる必要があります。

データベースのversionを上げる意味

エンティティの構造を変更したら、RoomDatabaseに指定しているversionも新しい番号へ変更します。versionは、現在のデータベース構造がどの世代なのかをRoomへ知らせるための番号です。最初の構造がバージョン一で、新しいカラムを追加した構造がバージョン二というように管理します。

@Database(entities = [User::class], version = 2)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}

Roomは、このversionの違いを見て、既存のデータベースをどのように新しい状態へ変更すればよいのか判断します。つまり、versionを上げることとMigrationを用意することはセットで考える必要があります。データベースの構造を変更したのにversionを適切に管理しなければ、アプリ起動時のデータベース処理で問題が発生する原因になります。

Migrationオブジェクトで変更内容を定義する

次に、古いバージョンから新しいバージョンへどのように変更するのかをMigrationオブジェクトとして定義します。バージョン一から二へ変更するのであれば、開始バージョンを一、終了バージョンを二としてMigrationを作成します。

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL(
            "ALTER TABLE users ADD COLUMN email TEXT NOT NULL DEFAULT ''"
        )
    }
}

この処理では、SQLiteのALTER TABLEを利用して、すでに存在しているusersテーブルへemailカラムを追加しています。Roomのマイグレーションでは、Kotlinで処理全体を管理しながら、実際のテーブル構造の変更にはSQLを使用することがあります。そのため、Roomを使っている場合でも、SQLの基本的な知識を理解しておくとマイグレーションをより正確に扱えるようになります。

execSQLはSQLiteへ直接命令を送るために使う

Migrationの中で登場するexecSQLは、SQLiteデータベースへSQL文を直接実行するための機能です。Roomを普段使っていると、エンティティやDaoを通してデータを扱うことが多いため、SQLを直接書く機会が少ないこともあります。しかし、テーブルの構造変更ではSQLを使う場面があります。

カラムを追加する場合にはALTER TABLEを使い、どのテーブルへ、どの名前のカラムを、どのデータ型で追加するのかを指定します。今回の例では、usersテーブルへemailという文字列用のカラムを追加しています。Roomのマイグレーションを学ぶときは、Kotlinだけではなく、Roomの内部でSQLiteが動いていることも意識すると理解しやすくなります。

DEFAULTが必要になる理由を理解しよう

新しいカラムを追加するときに特に重要なのがDEFAULTです。すでに保存されている古いデータには、当然ながら新しく追加するemailの値がありません。それにもかかわらず、新しいカラムを必須の値として追加すると、既存レコードに何を入れればよいのか決められなくなります。

そこで、古いレコードには初期値として空文字を設定するなど、DEFAULTを指定します。これにより、既存の利用者情報を残したまま、新しいemailカラムを追加できます。Roomでカラム追加のマイグレーションを行う場合は、新しくインストールする利用者だけではなく、すでにデータを持っている利用者の状態を考えることが重要です。

Room.databaseBuilderへMigrationを登録する

Migrationオブジェクトを作成しただけでは、Roomが自動的にその処理を利用するわけではありません。Room.databaseBuilderでデータベースを作成するときに、addMigrationsを使ってMigrationを登録します。

val db = Room.databaseBuilder(
    context,
    AppDatabase::class.java,
    "my_database"
).addMigrations(MIGRATION_1_2)
    .build()

この設定によって、古いバージョン一のデータベースを持っている利用者がバージョン二のアプリを起動した場合に、登録したマイグレーションを使ってデータベース構造を変更できるようになります。エンティティの変更、versionの更新、Migrationの作成、addMigrationsによる登録という一連の流れをセットで覚えておきましょう。

複数バージョンのマイグレーションは段階を意識する

アプリを長く運用すると、データベースのバージョンが二、三、四と増えていくことがあります。その場合、どのバージョンからどのバージョンへ変更するための処理なのかを明確に管理することが重要になります。

例えば、バージョン一から二でメールアドレスを追加し、さらに次のバージョン二から三で新しい変更を行うのであれば、それぞれの変更内容に対応したMigrationを用意します。記事で紹介したように、一から二、二から三という段階を意識して準備しておけば、それぞれのデータベース構造の変更内容がわかりやすくなります。

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL(
            "ALTER TABLE users ADD COLUMN email TEXT NOT NULL DEFAULT ''"
        )
    }
}

val MIGRATION_2_3 = object : Migration(2, 3) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL(
            "ALTER TABLE users ADD COLUMN address TEXT NOT NULL DEFAULT ''"
        )
    }
}

このように変更の履歴を段階ごとに分けることで、どのバージョンでどのカラムが追加されたのか確認しやすくなります。Roomのマイグレーションでは、現在のデータベースだけを見るのではなく、過去のバージョンを使っている利用者が新しいバージョンへ更新する流れも考えることが大切です。

カラム追加以外でもマイグレーションが必要になる

Roomのデータベースマイグレーションは、カラム追加だけの仕組みではありません。アプリの機能追加に伴って新しいテーブルを作成したり、既存のテーブル名を変更したり、保存する情報の構造を変更したりする場合にも必要になります。

データベース設計は、アプリの成長とともに変わっていくことがあります。最初から将来必要になるすべての項目を予測するのは難しいため、あとから安全に構造を変更できるマイグレーションの考え方を理解しておくことが重要です。特にユーザーが入力したデータを保存するアプリでは、既存データを守りながらアップデートすることが大切になります。

マイグレーションはデータを守るための仕組み

Kotlin初心者にとってRoomのマイグレーションは、SQLやバージョン番号などが登場するため、最初は難しく感じるかもしれません。しかし、目的を理解すると考え方はシンプルです。古いデータベースを持つ利用者がアプリを更新したときに、そのデータを失わず、新しいアプリでも使える形へ変換することが目的です。

アプリを作り直すのではなく、すでに存在しているデータを次の構造へ引き継ぐための設計と考えると理解しやすくなります。名前、年齢、メールアドレスなど、利用者が登録した情報はアプリにとって重要なデータです。アプリの機能を追加するたびにそれらが消えてしまっては、安心して利用してもらうことができません。

そのため、Roomのマイグレーションは単なるデータベース操作ではなく、アプリのアップデート時にユーザーデータを安全に守るための重要な仕組みといえます。

初心者が覚えておきたいRoomマイグレーションの基本手順

KotlinのRoomでデータベースマイグレーションを行うときは、まず新しい仕様に合わせてEntityを変更します。次にRoomDatabaseのversionを上げます。そして、古いバージョンから新しいバージョンへ構造を変えるMigrationオブジェクトを作成し、migrateの中で必要なSQLを実行します。最後にRoom.databaseBuilderへaddMigrationsを指定して、作成したMigrationを登録します。

この流れを理解しておけば、ユーザーテーブルへのカラム追加だけでなく、アプリの成長に応じたデータベース構造の変更にも対応しやすくなります。最初は小さなサンプルで、バージョン一から二へカラムを一つ追加するところから練習するとよいでしょう。

KotlinとRoomのデータベース設計を一緒に理解しよう

Roomを使うとKotlinのクラスとSQLiteのテーブルを結びつけて扱えるため、Androidアプリのデータ保存をわかりやすく実装できます。一方で、アプリを更新するときには、Kotlin側のEntityだけでなく、端末に保存済みのSQLiteデータベースがどのような状態になっているのかも考えなければなりません。

その橋渡しをするのがMigrationです。Entityは新しいデータ構造を表し、versionはデータベース構造の世代を示し、Migrationは旧バージョンから新バージョンへ進む方法を定義します。そしてexecSQLによって実際のSQLiteテーブルを変更し、addMigrationsによってRoomへその移行方法を登録します。

この関係をひとつの流れとして理解すると、Roomのマイグレーションはそれほど複雑ではありません。アプリのデータベースを変更するときに、古い利用者のデータをどう引き継ぐかという視点を持つことが最も重要です。

Roomのマイグレーションを理解して安全なアプリ更新につなげよう

KotlinでRoomを利用したAndroidアプリを開発する場合、データベースマイグレーションは長く運用するほど重要になる知識です。最初の開発では変更する予定がなくても、利用者の要望や新しい機能の追加によって保存項目が増えることがあります。

そのときに、データベースを削除して作り直すのではなく、古いデータを維持しながら新しいテーブル構造へ変更できれば、安全にアプリをアップデートできます。Roomのversion、Migration、SupportSQLiteDatabase、execSQL、ALTER TABLE、DEFAULT、addMigrationsという基本的な役割を順番に理解しておくことが大切です。

特に初心者のうちは、カラムを一つ追加するシンプルなマイグレーションから練習すると理解しやすくなります。Entityを変更して終わりではなく、既存データベースには古い構造が残っていることを常に意識しましょう。Roomのデータベースマイグレーションを正しく扱えるようになると、ユーザーデータを守りながら機能追加やデータベース設計の変更ができるようになり、より実践的なKotlinのAndroidアプリ開発へつながります。