【Flutter】
データベースのマイグレーションを行って新しいバージョンのアプリにテーブルを追加する方法
sqfliteでのマイグレーション方法
投稿日 2026/03/05 更新日 2026/03/05
こんにちは。IT業界歴6年目の「元木皇天」です。
先日、私がリリースしたFlutter製のアプリで、新バージョンの開発中に新しいテーブルを作る必要がありました。
ということで、今回はFlutterで使用しているsqfliteを使用してDBのマイグレーションを行う方法について解説いたします。
ちなみに、同様の方法でカラムの追加やテーブルの削除などもできます。
やりたいこと
sqfliteでデータベースのマイグレーションを行い、新テーブルを追加する
参考文献
環境
・OS：MacOS Sequoia 15.6
・Flutter：Ver 3.35.6
・sqflite：Ver 2.4.2
sqfliteでマイグレーション
まず初めに、マイグレーション前のコードを紹介します。（私のアプリでは、DatabaseHelperクラスでDBの作成などの処理を担っています）
class DatabaseHelper {
static final DatabaseHelper instance = DatabaseHelper._();
static Database? _database;
DatabaseHelper._();
Future get database async {
return _database ??= await _initDatabase();
}
Future _initDatabase() async {
var path = join(await getDatabasesPath(), "sample.db");
return await openDatabase(
join(path, "sample.db"),
version: 1,
onCreate: (Database db, int version) async {
await db.execute(/* do something */);
}
);
}
}
続いて、このコードにマイグレーションの処理を書き足したものを紹介します。
class DatabaseHelper {
static final DatabaseHelper instance = DatabaseHelper._();
static Database? _database;
DatabaseHelper._();
Future get database async {
return _database ??= await _initDatabase();
}
Future _initDatabase() async {
var path = join(await getDatabasesPath(), "sample.db");
return await openDatabase(
join(path, "sample.db"),
version: 2,
onCreate: (Database db, int version) async {
await db.execute(/* do something */);
await db.execute(/* do something ver2 */);
},
onUpgrade: (Database db, int oldVersion, int newVersion) async {
if (oldVersion < 2) {
await db.execute(/* do something ver2 */);
}
},
);
}
}
コードの解説
※先ほどのコードだけで伝わった方は、これより先は読まなくて大丈夫です。
マイグレーションを行う際に、ポイントとなるのは以下の点です。
- openDatabase()の引数のversionの値をインクリメントする。
- onUpgrade()でマイグレーションの内容を指定する。
- onCreate()に必要に応じてマイグレーションした結果と同じになるような処理を指定する。
まず「1」について。
マイグレーションの管理をするために、openDatabase()の引数であるversionの値をインクリメントします。
これに関しては特に説明不要ですね(笑)
次に「2」について。
データベースのマイグレーション処理は、onUpgrade()で指定します。
ここに、テーブルの新規作成処理や、カラムの追加処理などを記載します。
なお、条件に「if (oldVersion < 2)」を指定していますが、これは現在のデータベースのバージョンが「1」だった場合に実行されるようにしています。
今後もバージョンを上げる場合に「if (oldVersion < 3)」のように記載すれば、バージョンを1から3に上げた場合にも対応できるのでこのような記載にしております。
最後「3」について。
こちらは意外と忘れやすいのですが、onCreate()にマイグレーションの内容を含んだ実行内容を記載します。
DBバージョンが1の時から使用しているユーザもいれば、新規ユーザでバージョン2から使用し始める場合もあります。
その時に、onCreateの結果が、マイグレーション結果と同じ状態にならない場合、不整合が発生してしまいます。
忘れずに記載しましょう!!
まとめ
sqfliteでデータベースのマイグレーション(migration)するには、onUpgradeを使用する。
