cordova-sqlite-storage 轻量高效 SQLite 数据库插件

一款专为 Cordova/PhoneGap 应用设计的 SQLite 数据库插件，基于原生 SQLite 引擎封装，提供简洁易用的 API 接口，支持跨平台数据存储、事务管理、批量操作等核心能力，是混合移动应用本地数据持久化的理想解决方案，广泛适用于离线数据缓存、本地业务数据管理、日志存储等场景。

功能特性

• 全平台兼容：完美支持 Android、iOS、HarmonyOS三大主流移动平台，适配各系统最新版本特性

• 原生性能加持：基于系统原生 SQLite 引擎开发，避免 JS 模拟数据库的性能损耗，操作响应迅速

• 完整事务支持：支持显式事务（BEGIN/COMMIT/ROLLBACK）和隐式事务，确保数据操作的原子性和一致性

• 批量操作优化：提供批量执行 SQL 接口，大幅提升大批量数据插入、更新效率，减少 IO 开销

• 版本迁移支持：内置数据库版本管理机制，通过升级回调实现平滑的表结构变更和数据迁移

• 灵活存储位置：支持配置数据库存储路径，适配 Android 分区存储和 iOS和HarmonyOS 沙盒机制，满足不同存储需求

• 丰富错误反馈：提供详细的错误代码和描述信息，便于问题定位和调试

• 内存数据库支持：支持创建纯内存数据库，适用于临时数据处理场景，应用退出后数据自动清除

安装方法

确保已创建 Cordova 项目（若未创建，执行 cordova create sqliteApp com.example.sqliteapp SQLiteApp 创建），进入项目根目录后选择以下方式安装：

1. 基础版安装

# 安装hcordova
npm install -g hcordova


# 安装最新稳定版
hcordova plugin add cordova-sqlite-storage --platform ohos

# 安装指定版本（示例：1.0.0 版本）
hcordova plugin add [email protected] --platform ohos

2. 从 GitCode 安装开发版

适用于需要体验最新功能的开发者，从 GitCode 仓库直接安装：

# 无加密开发版
hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/Cordova-sqlite-storage.git --plarform ohos

卸载方法

进入项目根目录，执行以下命令卸载插件，若安装了加密依赖需一并卸载：

# 全平台卸载数据库插件
hcordova plugin remove cordova-sqlite-storage

# 指定HarmonyOS卸载
hcordova plugin remove cordova-sqlite-storage --platform ohos

核心概念

1. 数据库实例

每个数据库对应一个实例对象，通过 openDatabase 方法创建，所有数据库操作均通过该实例执行。建议应用全局维护一个数据库实例，避免频繁创建和关闭连接。

2. 事务

确保一组数据库操作的原子性，要么全部执行成功，要么全部执行失败并回滚。本插件支持两种事务模式：

• 显式事务：通过 transaction 方法手动开启，需手动提交或回滚

• 隐式事务：单条 SQL 操作默认开启隐式事务，执行完成后自动提交

3. 结果集

查询操作（SELECT）返回的结果容器，包含查询结果的总数和具体数据，通过 rows.length 获取总数，通过 rows.item(index) 获取指定索引的记录。

4. 版本迁移

当数据库版本号提升时，触发 upgrade 回调，用于执行表结构修改、数据迁移等操作，确保旧版本数据平滑过渡到新版本。

API 参考

插件通过全局对象 window.sqlitePlugin 暴露所有 API，所有操作均为异步执行，通过回调函数处理结果。

1. 打开/创建数据库

打开已存在的数据库，若不存在则创建新数据库，返回数据库实例。

/**
 * 打开/创建数据库
 * @param {Object} options - 数据库配置选项
 * @param {Function} successCallback - 成功回调（参数：db 数据库实例）
 * @param {Function} errorCallback - 错误回调（参数：error 错误对象）
 */
sqlitePlugin.openDatabase(options, successCallback, errorCallback);

使用示例：

var global_db = window.sqlitePlugin.openDatabase({name: 'tonge.db', location: 'default'});

2. 事务操作

开启事务，批量执行 SQL 操作，确保原子性。

/**
 * 执行事务
 * @param {Function} transactionCallback - 事务回调（参数：tx 事务对象）
 * @param {Function} errorCallback - 事务失败回调（参数：error 错误对象）
 * @param {Function} successCallback - 事务成功回调（无参数）
 */
db.transaction(transactionCallback, errorCallback, successCallback);

使用示例：

global_db.transaction(function(tx) {
    //批量执行其他sql语句
    tx.executeSql('CREATE TABLE IF NOT EXISTS TONGE_CONFIG_SYS(ID INTEGER PRIMARY KEY AUTOINCREMENT, CONF_KEY VARCHAR(64), CONF_VALUE VARCHAR(512))');
    tx.executeSql('CREATE TABLE IF NOT EXISTS TONGE_SYS_CONST(ID INTEGER PRIMARY KEY AUTOINCREMENT, CONF_KEY VARCHAR(64), CONF_VALUE VARCHAR(4096))');
}, function(error){
    //事务执行失败
    alert("checkDb失败"+error);
}, function(){
   //事务执行成功
});

3. 执行sql语句

执行查询类 SQL 语句，返回结果集。

/**
 * 执行查询 SQL
 * @param {String} sql - 查询 SQL 语句
 * @param {Array} params - SQL 参数数组
 * @param {Function} successCallback - 成功回调（参数：result 结果集对象）
 * @param {Function} errorCallback - 错误回调（参数：error 错误对象）
 */
db.executeSql(sql, params, successCallback, errorCallback);

使用示例：

//执行更新和插入
function updateConst(confKey, confVale, callBack) {
	global_db.transaction(function(tx) {
		tx.executeSql("update TONGE_SYS_CONST set CONF_VALUE=? where CONF_KEY=?", [confVale, confKey], function(tx, result){
			if(result.rowsAffected == 0) {
				tx.executeSql("insert into TONGE_SYS_CONST(CONF_KEY, CONF_VALUE) values(?, ?)", [confKey, confVale], function(tx, result) {
				});
			}
		});
	}, function(error){
		console.log("updateConst失败"+error);
	},function(){
		console.log("updateConst成功:"+confKey);
		callBack();
	});
}

//执行查询语句
function getMemAccount(memAccount, getMemAccountSuccess) {
	var rows = null;
	global_db.readTransaction(function(tx) {
		tx.executeSql("select * from TONGE_MEM_ACCOUNT where MEM_ACCOUNT=?", [memAccount], function(tx, result) {
			rows = result.rows;
		});
	}, function(error){
		console.log("getMemAccount失败"+error);
	},function(){
		if(rows.length != 0) {
            //获取到了数据
			getMemAccountSuccess(rows.item(0));
		} else {
			console.log("没有获取到登录会员的数据");
		}
	});
}

//执行删除和插入
function insertCorpUser(user, callBack) {
	global_db.transaction(function(tx) {
		tx.executeSql("delete from TONGE_CORP_USER where USER_NAME=?", [user.userName], function(tx, result) {
			tx.executeSql("insert into TONGE_CORP_USER(USER_NAME, PASSWD, CORP_ID,CORP_NAME,SHOP_ID,SHOP_NAME,MEM_SERVER_ID,SMS_SERVER_ID,CORP_SERVER_ID,USER_TYPE,USER_AUTHORITY1,USER_AUTHORITY2,FUNCTION_ID,CARD_KIND,SELF_OPTION,FUNCTION_OPTION,FUNCTION_OPTION2,DISCOUNT,SHOP_SELF_OPTION,FIELDS_MUST,STAFF_ID, SYS_VERSION, LAST_DT, PIC_URL, FUNCTION_ROLE,START_DT) values(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",[user.userName, user.passwd, user.corpId, user.corpName, user.shopId, user.shopName, user.memServerId, user.smsServerId, user.corpServerId, user.userType, user.userAuthority1, user.userAuthority2, user.functionId, user.cardKind, user.selfOption, user.functionOption, user.functionOption2, user.discount, user.shopSelfOption, user.fieldsMust, user.staffId, user.sysVersion, user.lastDt, user.picUrl,user.functionRole,user.startDt], function(tx, result){
				if(result.rowsAffected != 1) {
					console.log("insertCorpUser失败,影响行数"+result.rowsAffected);
				}
			});
		});

	}, function(error){
		console.log("insertCorpUser失败"+error);
	},function(){
		console.log("insertCorpUser成功");
		callBack();
	});
}

4. 关闭数据库

关闭数据库连接，释放资源，建议在应用退出前执行。

/**
 * 关闭数据库
 * @param {Function} successCallback - 成功回调（无参数）
 * @param {Function} errorCallback - 错误回调（参数：error 错误对象）
 */
db.close(successCallback, errorCallback);

5. 删除数据库

删除指定名称的数据库文件，需先关闭数据库连接。

/**
 * 删除数据库
 * @param {String} dbName - 数据库名称
 * @param {Function} successCallback - 成功回调（无参数）
 * @param {Function} errorCallback - 错误回调（参数：error 错误对象）
 */
sqlitePlugin.deleteDatabase(dbName, successCallback, errorCallback);

许可证

本插件基于 Apache License 2.0 开源，详见 LICENSE 文件。

参考资源

• Android和iOS：cordova-sqlite-storage 官方指南

• GitCode 仓库：OpenHarmony-Cordova/cordova-sqlite-storage