更新记录

1.0.19（2026-07-23）

• 修复插件市场 1.0.18 加密试用包在 uni-app x Web 仍提示 utssdk/web/index.uts is not a module，并因 index.module.js 缺少 SqlTransactionOperation 运行时导出而导致页面空白的问题。
• Web 平台入口由会被收费 UTS 发布流程加密的 index.uts 改为自包含 index.js；JavaScript 实现不导入任何 .uts 运行时代码，完整保留内存 SQL 子集、回调、错误码、诊断、JSON 导入导出和能力矩阵。
• Web index.js 对 interface.uts 的 69 个公开类型使用 JSDoc 类型合并，并提供对应 ESM named export；既兼容 HBuilderX 错误保留 import type 的运行时链接，又不会把值遮蔽成类型。
• HBuilderX 5.15 Web 发布已验证缺失导出、值当类型和 SQLite 模块 warning 均为 0；浏览器页面完整显示，快速上手已完成打开、建表、参数化写入和查询。
• 本轮只改变 Web 平台实现与版本资料；公开接口、Android/iOS/Harmony/小程序实现、原 uni-app 演示组件、权限、依赖和资源保持不变，无需仅为本次 Web 修复重打 App 自定义基座。

1.0.18（2026-07-23）

• 修复插件市场加密版 1.0.17 在 uni-app x Web 运行时仍把 SqlTransactionOperation 当作浏览器 named import、而加密 index.module.js 不提供该运行时导出导致页面空白的问题。
• 自动收集内置组件与 uni-app x 示例的 23 个根路径类型，确认 Web export type 已完整，但 import type 仍遗漏 SqlTransactionOperation / BatchSqlItem / BatchCrudItem / MigrationItem / DatabaseTransferResult；本版本一次补齐全部 5 项，避免错误逐个暴露。
• Web 入口现在对打包消费者类型保持 import type + export type 声明面对称，为市场加密/云解密编译提供可解析并擦除的完整类型来源；发布守卫会自动阻止后续新增消费者类型时再次漏转发。
• 本轮功能代码只修改 Web 入口纯类型 import，不改 .uvue 调用逻辑、公开接口、Android/iOS/Harmony/小程序实现、原 uni-app .vue、权限、依赖或资源，无需重打 App 自定义基座。

1.0.17（2026-07-23）

• 修复 1.0.16 在 uni-app x Web 消费者工程中加载内置 .uvue 组件时，平台专属 utssdk/web/index.uts 未导出组件所需类型，导致页面空白及 does not provide an export named 'BatchCrudItem' 的问题。
• Web 入口现通过 export type 完整转发组件使用的 SqlTransactionOperation / BatchSqlItem / BatchCrudItem / MigrationItem；这些声明只参与编译期检查，不进入浏览器运行时代码。
• 修复前真实 Web 发布复现 4 条未导出警告；补齐转发后 HBuilderX 5.15 Web 发布无上述 warning，生成页面分包不再包含这些类型的运行时 named import/export。
• 本轮功能代码只修改 Web 类型转发层；不改公开接口、Android/iOS/Harmony/小程序实现、原 uni-app .vue 组件、权限、依赖或资源，不需要重新制作 App 自定义基座。

平台兼容性

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，并扩展结构化 CRUD、参数化 SQL、批处理、迁移、备份恢复、导入导出、能力矩阵和诊断日志。

当前版本

接入方式怎么选

支持平台

付费加密试用说明： DCloud 的付费 UTS 原生实现仍按平台规则加密，App 试用需使用自定义基座。1.0.19 起，Web 内存降级实现独立放在不含原生能力的 utssdk/web/index.js，不会再依赖被加密的 Web .uts 模块，因此市场试用 Web 也应能正常加载页面。正式发布后仍需用另一账号删除旧插件并重新下载复验，以市场分发产物为最终依据。

安装与引入

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

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

目录结构说明

权限说明

自定义基座说明

iOS 本版本修改了原生 UTS 实现，仅同步 wgt/appResource 不能让真机旧基座获得修复。如果 HBuilderX 提示手机端自定义基座“已是最新版本”并跳过更新，请确认已安装的新包二进制确实变化；必要时先卸载旧基座或提升 iOS 构建号后再安装。

iOS 重装新基座后可使用仓库脚本自动跑结构化 CRUD 验收：

# 该脚本会运行 iOS appResource 导出、启动 SQLite Pro 示例页，并检查结构化 CRUD 日志与 crash report。
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\acceptance-lizhao-sqlite-pro-ios.ps1 -ConfirmInstalledCustomBase -DeviceId <设备UDID>

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)
  }
})

常见增强示例

跑通快速上手后，通常会继续补四类能力：先用结构化 CRUD 减少手写 SQL，再配置数据库稳定性参数，之后查看结构和健康状态，最后用 JSON 导出导入做数据搬迁或调试留档。

结构化 CRUD

结构化 CRUD 适合业务侧不想手写完整 SQL 的场景。where 支持两种写法：一种是 SQL 片段 + whereParams，另一种是对象式条件数组。对象式条件数组不支持任意对象动态键，例如 { age: 18 }，这是为了兼容 Harmony ArkTS 对 UTSJSONObject 动态下标的严格限制。

// 结构化 CRUD：用配置项表达 where/orderBy/groupBy/having/limit/offset。
import {
  selectRows,
  insertRow,
  updateRows,
  deleteRows,
  batchCrud
} from '@/uni_modules/lizhao-sqlite-pro'

// 片段 + 参数：适合已有 SQL 条件片段的业务。
selectRows({
  name: 'demo',
  table: 'users',
  columns: ['age', 'COUNT(*) AS total'],
  where: 'age >= ? AND status = ?',
  whereParams: [18, 'active'],
  groupBy: 'age',
  having: 'COUNT(*) > ?',
  havingParams: [0],
  orderBy: 'age DESC',
  limit: 10,
  offset: 0,
  success(rows) {
    console.log('分页分组查询结果', rows)
  },
  fail(err) {
    console.log('结构化查询失败', err)
  }
})

// 对象式条件数组：常用操作符由插件转换成参数化 SQL。
selectRows({
  name: 'demo',
  table: 'users',
  columns: ['id', 'name', 'age'],
  where: [
    { column: 'age', op: '>=', value: 18 },
    { column: 'name', op: 'LIKE', value: 'A%', connector: 'AND' }
  ],
  orderBy: [{ column: 'id', direction: 'DESC' }],
  limit: 10,
  success(rows) {
    console.log('对象式条件查询结果', rows)
  }
})

// 新增、更新、删除都用字段数组表达，字段值会通过 ? 参数绑定。
insertRow({
  name: 'demo',
  table: 'users',
  values: [
    { column: 'name', value: 'Alice' },
    { column: 'age', value: 30 },
    { column: 'status', value: 'active' }
  ],
  success(res) {
    console.log('结构化新增成功', res)
  }
})

updateRows({
  name: 'demo',
  table: 'users',
  values: [{ column: 'status', value: 'vip' }],
  where: [{ column: 'age', op: '>=', value: 30 }],
  success(res) {
    console.log('结构化更新成功', res)
  }
})

deleteRows({
  name: 'demo',
  table: 'users',
  where: [{ column: 'status', op: '=', value: 'inactive' }],
  success(res) {
    console.log('结构化删除成功', res)
  }
})

// 批量增删查改复用事务，失败时按 rollbackOnFail 回滚。
batchCrud({
  name: 'demo',
  transaction: true,
  rollbackOnFail: true,
  items: [
    {
      action: 'insert',
      table: 'users',
      values: [
        { column: 'name', value: 'Bob' },
        { column: 'age', value: 25 }
      ]
    },
    {
      action: 'select',
      table: 'users',
      where: [{ column: 'age', op: 'IN', values: [25, 30] }],
      orderBy: [{ column: 'id', direction: 'DESC' }],
      limit: 5
    }
  ],
  success(res) {
    console.log('结构化批量执行成功', res.results)
  }
})

配置 PRAGMA

// App 原生端建议在打开数据库后配置外键、WAL 和 busy timeout。
import { configureDatabase } from '@/uni_modules/lizhao-sqlite-pro'

configureDatabase({
  name: 'demo',
  foreignKeys: true,
  journalMode: 'WAL',
  busyTimeoutMs: 3000,
  synchronous: 'NORMAL',
  success(res) {
    console.log('PRAGMA 配置成功', res.applied, res.values)
  },
  fail(err) {
    console.log('PRAGMA 配置失败', err)
  }
})

数据库健康检查

// 健康检查会返回 quick_check/integrity_check 结果、表数量和警告信息。
import { runHealthCheck } from '@/uni_modules/lizhao-sqlite-pro'

runHealthCheck({
  name: 'demo',
  fullCheck: false,
  includeTableStats: true,
  success(res) {
    console.log('数据库健康检查', res.ok, res.integrity, res.warnings)
  },
  fail(err) {
    console.log('健康检查失败', err)
  }
})

结构检查

// 结构检查适合在发布前或售后排查时确认表结构、列名、行数和样例数据。
import { inspectDatabase } from '@/uni_modules/lizhao-sqlite-pro'

inspectDatabase({
  name: 'demo',
  includeSampleRows: true,
  sampleLimit: 2,
  success(res) {
    console.log('表数量', res.tableCount)
    console.log('表结构', res.tables)
  }
})

JSON 导出导入

// JSON 导出会返回 format/schema/tables/rows，可直接作为 importDatabase 的 data 使用。
import { exportDatabase, importDatabase } from '@/uni_modules/lizhao-sqlite-pro'

exportDatabase({
  name: 'demo',
  success(res) {
    console.log('JSON 导出表数量', res.tableCount)
    importDatabase({
      name: 'demo',
      data: res.data,
      success(importRes) {
        console.log('JSON 导入表数量', importRes.tableCount)
      },
      fail(err) {
        console.log('JSON 导入失败', err)
      }
    })
  },
  fail(err) {
    console.log('JSON 导出失败', err)
  }
})

uni-app 调用示例

下面示例适用于普通 uni-app Vue 页面。Web 端会使用内存 SQL 子集降级，App 端在原生联编后使用真实 SQLite。

<template>
  <view>
    <!-- 点击按钮后执行最小数据库写入流程。 -->
    <button @click="createDemoUser">写入演示用户</button>
  </view>
</template>

<script>
import { openDatabase, executeSql } from '@/uni_modules/lizhao-sqlite-pro'

export default {
  methods: {
    createDemoUser() {
      // 先打开数据库，再创建表并写入演示数据。
      openDatabase({
        name: 'demo',
        success() {
          executeSql({
            name: 'demo',
            sql: [
              'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)',
              "INSERT INTO users (name) VALUES ('uni-app')"
            ],
            success(res) {
              console.log('uni-app 写入成功', res)
            },
            fail(err) {
              console.log('uni-app 写入失败', err)
            }
          })
        },
        fail(err) {
          console.log('uni-app 打开失败', err)
        }
      })
    }
  }
}
</script>

uni-app x 调用示例

下面示例适用于 uni-app x 页面脚本。复杂业务建议优先使用 interface.uts 中声明的类型约束参数。

<template>
  <view>
    <!-- uni-app x 中同样只从插件根目录调用公开 API。 -->
    <button @click="queryDemoUsers">查询演示用户</button>
  </view>
</template>

<script setup lang="uts">
import { openDatabase, selectSql } from '@/uni_modules/lizhao-sqlite-pro'

// 查询前先确保数据库已打开，失败回调会返回 SqliteFail。
function queryDemoUsers(): void {
  openDatabase({
    name: 'demo',
    success() {
      selectSql({
        name: 'demo',
        sql: 'SELECT * FROM users',
        success(rows: any) {
          console.log('uni-app x 查询结果', rows)
        },
        fail(err) {
          console.log('uni-app x 查询失败', err)
        }
      })
    },
    fail(err) {
      console.log('uni-app x 打开失败', err)
    }
  })
}
</script>

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)
  }
})

selectRows(options)

说明 执行结构化查询。插件会把 table / columns / where / groupBy / having / orderBy / limit / offset 转成参数化查询 SQL。

参数

返回值

示例

// 使用结构化配置完成 where、排序和分页查询。
selectRows({
  name: 'demo',
  table: 'users',
  columns: ['id', 'name', 'age'],
  where: [
    { column: 'age', op: '>=', value: 18 },
    { column: 'name', op: 'LIKE', value: 'A%' }
  ],
  orderBy: [{ column: 'id', direction: 'DESC' }],
  limit: 10,
  offset: 0,
  success(rows) {
    console.log('结构化查询结果', rows)
  }
})

insertRow(options)

说明 执行结构化单行新增。字段和值通过 values 数组传入，值会通过 ? 参数绑定。

参数

返回值

示例

// 使用字段数组新增单行数据，字段值自动参数化绑定。
insertRow({
  name: 'demo',
  table: 'users',
  values: [
    { column: 'name', value: 'Alice' },
    { column: 'age', value: 30 }
  ],
  success(res) {
    console.log('结构化新增成功', res)
  }
})

updateRows(options)

说明 执行结构化更新。默认必须传入 where，如果确实需要更新全表，必须显式传 allowAll: true。

参数

返回值

示例

// 更新时建议始终传 where，避免误操作全表。
updateRows({
  name: 'demo',
  table: 'users',
  values: [{ column: 'status', value: 'vip' }],
  where: [{ column: 'age', op: '>=', value: 30 }],
  success(res) {
    console.log('结构化更新成功', res)
  }
})

deleteRows(options)

说明 执行结构化删除。默认必须传入 where，如果确实需要删除全表，必须显式传 allowAll: true。

参数

返回值

示例

// 删除建议传明确 where；全表删除必须传 allowAll: true。
deleteRows({
  name: 'demo',
  table: 'users',
  where: [{ column: 'status', op: '=', value: 'inactive' }],
  success(res) {
    console.log('结构化删除成功', res)
  }
})

batchCrud(options)

说明 执行结构化批量增删查改。插件会先把每个条目转换为参数化 SQL，再复用 batch 的事务和回滚能力。

参数

返回值

示例

// 使用 batchCrud 在事务中执行结构化新增和查询。
batchCrud({
  name: 'demo',
  transaction: true,
  rollbackOnFail: true,
  items: [
    {
      action: 'insert',
      table: 'users',
      values: [
        { column: 'name', value: 'Bob' },
        { column: 'age', value: 25 }
      ]
    },
    {
      action: 'select',
      table: 'users',
      where: [{ column: 'age', op: '>=', value: 18 }],
      orderBy: [{ column: 'id', direction: 'DESC' }],
      limit: 10
    }
  ],
  success(res) {
    console.log('结构化批量结果', res.results)
  }
})

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)

说明 导出数据库为稳定 JSON 文本。JSON 顶层包含 format / schema / tables / rows，可以保存到业务文件，也可以直接传给 importDatabase({ data }) 做恢复。App 端会导出真实表结构和行数据；Web/小程序降级端导出当前内存 SQL 子集中的表数据。

参数

返回值

示例

// 导出稳定 JSON 文本，data 可直接用于 importDatabase。
exportDatabase({
  name: 'demo',
  success(res) {
    console.log('JSON 导出成功', res.tableCount, res.data)
  },
  fail(err) {
    console.log('导出失败', err)
  }
})

importDatabase(options)

说明 导入数据库。优先支持 data 传入 lizhao-sqlite-pro-json 文本，插件会按 JSON 中的 tables 重建表并写入行数据。Android/iOS 也支持 path 指向 JSON 文件；如果 path 指向普通数据库备份文件，则按文件恢复兜底处理。Web/小程序降级端支持导入自身导出的 JSON 数据。

参数

返回值

示例

// 先导出 JSON，再把同一份 JSON 导入回数据库。
exportDatabase({
  name: 'demo',
  success(exportRes) {
    importDatabase({
      name: 'demo',
      data: exportRes.data,
      success(importRes) {
        console.log('JSON 导入成功', importRes.tableCount)
      },
      fail(err) {
        console.log('JSON 导入失败', err)
      }
    })
  },
  fail(err) {
    console.log('JSON 导出失败', err)
  }
})

configureDatabase(options)

说明 配置数据库常用 PRAGMA。建议在 openDatabase 成功后调用，用于启用外键、WAL、忙碌等待和同步级别。Web/小程序降级端会明确返回已降级说明，不伪造原生 PRAGMA 生效。

参数

返回值

示例

// 打开数据库后配置常用稳定性参数。
configureDatabase({
  name: 'demo',
  foreignKeys: true,
  journalMode: 'WAL',
  busyTimeoutMs: 3000,
  synchronous: 'NORMAL',
  success(res) {
    console.log('PRAGMA 配置成功', res)
  }
})

inspectDatabase(options)

说明 检查数据库结构，返回表数量、建表 SQL、列名、行数和可选样例行。适合发布前自检、售后排查、导出前确认表结构。

参数

返回值

示例

// 检查表结构并返回少量样例数据。
inspectDatabase({
  name: 'demo',
  includeSampleRows: true,
  sampleLimit: 2,
  success(res) {
    console.log('数据库结构', res.tables)
  }
})

runHealthCheck(options)

说明 运行数据库健康检查。App 端执行 PRAGMA quick_check 或 PRAGMA integrity_check，并可返回表统计和警告信息；Web/小程序降级端返回内存表状态。

参数

返回值

示例

// 快速检查数据库是否健康。
runHealthCheck({
  name: 'demo',
  fullCheck: false,
  includeTableStats: true,
  success(res) {
    console.log('健康检查', res.ok, res.integrity, res.warnings)
  }
})

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,
  selectRows,
  insertRow,
  updateRows,
  deleteRows,
  batchCrud,
  runMigrations,
  backupDatabase,
  restoreDatabase,
  exportDatabase,
  importDatabase,
  configureDatabase,
  inspectDatabase,
  runHealthCheck,
  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)

  // 结构化 CRUD 会生成参数化 SQL，业务侧不用拼完整 SELECT/INSERT/UPDATE/DELETE。
  await callSqlite('insertRow', {
    name: dbName,
    table: 'users',
    values: [
      { column: 'name', value: 'Daisy' },
      { column: 'age', value: 28 }
    ]
  }, insertRow)

  await callSqlite('selectRows', {
    name: dbName,
    table: 'users',
    columns: ['id', 'name', 'age'],
    where: [
      { column: 'age', op: '>=', value: 18 },
      { column: 'name', op: 'LIKE', value: 'D%' }
    ],
    orderBy: [{ column: 'id', direction: 'DESC' }],
    limit: 10,
    offset: 0
  }, selectRows)

  await callSqlite('updateRows', {
    name: dbName,
    table: 'users',
    values: [{ column: 'age', value: 29 }],
    where: 'name = ?',
    whereParams: ['Daisy']
  }, updateRows)

  await callSqlite('deleteRows', {
    name: dbName,
    table: 'users',
    where: [{ column: 'name', op: '=', value: 'nobody' }]
  }, deleteRows)

  await callSqlite('batchCrud', {
    name: dbName,
    transaction: true,
    rollbackOnFail: true,
    items: [
      {
        action: 'insert',
        table: 'users',
        values: [
          { column: 'name', value: 'Eve' },
          { column: 'age', value: 32 }
        ]
      },
      {
        action: 'select',
        table: 'users',
        where: [{ column: 'age', op: 'BETWEEN', values: [25, 40] }],
        orderBy: [{ column: 'age', direction: 'DESC' }],
        limit: 5
      }
    ]
  }, batchCrud)

  // 打开后配置 PRAGMA，常见生产设置包括外键、WAL 和 busy timeout。
  await callSqlite('configureDatabase', {
    name: dbName,
    foreignKeys: true,
    journalMode: 'WAL',
    busyTimeoutMs: 3000,
    synchronous: 'NORMAL'
  }, configureDatabase)

  // 导出前先检查结构，必要时带少量样例行辅助排查。
  await callSqlite('inspectDatabase', {
    name: dbName,
    includeSampleRows: true,
    sampleLimit: 2
  }, inspectDatabase)

  // 健康检查用于确认数据库 quick_check/integrity_check 状态。
  await callSqlite('runHealthCheck', {
    name: dbName,
    fullCheck: false,
    includeTableStats: true
  }, runHealthCheck)

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

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

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

错误码

演示组件

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

组件采用 easycom 同名双入口，无需手动 import：

• uni-app：uni_modules/lizhao-sqlite-pro/components/lizhao-sqlite-pro/lizhao-sqlite-pro.vue
• uni-app x：uni_modules/lizhao-sqlite-pro/components/lizhao-sqlite-pro/lizhao-sqlite-pro.uvue

uni-app x 会优先编译 .uvue 强类型组件；uni-app 继续使用原 .vue，两端共享相同公开 API 和完整能力按钮，但互不混用页面脚本语法。

1.0.15 曾使用组件本地 Demo* 类型与 Array<any> 桥接，但插件市场消费者编译器仍会拒绝把 UTSArray<Any> 赋给插件强类型数组。1.0.16 改为从插件根目录显式导入 BatchSqlItem / BatchCrudItem / MigrationItem，让数组、对象和公开 Options 使用同一插件模块类型身份；公开 API 与运行语义均未改变。

本修复只影响消费者 UTS 编译，不包含原生实现、权限、依赖或资源变更，因此使用此前 HBuilderX 5.15 制作的自定义基座即可重新编译验证，无需仅为 1.0.16 重打基座。

1.0.17 只在 utssdk/web/index.uts 补齐上述四个纯类型的 export type 转发。Web 编译器可以据此在编译期解析组件类型并擦除对应导入，不再向浏览器 ESM 请求不存在的运行时导出；Android/iOS/Harmony/小程序实现、公开 Options 和 uni-app .vue 组件均未改变，也无需为本次 Web 修复重打 App 自定义基座。

插件市场加密链还要求 Web 平台入口本地能够解析全部消费者类型；1.0.17 只补 export type 后，市场加密包仍可能把 SqlTransactionOperation 保留成运行时 named import。1.0.18 进一步把 SqlTransactionOperation / BatchSqlItem / BatchCrudItem / MigrationItem / DatabaseTransferResult 补入同一入口的 import type，让 23 个内置组件/示例类型在 import/export 两侧完整对称。该修改仍只属于 Web 编译期声明，不改变任何平台 API 或运行语义。

1.0.18 发布后的另一账号实测证明，仅补齐 Web .uts 类型声明仍无法穿过收费插件加密链。1.0.19 将 Web 降级实现隔离为自包含 utssdk/web/index.js，并对 interface.uts 全部 69 个公开类型同时提供 JSDoc 类型合并和 ESM 兼容导出；真实 Web 发布不再出现缺失导出或值当类型 warning。

市场 Web 的最终验收必须在上传 1.0.19 后，由测试账号删除旧插件、重新下载并确认版本，再运行 Web；本地源码发布和浏览器结果不能替代市场分发产物证据。

注意事项

• App 端 SQL 语句不要用分号拼接多条命令，多条命令请传数组或使用 batch。
• Web/小程序降级能力只适合演示、轻量缓存和接口连通性测试，不可当作完整 SQLite 文件数据库。
• Web/小程序普通错误对象不会继承 UniError，但会保留 errSubject / errCode / errMsg / details，业务侧仍按 fail(err) 读取错误信息。
• 受限平台或受限 SQL 会进入 fail / complete；插件承诺不伪造成功，也不会把降级结果宣传为完整 SQLite。
• exportDatabase 返回稳定 lizhao-sqlite-pro-json 文本，包含 schema / tables / rows，可直接作为 importDatabase({ data }) 的输入。
• importDatabase 优先使用 data JSON 导入；传 path 时 Android/iOS 会优先尝试读取 JSON 文件，普通数据库文件仍可走文件恢复兜底。
• JSON 导出适合调试、迁移和小规模数据搬迁；大体量数据库仍建议使用 backupDatabase/restoreDatabase 做文件级备份恢复。
• Harmony 使用 rdbStore 原生关系型数据库，backupDatabase/restoreDatabase 走 rdbStore 自带备份恢复；如需跨应用任意路径导入导出，请先用平台文件能力把文件放到应用可访问路径。

作者系列UTS插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。