更新记录

0.4.0（2026-08-18）

• 新增 Web：自包含内存表（ORM Lite），对外 API 与 App 对齐
• Web 支持演示页用到的建表 / 增删改查 / ? 绑定 / 事务，刷新后不保留
• 演示页支持 Android / iOS / Harmony / Web

0.3.0（2026-08-18）

• 新增 Harmony：系统 relationalStore，对外 API 与 iOS 对齐
• Harmony 事务使用 beginTransaction / commit / rollBack
• 演示页支持 Android / iOS / Harmony

0.2.0（2026-08-18）

• 新增 Android：系统 SQLiteDatabase，API 与 iOS 对齐
• 默认路径：filesDir/tan-sqlite/{name}.db
• 演示页支持 Android / iOS

平台兼容性

uni-app x(4.31)

tan-sqlite

uni-app x 本地 SQLite API 插件。当前已实现 App Android（SQLiteDatabase）、App iOS（系统 SQLite3）、App Harmony（relationalStore）和 Web（内存 ORM Lite）。

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

import {
  openDatabase,
  isOpenDatabase,
  closeDatabase,
  executeSql,
  selectSql,
  transaction,
  getDatabasePath
} from '@/uni_modules/tan-sqlite'

import type {
  DatabaseOptions,
  CloseDatabaseOptions,
  SqlOperationOptions,
  SqlQueryOptions,
  SqlTransactionOptions
} from '@/uni_modules/tan-sqlite'

平台

API 一览

executeSql 不传 params 时走 sqlite3_exec，可一次执行多条 SQL。传入 params 时走预编译绑定，只支持单条语句。查询结果请用 ? 占位符绑定参数，避免拼接 SQL。

错误码

代码演示

下面示例均面向 uni-app x（.uvue / .uts）。对象字面量建议 as 成插件导出的 Options 类型。

1. 获取数据库路径

未打开时返回默认沙盒路径；已打开时返回实际打开路径。

const dbName = 'demo'
const path = getDatabasePath(dbName)
console.log('db path', path)

自定义路径打开（可选）：

openDatabase({
  name: dbName,
  path: '/Documents/custom/demo.db',
  success(res) {
    console.log('实际路径', res.path)
  },
  fail(err) {
    console.log('打开失败', err.errCode, err.errMsg)
  }
} as DatabaseOptions)

2. 打开数据库

不存在则创建。同一 name 重复打开会直接成功，不会重复建连接。

openDatabase({
  name: dbName,
  success(res) {
    console.log('打开成功', res.errMsg, res.path)
  },
  fail(err) {
    console.log('打开失败', err.errCode, err.errMsg)
  },
  complete() {
    console.log('openDatabase complete')
  }
} as DatabaseOptions)

3. 判断数据库是否打开

同步返回 boolean，适合在写库前先检查。

const opened = isOpenDatabase({
  name: dbName
} as DatabaseOptions)

if (opened) {
  console.log('数据库已打开')
} else {
  console.log('数据库未打开，先调用 openDatabase')
}

推荐封装：

function ensureOpen(next : () => void) {
  if (isOpenDatabase({ name: dbName } as DatabaseOptions)) {
    next()
    return
  }
  openDatabase({
    name: dbName,
    success() {
      next()
    },
    fail(err) {
      console.log('打开失败', err.errMsg)
    }
  } as DatabaseOptions)
}

4. 执行增删改等 SQL（executeSql）

建表

executeSql({
  name: dbName,
  sql: 'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER)',
  success(res) {
    console.log('建表成功', res.errMsg)
  },
  fail(err) {
    console.log('建表失败', err.errMsg)
  }
} as SqlOperationOptions)

新增

params 按 ? 顺序绑定。成功结果里 insertId 为自增 id，rowsAffected 为影响行数。

executeSql({
  name: dbName,
  sql: 'INSERT INTO users (name, age) VALUES (?, ?)',
  params: ['Alice', 30],
  success(res) {
    console.log('新增成功', res.insertId, res.rowsAffected)
  },
  fail(err) {
    console.log('新增失败', err.errMsg)
  }
} as SqlOperationOptions)

修改

executeSql({
  name: dbName,
  sql: 'UPDATE users SET name = ?, age = ? WHERE id = ?',
  params: ['Bob', 28, 1],
  success(res) {
    console.log('更新行数', res.rowsAffected)
  },
  fail(err) {
    console.log('更新失败', err.errMsg)
  }
} as SqlOperationOptions)

删除

executeSql({
  name: dbName,
  sql: 'DELETE FROM users WHERE id = ?',
  params: [1],
  success(res) {
    console.log('删除行数', res.rowsAffected)
  },
  fail(err) {
    console.log('删除失败', err.errMsg)
  }
} as SqlOperationOptions)

不传 params 时可一次执行多条语句：

executeSql({
  name: dbName,
  sql: 'DELETE FROM users; VACUUM;',
  success() {
    console.log('批量执行完成')
  }
} as SqlOperationOptions)

5. 执行查询 SQL（selectSql）

selectSql({
  name: dbName,
  sql: 'SELECT id, name, age FROM users ORDER BY id DESC',
  success(res) {
    console.log('查询成功', res.errMsg, res.data.length)
    const data = res.data
    for (let i = 0; i < data.length; i++) {
      const row = new UTSJSONObject(data[i])
      const id = row.getNumber('id') ?? 0
      const name = row.getString('name') ?? ''
      const age = row.getNumber('age') ?? 0
      console.log('#' + id + ' ' + name + ' / ' + age)
    }
  },
  fail(err) {
    console.log('查询失败', err.errMsg)
  }
} as SqlQueryOptions)

带条件查询：

selectSql({
  name: dbName,
  sql: 'SELECT id, name, age FROM users WHERE age >= ? ORDER BY age DESC',
  params: [18],
  success(res) {
    console.log('成年用户', res.data.length)
  },
  fail(err) {
    console.log('查询失败', err.errMsg)
  }
} as SqlQueryOptions)

iOS 上 res.data 的数组元素请先 new UTSJSONObject(item) 再 getNumber / getString。不要对原始元素直接 forEach + 取值，否则页面可能拿不到字段。

6. 执行事务

operation 只接受：begin、commit、rollback。

function runInTransaction() {
  transaction({
    name: dbName,
    operation: 'begin',
    success() {
      executeSql({
        name: dbName,
        sql: 'INSERT INTO users (name, age) VALUES (?, ?)',
        params: ['Carol', 22],
        success() {
          executeSql({
            name: dbName,
            sql: 'INSERT INTO users (name, age) VALUES (?, ?)',
            params: ['Dave', 26],
            success() {
              transaction({
                name: dbName,
                operation: 'commit',
                success() {
                  console.log('事务提交成功')
                },
                fail(err) {
                  console.log('commit 失败', err.errMsg)
                }
              } as SqlTransactionOptions)
            },
            fail(err) {
              transaction({
                name: dbName,
                operation: 'rollback',
                complete() {
                  console.log('第二条插入失败，已回滚', err.errMsg)
                }
              } as SqlTransactionOptions)
            }
          } as SqlOperationOptions)
        },
        fail(err) {
          transaction({
            name: dbName,
            operation: 'rollback',
            complete() {
              console.log('第一条插入失败，已回滚', err.errMsg)
            }
          } as SqlTransactionOptions)
        }
      } as SqlOperationOptions)
    },
    fail(err) {
      console.log('begin 失败', err.errMsg)
    }
  } as SqlTransactionOptions)
}

7. 关闭数据库

用完后及时关闭，避免占用连接。关闭后再读写需要重新 openDatabase。

closeDatabase({
  name: dbName,
  success(res) {
    console.log('已关闭', res.errMsg)
    console.log('是否仍打开', isOpenDatabase({ name: dbName } as DatabaseOptions))
  },
  fail(err) {
    console.log('关闭失败', err.errCode, err.errMsg)
  }
} as CloseDatabaseOptions)

完整流程示例

打开 → 建表 → 写入 → 查询 → 关闭：

const dbName = 'demo'

openDatabase({
  name: dbName,
  success(openRes) {
    console.log('path', openRes.path)

    executeSql({
      name: dbName,
      sql: 'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER)',
      success() {
        executeSql({
          name: dbName,
          sql: 'INSERT INTO users (name, age) VALUES (?, ?)',
          params: ['Alice', 30],
          success(insertRes) {
            console.log('insertId', insertRes.insertId)

            selectSql({
              name: dbName,
              sql: 'SELECT * FROM users',
              success(queryRes) {
                console.log('rows', queryRes.data.length)
                closeDatabase({
                  name: dbName,
                  success() {
                    console.log('done')
                  }
                } as CloseDatabaseOptions)
              }
            } as SqlQueryOptions)
          }
        } as SqlOperationOptions)
      }
    } as SqlOperationOptions)
  },
  fail(err) {
    console.log('打开失败', err.errMsg)
  }
} as DatabaseOptions)

项目内可运行演示页：pages/test/test（可视化列表 + 增删改查 + 一键模拟）。

平台说明

• Android / iOS / Harmony 使用同一套 API，页面无需分端调用
• Android 改了原生配置后需要自定义基座；普通 UTS 代码可热刷新
• iOS 链接系统库 libsqlite3.tbd；Windows 开发 iOS 必须自定义基座
• Harmony 使用 @ohos.data.relationalStore，需要鸿蒙原生联编
• Harmony 的 path 只取文件名，物理路径由系统管理；getDatabasePath 返回存储名（如 demo.db）
• Harmony 事务走 beginTransaction / commit / rollBack，不要对 executeSql 传 BEGIN/COMMIT SQL
• Harmony executeSql 单次不支持分号多语句，插件会按 ; 拆开逐条执行
• Web 使用自包含内存实现（ORM Lite），页面仍走同一套 executeSql / selectSql
• Web 不是完整 SQLite：支持 CREATE TABLE / DROP TABLE / INSERT / UPDATE / DELETE / SELECT（单表、WHERE 等值与比较、AND、ORDER BY、LIMIT、? 绑定）以及 transaction
• Web 不支持 JOIN、子查询、索引、触发器等；VACUUM / PRAGMA 视为空操作
• Web 数据只在当前页面进程内存中，刷新、关闭库或关闭标签后不保留
• 数据在应用沙盒，卸载 App 后清除
• 写操作建议使用 params 绑定，不要拼接用户输入
• 查询结果数组元素请先 new UTSJSONObject(item) 再取值