跨平台开发 / 系统课时
处理数据库版本升级
处理数据库版本升级
本篇解决 Flutter 应用中 SQLite 数据结构变化的问题。当应用发布新版本,需要新增字段、创建新表或调整结构时,可以通过数据库版本号和升级回调安全完成迁移。
学习目标
- 理解 SQLite 数据库版本号与迁移流程。
- 掌握
version和onUpgrade的基本使用方式。 - 能够设计不会破坏已有用户数据的数据库升级方案。
数据库升级为什么需要迁移
SQLite 数据保存在用户设备中,应用升级并不会自动删除旧数据库。如果新版本代码访问了旧版本不存在的字段,就会出现查询失败或运行异常。
数据库迁移的核心任务是让旧结构逐步转换为新结构,同时保留用户已有数据。
典型流程是:打开数据库时读取当前版本,如果目标版本更高,则执行对应升级逻辑。
使用 version 控制数据库结构版本
Flutter SQLite 库通常通过 version 指定目标数据库版本,通过 onCreate 初始化首次创建,通过 onUpgrade 处理已有数据库升级。
dart
final database = await openDatabase(
'app.db',
version: 2,
onCreate: (db, version) async {
await db.execute('''
CREATE TABLE users (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL
)
''');
},
onUpgrade: (db, oldVersion, newVersion) async {
if (oldVersion < 2) {
await db.execute(
'ALTER TABLE users ADD COLUMN email TEXT',
);
}
},
);预期结果
text
首次安装:
创建 users 表,数据库版本为 2
旧版本升级:
执行 ALTER TABLE,新增 email 字段版本号应该只递增,不应该在发布版本中降低数据库版本。
编写可靠的 onUpgrade 迁移逻辑
onUpgrade 可能面对多个历史版本。例如用户可能从版本 1 直接升级到版本 3,而不是每次都经过版本 2。
因此迁移代码应该按照版本区间执行:
dart
if (oldVersion < 2) {
// v1 -> v2
}
if (oldVersion < 3) {
// v2 -> v3
}这种写法可以保证跨版本升级时,每一步结构变化都被执行。
处理表结构调整的风险
简单新增字段通常可以使用 ALTER TABLE 完成,但复杂修改需要新建表、复制数据、删除旧表等步骤。
例如修改字段类型时,直接修改列定义并不是所有 SQLite 场景都支持,需要设计完整迁移流程。
验证数据库升级结果
数据库迁移完成后,需要验证结构和数据是否符合预期。常见验证方式包括:
- 检查新增字段是否存在。
- 检查旧数据是否可以正常读取。
- 使用多个历史版本数据库测试升级路径。
数据库版本管理的关键不是简单增加一个版本号,而是维护每一次结构变化的可重复迁移过程。良好的迁移设计可以让应用长期演进,而不会因为数据库变化影响已有用户。
按自己的节奏,确认真正理解。