HarmonyOS 5.0.0 或以上：实现 SQLite 表结构升级与版本管理（支持字段新增与数据迁移）

📌 场景介绍

在实际项目中，数据库表结构随着版本演进经常发生变化，如：

• 新增字段（如邮箱、创建时间等）

• 修改字段类型或索引结构

• 数据迁移（如旧字段拷贝进新表）

• 保留旧数据而不清除原表内容

本篇实现：

• 在数据库版本升级时自动检测并执行结构变更

• 新增字段：email

• 保留旧数据不丢失

• 展示升级后的完整数据

🧱 页面结构

/entry/src/main/ets
  └── pages/
       └── SQLiteUpgradeDemo.ets     // 数据库升级与迁移页面

🧩 SQLiteUpgradeDemo.ets 示例页面

import relationalStore from '@ohos.data.relationalStore'

@Entry
@Component
struct SQLiteUpgradeDemo {
  @State userList: Array<{ id: number, name: string, email: string }> = []
  private rdbStore: relationalStore.RdbStore | undefined
  private dbVersion: number = 2 // 假设版本从 1 升级到 2

  aboutToAppear() {
    this.initOrUpgradeDB()
  }

  private async initOrUpgradeDB() {
    const context = getContext(this)
    const config = {
      name: 'upgrade_demo.db',
      securityLevel: relationalStore.SecurityLevel.S1
    }

    this.rdbStore = await relationalStore.getRdbStore(context, config, this.dbVersion, {
      onCreate: async (db: relationalStore.RdbStore) => {
        const sql = `CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)`
        await db.executeSql(sql)
        await db.insert('users', { name: '张三' })
        await db.insert('users', { name: '李四' })
      },
      onUpgrade: async (db: relationalStore.RdbStore, oldVersion: number, newVersion: number) => {
        if (oldVersion < 2) {
          const alterSql = `ALTER TABLE users ADD COLUMN email TEXT`
          await db.executeSql(alterSql)
          // 可补充历史数据迁移，如设置默认 email
          await db.executeSql(`UPDATE users SET email = 'unknown@example.com'`)
        }
      }
    })

    this.queryAll()
  }

  private async queryAll() {
    const resultSet = await this.rdbStore?.querySql('SELECT * FROM users')
    const result: Array<{ id: number, name: string, email: string }> = []
    while (resultSet?.goToNextRow()) {
      result.push({
        id: resultSet.getInteger(0),
        name: resultSet.getString(1),
        email: resultSet.getString(2)
      })
    }
    resultSet?.close()
    this.userList = result
  }

  build() {
    Column() {
      Text("🧩 SQLite 表结构升级演示").fontSize(22).margin(20)
      Text("当前数据库版本：2").fontSize(14).fontColor('#999').margin(10)

      ForEach(this.userList, (user) => {
        Text(`🧑‍💻 ${user.name} | 📧 ${user.email}`).fontSize(16).margin(6)
      })
    }
    .padding(20)
    .height('100%')
    .scrollable(true)
  }
}

✅ 效果说明

• 首次运行时建表（仅有 name 字段）并插入数据

• 当数据库版本升级为 2 时自动新增 email 字段

• 使用 ALTER TABLE 和 UPDATE 保留旧数据并补充默认 email

• 最终展示升级后完整结构下的所有数据

🔧 拓展建议

• 多版本升级链：v1 → v2 → v3 连续升级逻辑封装

• 支持数据迁移备份、字段合并、字段拆分

• 升级失败回滚机制、日志记录机制

• 封装数据库版本升级类（如 DatabaseUpgradeManager）