跨平台开发 / 系统课时

处理数据库版本升级

处理数据库版本升级

本篇解决 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 场景都支持,需要设计完整迁移流程。

验证数据库升级结果

数据库迁移完成后,需要验证结构和数据是否符合预期。常见验证方式包括:

  • 检查新增字段是否存在。
  • 检查旧数据是否可以正常读取。
  • 使用多个历史版本数据库测试升级路径。

数据库版本管理的关键不是简单增加一个版本号,而是维护每一次结构变化的可重复迁移过程。良好的迁移设计可以让应用长期演进,而不会因为数据库变化影响已有用户。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理数据库版本升级

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通