更新记录

1.1.4（2026-09-06）

• 修复 uni-app x Android 示例的 SQLite 回调前向引用与可空结果类型导致的 UTS 编译错误。

1.1.3（2026-08-19）

• 修复 Android 结构化 CRUD、Schema Builder、ORM Lite 的嵌套配置经桥接后字段或数组丢失的问题；现在兼容 UTSJSONObject / UTSObject / java.util.Map / java.util.List 四类真机对象，包括 uni-app x 自定义 type 生成的条件项，where.column、columns[].name、orderBy.column 及对象数组均可直接读取，公开 API 与调用方式不变。
• 修复 iOS selectRows / aggregateRows 返回数组时，HBuilderX ByJs 的 UTSCallback 把 Array<Any> 解释为回调参数列表，导致页面只收到第一行对象的问题；现在将完整行数组装箱为单个回调参数，公开 API 类型和调用方式不变。
• “一键全量自检”在声明 full_check_models 前重建专用 ORM 测试表，避免历史自检数据库缺少 UNIQUE 约束时产生两项 Upsert 假失败；真实业务表缺少唯一约束时仍会返回原 SQLite 错误，不会伪造成功。
• 失败条目新增脱敏 diagnostic 字段，只记录回调次数、结果类型/数组长度或截断后的错误码与错误信息，不复制查询行正文。
• uni-app、uni-app x 的组件与完整示例保持相同自检夹具；Harmony、Web、小程序、公开 interface.uts、原生依赖和客户 README 均未改变。
• 本版本修改 Android 公共 UTS 解析路径和 iOS UTS 回调适配层，升级后必须重新制作并安装与 HBuilderX 5.24 匹配的目标平台自定义基座，再以全量自检零失败且无新增崩溃作为真机验收结果。

1.1.2（2026-08-14）

• 修复 iOS 真机执行“一键全量自检”时，selectRows / aggregateRows 的数组回调因 HBuilderX 5.24 生成闭包类型不一致而触发 swift_dynamicCastFailure 闪退；公开 API 和页面调用方式保持不变。
• README 改为先展示功能特色、适用场景、快速开始和核心配置，移除目录、权限、自定义基座及 Mac/Windows 内部排障章节。
• uni-app 与 uni-app x 的完整组件和示例新增“一键全量自检”和可复制安全报告，直接覆盖全部 32 个公开 API，不新增测试专用原生接口。
• 自检逐项记录通过、失败、跳过和耗时，严格校验 success / fail / complete 次数、8 秒超时、事务提交/回滚结果、危险全表操作保护、Schema/迁移幂等、索引、ORM Lite、诊断与关闭状态。
• uni-app x 使用强类型串行状态机隔离结算后的迟到回调；数据库打开失败时跳过依赖链并继续诊断，避免级联假失败。
• 完整示例仅在显式 autoFullCheck=1 时自动运行，输出稳定 START/ITEM/DONE/FAILED marker；普通打开页面不会自动写入测试数据库。
• iOS 验收脚本加入全量 marker、失败项、计数、耗时和 crash report 时间窗；只有匹配自定义基座、全量 DONE、零失败且无新增崩溃报告时才可声明真机通过。
• 本版本未改变原生依赖、权限及平台配置；iOS 回调桥与公共诊断版本会进入 App 原生生成物，正式验收应重新制作与当前 HBuilderX 匹配的目标平台自定义基座。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lizhao-sqlite-pro

插件简介

lizhao-sqlite-pro 是面向 uni-app / uni-app x 的纯 UTS SQLite 数据库插件。除了兼容 plus.sqlite 风格 API，还提供结构化 CRUD、声明式 Schema Builder、事务安全 Upsert、固定函数聚合、一致性分页、迁移、备份恢复和诊断能力。

功能特色

• 原生 SQLite 多端实现：Android、iOS、Harmony 分别使用平台数据库能力，业务代码保持统一。
• SQL 与结构化操作并存：既能执行原生 SQL，也能通过对象配置完成增删改查，减少字符串拼接。
• 轻量 ORM 能力：内置建表核对、Upsert、计数、聚合和分页，不绑定实体类或额外运行时。
• 安全优先：数据值统一支持参数绑定，结构化接口校验表名、字段名和危险全表操作。
• 工程化能力完整：支持事务、迁移、批处理、备份恢复、导入导出、健康检查和诊断日志。
• 可直接验收：内置演示组件和“一键全量自检”，便于接入后快速确认各项能力。

适用场景

快速开始

先打开数据库，再执行参数化 SQL；页面退出或业务结束时关闭数据库。

import {
  openDatabase,
  executePrepared,
  selectSql,
  closeDatabase
} from '@/uni_modules/lizhao-sqlite-pro'

const databaseName = 'business'

openDatabase({
  name: databaseName,
  success() {
    executePrepared({
      name: databaseName,
      sql: 'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)',
      params: [],
      success() {
        selectSql({
          name: databaseName,
          sql: 'SELECT * FROM users',
          success(rows) {
            console.log('用户数据', rows)
          },
          fail(err) {
            console.error('查询失败', err)
          },
      complete() {
            // 查询结束后再关闭，避免提前结束数据库会话。
            closeDatabase({ name: databaseName })
          }
        })
      },
      fail(err) {
        console.error('建表失败', err)
        closeDatabase({ name: databaseName })
      }
    })
  },
  fail(err) {
    console.error('数据库打开失败', err)
  }
})

核心配置

接入方式怎么选

支持平台

安装与引入

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

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

API 列表

ORM Lite 快速接入

Schema Builder 适合首次创建并核对结构；runMigrations 适合版本升级时新增列、迁移数据或执行其他显式变更。ensureSchema 只会创建缺失的表和索引，并核对已有字段、主键、非空和索引声明；发现冲突会失败，不会自动 ALTER TABLE、删表或重建客户数据。

import {
  openDatabase,
  ensureSchema,
  upsertRow,
  countRows,
  aggregateRows,
  paginateRows
} from '@/uni_modules/lizhao-sqlite-pro'

openDatabase({
  name: 'business',
  success() {
    ensureSchema({
      name: 'business',
      tables: [{
        name: 'users',
        columns: [
          { name: 'id', type: 'INTEGER', primaryKey: true, autoIncrement: true },
          { name: 'email', type: 'TEXT', notNull: true, unique: true },
          { name: 'score', type: 'REAL', defaultValue: 0 },
          { name: 'created_at', type: 'TEXT', defaultExpression: 'CURRENT_TIMESTAMP' }
        ],
        indexes: [
          { name: 'idx_users_email', columns: ['email'], unique: true },
          { name: 'idx_users_score', columns: ['score'] }
        ]
      }],
      success(res) {
        console.log('Schema 已就绪', res)
      },
      fail(err) {
        console.error('Schema 声明或已有结构冲突', err)
      }
    })
  }
})

Upsert 不使用删除重插语义。新 SQLite 使用原生 ON CONFLICT，旧运行时在当前事务内执行更新/插入回退：

upsertRow({
  name: 'business',
  table: 'users',
  values: [
    { column: 'email', value: 'customer@example.com' },
    { column: 'score', value: 88 }
  ],
  conflictColumns: ['email'],
  updateColumns: ['score'],
  success(res) {
    console.log(res.inserted, res.updated, res.affectedRows)
  }
})

计数、聚合和分页示例：

countRows({
  name: 'business',
  table: 'users',
  where: [{ column: 'score', op: '>=', value: 60 }],
  success(res) { console.log('总数', res.count) }
})

aggregateRows({
  name: 'business',
  table: 'users',
  aggregates: [
    { function: 'COUNT', column: '*', alias: 'user_count' },
    { function: 'AVG', column: 'score', alias: 'score_avg' }
  ],
  success(rows) { console.log('聚合', rows) }
})

paginateRows({
  name: 'business',
  table: 'users',
  orderBy: [{ column: 'id', direction: 'DESC' }],
  page: 1,
  pageSize: 20,
  success(res) { console.log(res.total, res.pageCount, res.rows) }
})

ensureSchema(options)

创建缺失表和索引，并核对已有结构。已有额外字段允许保留；声明字段缺失、类型/主键/非空约束或同名索引不一致时返回冲突错误。

返回 createdTables / existingTables / createdIndexes / existingIndexes / checkedColumns。

createIndex(options)

显式创建索引；同名索引存在时会核对字段顺序和唯一性。

返回 created / dropped / table / index。

dropIndex(options)

显式删除索引，不接受任意 SQL 片段。

返回 dropped / table / index。

upsertRow(options)

按 conflictColumns 判断插入或原位更新；所有值使用参数绑定。

返回 inserted / updated / affectedRows / insertId。

countRows(options)

按与结构化 CRUD 相同的安全条件统计行数。

返回 { name, count }。

aggregateRows(options)

只允许 COUNT / SUM / AVG / MIN / MAX，聚合别名和字段均执行标识符校验。

返回聚合结果对象数组。

paginateRows(options)

App 原生端在同一读取事务中查询总数和当前页；Web 在同一内存快照中计算。

返回 total / pageCount / hasPrevious / hasNext / rows。

快速上手示例

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

// 快速上手：打开数据库 -> 建表 -> 参数化写入 -> 查询结果。
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 动态下标的严格限制。

Web 内存降级端支持结构化新增、查询、更新、删除和失败回滚批处理。对象条件数组支持全部公开比较操作符和 AND / OR；字符串 where + whereParams 支持标量比较、LIKE / IS NULL / IS NOT NULL 的安全子集。查询还支持字段投影、排序、limit / offset。Web 暂不执行 groupBy / having 聚合语义，传入时会进入 fail + complete；App 原生 SQLite 端继续支持完整结构化 SQL 构造合同。Web 的 structuredCrud=true 只表示这些内存结构化操作可用，nativeSqlite 仍为 false。

// 结构化 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，不会伪造成功。

一键全量自检

内置 uni-app / uni-app x 完整组件和示例均提供“一键全量自检”。它会从插件根入口串行调用真实公开 API，并生成包含“通过 / 失败 / 跳过 / 耗时”的安全报告；报告不会复制数据库导出的数据正文。

• 手动验收：进入完整示例，点击“一键全量自检”，结束后可点击“复制自检报告”。
• 自动验收：打开完整示例页时显式追加 autoFullCheck=1，运行日志会输出 AUTO_SQLITE_FULL_CHECK_START / ITEM / DONE / FAILED。
• 普通打开页面不会自动执行，也不会自动创建或写入自检数据库。
• skipped 表示能力矩阵明确不支持，例如部分平台没有文件备份恢复；它不等于通过，也不等于失败。
• App 真机报告必须来自包含插件原生实现、诊断版本一致且与当前 HBuilderX 匹配的自定义基座；升级插件版本后应重新原生联编，资源同步或 appResource 编译不能单独证明真机数据库链路通过。

// 完整回归示例：覆盖兼容 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 和完整能力按钮，但互不混用页面脚本语法。

uni-app x 强类型组件与 uni-app 组件共享同一组公开 API，可按当前项目类型直接使用对应组件文件。

注意事项

• 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 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。