更新记录

1.0.1（2026-06-08）

• 发布前收口版本，统一 package.json 与诊断日志版本号为 1.0.1。
• 修复 Harmony 运行包制作时 ArkTS 严格类型编译失败的问题。
• Harmony rdbStore 的 executeSql/querySql 绑定参数统一转换为 relationalStore.ValueType[]，不再向原生 API 传入 Array<any> / Object[]。
• 修复 Harmony 端调用 number.toDouble() 导致的编译错误。
• 修复 Harmony 迁移版本读取中 UTSJSONObject 动态索引触发 arkts-no-any-unknown 的问题，改为直接从 ResultSet.getLong(0) 读取。
• 复核 Harmony 迁移版本读取不再使用 UTSJSONObject 动态索引，空参数和参数化 SQL 均使用 relationalStore.ValueType[]。
• 补充 README 示例代码注释规范和回归守卫，所有文档示例代码块均包含说明注释。
• 完善发布文档体验：README 示例代码均包含中文注释，便于客户复制后理解调用顺序和平台边界。
• 优化演示组件按钮区域为一行三个，并为示例组件方法补齐用途注释。
• 修复 SQLite Pro 页面【快速上手】嵌套回调中 this.dbName 丢失导致的运行时错误。

1.0.0（2026-06-08）

• 首版新增 lizhao-sqlite-pro 纯 UTS SQLite Pro 插件。
• Android 使用系统 android.database.sqlite.SQLiteDatabase 实现真实 SQLite 打开、关闭、执行、查询、事务、参数化 SQL、批处理、迁移和备份恢复。
• iOS 使用系统 SQLite3 C API 实现真实 SQLite 打开、关闭、执行、查询、事务、参数化 SQL、批处理、迁移和备份恢复。
• Harmony 使用系统 @ohos.data.relationalStore / rdbStore 实现真实关系型数据库打开、关闭、执行、查询、事务、参数化 SQL、批处理、迁移和备份恢复。
• Web、微信小程序、支付宝小程序提供 SQL 子集降级，并通过能力矩阵明确不等同完整原生 SQLite。
• 新增演示组件、示例页、诊断日志和结构守卫脚本。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lizhao-sqlite-pro

lizhao-sqlite-pro 是纯 UTS SQLite Pro 数据库插件，面向 uni-app / uni-app x。插件兼容 plus.sqlite 风格 API，并扩展参数化 SQL、批处理、迁移、备份恢复、导入导出、能力矩阵和诊断日志。

支持平台

安装与引入

页面和业务代码只能从插件根目录导入，不要直接引用 utssdk 内部文件。

// 从插件根目录统一导入公开 API，不要直接引用 utssdk 内部文件。
import {
  openDatabase,
  isOpenDatabase,
  closeDatabase,
  transaction,
  executeSql,
  selectSql,
  getDatabasePath,
  executePrepared,
  batch,
  runMigrations,
  backupDatabase,
  restoreDatabase,
  exportDatabase,
  importDatabase,
  getCapabilities,
  getDiagnostics,
  clearDiagnostics
} from '@/uni_modules/lizhao-sqlite-pro'

自定义基座说明

API 列表

快速上手示例

下面示例展示最常用的打开数据库、建表、参数化写入和查询流程。页面和业务代码仍然只从插件根目录导入。

// 快速上手：打开数据库 -> 建表 -> 参数化写入 -> 查询结果。
import {
  openDatabase,
  executeSql,
  executePrepared,
  selectSql
} from '@/uni_modules/lizhao-sqlite-pro'

const dbName = 'demo'

// 打开或创建演示数据库。
openDatabase({
  name: dbName,
  success() {
    // 数据库打开后创建用户表。
    executeSql({
      name: dbName,
      sql: 'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER)',
      success() {
        // 使用 ? 占位符写入数据，避免 SQL 字符串拼接。
        executePrepared({
          name: dbName,
          sql: 'INSERT INTO users (name, age) VALUES (?, ?)',
          params: ['Alice', 30],
          success() {
            // 写入成功后查询全部用户数据。
            selectSql({
              name: dbName,
              sql: 'SELECT * FROM users',
              success(rows) {
                console.log('查询结果', rows)
              },
              fail(err) {
                console.log('查询失败', err)
              }
            })
          },
          fail(err) {
            console.log('写入失败', err)
          }
        })
      },
      fail(err) {
        console.log('建表失败', err)
      }
    })
  },
  fail(err) {
    console.log('打开数据库失败', err)
  }
})

openDatabase(options)

说明 打开或创建数据库。

参数

返回值

示例

// 打开或创建 demo 数据库。
openDatabase({
  name: 'demo',
  success(res) {
    console.log('打开成功', res)
  },
  fail(err) {
    console.log('打开失败', err)
  },
  complete(res) {
    console.log('打开完成', res)
  }
})

isOpenDatabase(options)

说明 判断数据库是否已经打开，同时会触发 success / complete 返回当前状态。

参数

返回值

示例

// 同步返回 opened，同时通过 success / complete 拿到状态对象。
const opened = isOpenDatabase({
  name: 'demo',
  success(res) {
    console.log('状态查询成功', res)
  },
  complete(res) {
    console.log('状态查询完成', res)
  }
})
console.log('当前是否打开', opened)

closeDatabase(options)

说明 关闭已打开的数据库。

参数

返回值

示例

// 关闭已经打开的 demo 数据库。
closeDatabase({
  name: 'demo',
  success(res) {
    console.log('关闭成功', res)
  },
  fail(err) {
    console.log('关闭失败', err)
  }
})

transaction(options)

说明 执行事务控制。begin 开启事务，commit 提交事务，rollback 回滚事务。

参数

返回值

示例

// 开启事务；提交和回滚时把 operation 改为 commit 或 rollback。
transaction({
  name: 'demo',
  operation: 'begin',
  success(res) {
    console.log('事务开启成功', res)
  },
  fail(err) {
    console.log('事务开启失败', err)
  }
})

executeSql(options)

说明 执行建表、插入、更新、删除等非查询 SQL。多条 SQL 请传数组。

参数

返回值

示例

// 执行建表和清理数据，多条 SQL 可以使用数组。
executeSql({
  name: 'demo',
  sql: [
    'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER)',
    'DELETE FROM users'
  ],
  success(res) {
    console.log('SQL 执行成功', res)
  },
  fail(err) {
    console.log('SQL 执行失败', err)
  }
})

selectSql(options)

说明 执行查询 SQL，成功回调返回行数组。

参数

返回值

示例

// 执行普通查询 SQL，success 回调参数是结果行数组。
selectSql({
  name: 'demo',
  sql: 'SELECT * FROM users ORDER BY id DESC',
  success(rows) {
    console.log('查询结果', rows)
  },
  fail(err) {
    console.log('查询失败', err)
  }
})

getDatabasePath(name)

说明 获取当前平台的数据库路径。App 端返回沙盒内真实路径，Web/小程序返回降级标识路径。

参数

返回值

示例

// 获取当前平台下 demo 数据库的实际路径或降级标识路径。
const path = getDatabasePath('demo')
console.log('数据库路径', path)

executePrepared(options)

说明 执行带 ? 占位符的参数化 SQL，用于避免字符串拼接带来的 SQL 注入风险。

参数

返回值

示例

// 使用 ? 占位符做参数化写入，避免 SQL 注入风险。
executePrepared({
  name: 'demo',
  sql: 'INSERT INTO users (name, age) VALUES (?, ?)',
  params: ['Alice', 30],
  query: false,
  success(res) {
    console.log('参数化写入成功', res)
  },
  fail(err) {
    console.log('参数化写入失败', err)
  }
})

batch(options)

说明 批量执行 SQL，可选择事务包裹和失败回滚。每个条目都支持 ? 参数。

参数

返回值

示例

// 使用事务批量执行多条参数化 SQL，失败时自动回滚。
batch({
  name: 'demo',
  transaction: true,
  rollbackOnFail: true,
  items: [
    { sql: 'INSERT INTO users (name, age) VALUES (?, ?)', params: ['Bob', 25] },
    { sql: 'INSERT INTO users (name, age) VALUES (?, ?)', params: ['Charlie', 35] }
  ],
  success(res) {
    console.log('批处理成功', res)
  },
  fail(err) {
    console.log('批处理失败', err)
  }
})

runMigrations(options)

说明 按版本顺序执行迁移脚本，并把已执行版本记录到迁移表中。

参数

返回值

示例

// 按版本顺序执行迁移脚本，已执行版本会被记录。
runMigrations({
  name: 'demo',
  migrations: [
    {
      version: 1,
      name: 'create-settings',
      sql: ['CREATE TABLE IF NOT EXISTS settings (key TEXT PRIMARY KEY, value TEXT)']
    },
    {
      version: 2,
      name: 'seed-settings',
      sql: ["INSERT OR REPLACE INTO settings (key, value) VALUES ('demo_version', '2')"]
    }
  ],
  success(res) {
    console.log('迁移成功', res)
  },
  fail(err) {
    console.log('迁移失败', err)
  }
})

backupDatabase(options)

说明 备份数据库文件。App 原生平台需要传入应用可访问的目标路径；Web/小程序降级平台没有真实数据库文件，会触发失败回调。

参数

返回值

示例

// 备份 demo 数据库到同目录 .bak 文件。
backupDatabase({
  name: 'demo',
  path: getDatabasePath('demo') + '.bak',
  success(res) {
    console.log('备份成功', res)
  },
  fail(err) {
    console.log('备份失败', err)
  }
})

restoreDatabase(options)

说明 从备份文件恢复数据库。部分平台恢复时会关闭当前连接，再替换数据库文件。

参数

返回值

示例

// 从 .bak 备份文件恢复 demo 数据库。
restoreDatabase({
  name: 'demo',
  path: getDatabasePath('demo') + '.bak',
  success(res) {
    console.log('恢复成功', res)
  },
  fail(err) {
    console.log('恢复失败', err)
  }
})

exportDatabase(options)

说明 导出数据库内容摘要。当前首版 App 端返回数据库路径和导出元数据；降级平台返回内存表快照摘要。

参数

返回值

示例

// 导出数据库摘要或文件信息，具体能力以平台能力矩阵为准。
exportDatabase({
  name: 'demo',
  success(res) {
    console.log('导出成功', res)
  },
  fail(err) {
    console.log('导出失败', err)
  }
})

importDatabase(options)

说明 导入数据库。iOS/Harmony 支持通过 path 导入数据库文件；Android 首版建议使用 restoreDatabase({ name, path }) 完成文件恢复；Web/小程序降级平台会明确失败。

参数

返回值

示例

// 从备份路径或数据载荷导入数据库，降级端会明确失败。
importDatabase({
  name: 'demo',
  path: getDatabasePath('demo') + '.bak',
  data: '',
  success(res) {
    console.log('导入成功', res)
  },
  fail(err) {
    console.log('导入失败或平台暂不支持', err)
  }
})

getCapabilities()

说明 获取当前平台能力矩阵，用于区分 App 原生 SQLite、Web/小程序降级 SQL 子集和自定义基座要求。

参数

返回值

示例

// 读取当前平台能力矩阵，用于判断是否为原生 SQLite。
const capabilities = getCapabilities()
console.log('能力矩阵', capabilities)

getDiagnostics(options)

说明 获取中文诊断快照，包括插件版本、平台适配器、已打开数据库和最近日志。

参数

返回值

示例

// 读取诊断快照，includeLogs=true 会返回最近诊断日志。
const diagnostics = getDiagnostics({ includeLogs: true })
console.log('诊断日志', diagnostics)

clearDiagnostics()

说明 清空插件内部诊断日志。

参数

返回值

示例

// 清空插件内部诊断日志。
clearDiagnostics()
console.log('诊断日志已清空')

完整功能演示

下面示例覆盖插件全部公开 API，适合作为项目接入后的回归演示。Web/小程序会按能力矩阵降级；备份恢复和部分导入能力在降级平台会触发 fail / complete，不会伪造成功。

// 完整回归示例：覆盖兼容 API、增强 API、迁移、备份恢复和诊断日志。
import {
  openDatabase,
  isOpenDatabase,
  closeDatabase,
  transaction,
  executeSql,
  selectSql,
  getDatabasePath,
  executePrepared,
  batch,
  runMigrations,
  backupDatabase,
  restoreDatabase,
  exportDatabase,
  importDatabase,
  getCapabilities,
  getDiagnostics,
  clearDiagnostics
} from '@/uni_modules/lizhao-sqlite-pro'

const dbName = 'lizhao_sqlite_pro_demo'
const dbPath = getDatabasePath(dbName)
const backupPath = dbPath + '.bak'

// 统一打印示例日志，方便在控制台筛选插件输出。
function logResult(label: string, value: any) {
  console.log('[lizhao-sqlite-pro]', label, value)
}

// 统一包装 success / fail / complete，确保示例保留真实回调路径。
function callSqlite(label: string, options: any, invoke: (opts: any) => void): Promise<any> {
  return new Promise((resolve) => {
    let settled = false
    // 只用 success/fail 决定 Promise 结果，complete 仅记录日志。
    const done = (ok: boolean, payload: any) => {
      if (settled) return
      settled = true
      resolve({ ok, payload })
    }
    invoke({
      ...options,
      success(res: any) {
        logResult(label + ' success', res)
        done(true, res)
      },
      fail(err: any) {
        logResult(label + ' fail', err)
        done(false, err)
      },
      complete(res: any) {
        logResult(label + ' complete', res)
      }
    })
  })
}

// 一键运行全部核心能力，适合作为接入后的回归脚本。
export async function runLizhaoSqliteProDemo() {
  // 先清空旧诊断，避免历史日志干扰本次演示。
  clearDiagnostics()
  logResult('getCapabilities', getCapabilities())
  logResult('getDatabasePath', dbPath)

  // 打开数据库后再执行建表、写入和查询。
  const opened = await callSqlite('openDatabase', { name: dbName }, openDatabase)
  const openStatus = isOpenDatabase({
    name: dbName,
    success(res) {
      logResult('isOpenDatabase success', res)
    },
    complete(res) {
      logResult('isOpenDatabase complete', res)
    }
  })
  logResult('isOpenDatabase return', openStatus)

  if (!opened.ok) return

  // 初始化演示表，并清理上一次运行留下的数据。
  await callSqlite('executeSql create', {
    name: dbName,
    sql: [
      'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER)',
      'CREATE TABLE IF NOT EXISTS audit_logs (id INTEGER PRIMARY KEY AUTOINCREMENT, action TEXT, created_at INTEGER)',
      'DELETE FROM users',
      'DELETE FROM audit_logs'
    ]
  }, executeSql)

  // 手动演示事务 begin -> 参数化写入 -> commit/rollback。
  await callSqlite('transaction begin', { name: dbName, operation: 'begin' }, transaction)
  const insertResult = await callSqlite('executePrepared insert', {
    name: dbName,
    sql: 'INSERT INTO users (name, age) VALUES (?, ?)',
    params: ['Alice', 30],
    query: false
  }, executePrepared)

  await callSqlite(insertResult.ok ? 'transaction commit' : 'transaction rollback', {
    name: dbName,
    operation: insertResult.ok ? 'commit' : 'rollback'
  }, transaction)

  // 批处理会在事务中连续执行多条参数化 SQL。
  await callSqlite('batch', {
    name: dbName,
    transaction: true,
    rollbackOnFail: true,
    items: [
      { sql: 'INSERT INTO users (name, age) VALUES (?, ?)', params: ['Bob', 25] },
      { sql: 'INSERT INTO users (name, age) VALUES (?, ?)', params: ['Charlie', 35] },
      { sql: 'INSERT INTO audit_logs (action, created_at) VALUES (?, ?)', params: ['batch-insert', Date.now()] }
    ]
  }, batch)

  // 迁移脚本会按版本记录，重复执行不会重复应用旧版本。
  await callSqlite('runMigrations', {
    name: dbName,
    migrations: [
      {
        version: 1,
        name: 'create-settings',
        sql: ['CREATE TABLE IF NOT EXISTS settings (key TEXT PRIMARY KEY, value TEXT)']
      },
      {
        version: 2,
        name: 'seed-settings',
        sql: ["INSERT OR REPLACE INTO settings (key, value) VALUES ('demo_version', '2')"]
      }
    ]
  }, runMigrations)

  // 分别验证参数化查询和普通 selectSql 查询。
  await callSqlite('executePrepared query', {
    name: dbName,
    sql: 'SELECT * FROM users WHERE age >= ?',
    params: [25],
    query: true
  }, executePrepared)

  await callSqlite('selectSql', {
    name: dbName,
    sql: 'SELECT * FROM users'
  }, selectSql)

  // App 原生端可验证文件备份恢复，降级端会进入 fail/complete。
  await callSqlite('exportDatabase', { name: dbName }, exportDatabase)
  await callSqlite('backupDatabase', { name: dbName, path: backupPath }, backupDatabase)
  await callSqlite('restoreDatabase', { name: dbName, path: backupPath }, restoreDatabase)
  await callSqlite('importDatabase', { name: dbName, path: backupPath, data: '' }, importDatabase)

  // 演示结束前输出诊断，再清空诊断并关闭数据库。
  logResult('getDiagnostics', getDiagnostics({ includeLogs: true }))
  clearDiagnostics()

  await callSqlite('closeDatabase', { name: dbName }, closeDatabase)
}

错误码

演示组件

<template>
  <!-- 在页面中直接使用插件演示组件。 -->
  <lizhao-sqlite-pro />
</template>

组件路径：uni_modules/lizhao-sqlite-pro/components/lizhao-sqlite-pro/lizhao-sqlite-pro.vue

注意事项

• App 端 SQL 语句不要用分号拼接多条命令，多条命令请传数组或使用 batch。
• Web/小程序降级能力只适合演示、轻量缓存和接口连通性测试，不可当作完整 SQLite 文件数据库。
• 受限平台或受限 SQL 会进入 fail / complete；插件承诺不伪造成功，也不会把降级结果宣传为完整 SQLite。
• Android 首版 importDatabase 会提示使用 restoreDatabase({ name, path }) 做文件恢复；iOS/Harmony 支持通过 path 导入数据库文件。
• exportDatabase 首版主要返回数据库路径和元数据摘要，表级 JSON 完整导出可在后续版本扩展。
• Harmony 使用 rdbStore 原生关系型数据库，backupDatabase/restoreDatabase 走 rdbStore 自带备份恢复；如需跨应用任意路径导入导出，请先用平台文件能力把文件放到应用可访问路径。