更新记录

0.1.0（2026-05-09）

u-sqlite

uniapp版本sqlite uts 插件上线 适配 android ios harmonyos web

平台兼容性

uni-app(4.87)

uni-app x(4.87)

u-sqlite

u-sqlite 是一款面向 uni-app / uni-app-x 的轻量级 SQLite UTS 插件，为 App Android、App iOS、App HarmonyOS 以及 Web/H5 提供统一的 SQL 操作 API。

本插件定位精简：它是 SQLite 驱动，而非 ORM、同步框架或后端集成层。

支持平台

• App Android：android.database.sqlite.SQLiteDatabase
• App iOS：系统 SQLite3 C API
• App HarmonyOS：@ohos.data.relationalStore
• Web/H5：sql.js 1.12.0 WebAssembly + IndexedDB 持久化

IOS端未测试 小程序及其他客户端不受支持，应展示降级提示。

基础 API（推荐）

日常开发推荐使用以下六个方法：

• openDatabase(options) — 打开数据库
• isOpenDatabase(options) — 判断数据库是否已打开
• closeDatabase(options) — 关闭数据库
• executeSql(options) — 执行写操作（INSERT / UPDATE / DELETE / DDL）
• selectSql(options) — 执行查询（SELECT）
• transaction(options) — 事务执行多条语句

30 秒快速开始

import {
    openDatabase,
    executeSql,
    selectSql,
    closeDatabase
} from '@/uni_modules/u-sqlite';

const db = await openDatabase({
    name: 'demo.db'
});

await executeSql({
    dbId: db.dbId,
    sql: `CREATE TABLE IF NOT EXISTS todo (
        id INTEGER PRIMARY KEY,
        title TEXT NOT NULL,
        done INTEGER NOT NULL DEFAULT 0
    )`
});

await executeSql({
    dbId: db.dbId,
    sql: 'INSERT INTO todo (title) VALUES (?)',
    params: ['Learn SQLite']
});

const result = await selectSql({
    dbId: db.dbId,
    sql: 'SELECT * FROM todo ORDER BY id DESC'
});

console.log(result.rows);

await closeDatabase({ dbId: db.dbId });

事务使用

当多条写入语句需要同时成功或同时回滚时，请使用 transaction()。

await transaction({
    dbId,
    statements: [
        { sql: 'INSERT INTO todo (title) VALUES (?)', params: ['A'] },
        { sql: 'INSERT INTO todo (title) VALUES (?)', params: ['B'] }
    ]
});

transaction() 会在托管事务中拒绝事务控制类 SQL，包括 BEGIN、COMMIT、ROLLBACK、SAVEPOINT、RELEASE 以及精确的 PRAGMA foreign_keys = OFF。

批量写入

为了简化调用，executeSql() 也支持传入语句数组。

await executeSql({
    dbId,
    transaction: true,
    sql: [
        { sql: 'INSERT INTO todo (title) VALUES (?)', params: ['A'] },
        { sql: 'INSERT INTO todo (title) VALUES (?)', params: ['B'] }
    ]
});

返回结果结构

写操作结果：

{
    rowsAffected: 1,
    lastInsertRowid: 1,
    elapsedMs: 2
}

查询结果：

{
    columns: ['id', 'title'],
    rows: [{ id: 1, title: 'Learn SQLite' }],
    elapsedMs: 2
}

兼容方法

以下方法对存量代码保持兼容，但新项目建议优先使用上方的基础 API。

• execute(options)：executeSql() 的单语句兼容别名
• query(options)：selectSql() 的兼容别名
• batch(options)：数组形式 executeSql() 的底层兼容路径
• migrate(options)：基于 PRAGMA user_version 的迁移助手
• getVersion(options) / setVersion(options)：直接读写 PRAGMA user_version
• quickCheck(options)：数据库完整性诊断
• getCapabilities()：平台能力报告

平台说明

• Web/H5 的 path 是逻辑路径，并非真实浏览器文件系统路径。
• Web/H5 在成功写入后将 SQLite 字节导出并持久化到 IndexedDB。
• Web/H5 的只读操作不会触发导出或持久化。
• Web/H5 的大数据库导出可能较慢，因为 sql.js 会生成数据库快照。
• WAL、FTS5、JSON1、加密、备份以及 PRAGMA 行为因平台而异。请在依赖可选功能前先调用 getCapabilities() 确认。
• SQLite 本身不提供加密存储。如需存储敏感数据，请先评估各平台的安全要求。

演示范围

内置演示有意保持简单，仅展示：

• 打开与关闭数据库
• 创建表
• 插入、查询、更新与删除记录
• 提交与回滚事务

业务同步、后端请求、冲突处理、登录态、重试队列等应放在应用代码中，而非插件演示里。