Flutter sqflite openDatabase()中'version'参数的作用是什么

version是本地SQLite数据库的schema版本标识，核心作用是支撑数据库结构迭代的自动迁移，整个逻辑由sqflite框架托管，不需要开发者自行存储版本号。

核心运行逻辑 #

sqflite会在数据库内部持久化存储最近一次设置的版本号，每次调用openDatabase()时，会先读取已存的旧版本号，和本次传入的新版本号做比对，触发对应回调：

• 当指定路径下不存在目标数据库文件（即首次启动APP创建数据库）：框架创建空数据库后，先触发onCreate回调，开发者可在回调内编写建表、插入初始默认数据的逻辑，执行完成后框架自动将本次传入的version值存入数据库元信息中。
• 当目标数据库已存在：
  • 若传入version和已存旧版本号完全相等：不触发任何版本相关回调，直接打开数据库供业务调用。
  • 若传入version 大于 已存旧版本号：触发onUpgrade回调，回调参数会返回数据库实例、旧版本号、新版本号，开发者可在此处编写表结构修改、新增表、存量数据迁移的逻辑，执行完成后框架自动更新存储的版本号为本次传入值。
  • 若传入version 小于 已存旧版本号：触发onDowngrade回调，用于处理数据库版本回退场景；如果未手动实现该回调，框架会默认抛出异常，阻断数据库打开流程。

使用注意事项 #

version必须传入大于0的正整数，传入0或负数会导致框架版本判断逻辑异常。
仅当你修改了数据库结构（比如新增字段、新增表、调整字段约束）时，才需要将version值递增，不要随意修改版本号避免触发不必要的迁移逻辑。
写onUpgrade逻辑时要做版本区间判断，保证从任意旧版本升级到最新版时，所有增量结构修改都能按顺序执行，避免出现“表不存在”“字段不存在”的SQL运行错误。

代码示例 #

final db = await openDatabase(
  'app_local.db',
  // 第二次迭代新增收藏表，版本号从1升级到2
  version: 2,
  onCreate: (db, latestVersion) async {
    // 首次安装用户直接创建最新版表结构
    await db.execute('CREATE TABLE user (id INTEGER PRIMARY KEY, nickname TEXT, avatar TEXT)');
    await db.execute('CREATE TABLE favorite (id INTEGER PRIMARY KEY, goods_id INTEGER, create_time INTEGER)');
  },
  onUpgrade: (db, oldVersion, newVersion) async {
    // 从v1升级的用户，仅补建收藏表即可
    if (oldVersion == 1) {
      await db.execute('CREATE TABLE favorite (id INTEGER PRIMARY KEY, goods_id INTEGER, create_time INTEGER)');
    }
    // 后续升级到v3、v4时，继续在此处追加对应版本的迁移逻辑即可
  },
  onDowngrade: (db, oldVersion, newVersion) async {
    // 一般生产环境很少处理降级，多用于本地调试场景
  }
);

内容的提问来源于stack exchange，提问作者Kaustubh Dixit