WCDB for Android的使用
WCDB for Android的使用
WCDB是一个基于SQLCipher,支持iOS, macOS和Android的数据库框架。
基本功能
- 基于SQLCipher的数据库加密
- 使用连接池实现并发读写
- 内建 Repair Kit 可用于修复损坏数据库
- 针对占用空间大小优化的数据库备份/恢复功能
- 日志输出重定向以及性能跟踪接口
- 内建用于全文搜索的 mmicu FTS3/4 分词器
接入与迁移
1. 通过 Maven 接入
在app的 build.gradle 下添加WCDB依赖即可
dependencies {
compile 'com.tencent.wcdb:wcdb-android:1.0.2'
}
2. 通过 AAR 包接入
从发布页面下载 AAR 包,然后导入到工程:
在 Android Studio 选择 File -> New -> New Module... -> Import JAR/AAR Package
在 File -> Project Structure... 或编辑 APP 模块的 build.gradle 将 WCDB 加入依赖项:
dependencies {
compile project(':wcdb')
}
3. 选择接入的 CPU 架构
WCDB包含armeabi, armeabi-v7a, arm64-v8a, x86四种架构的动态库,如果应用希望只接入其中一种或几种架构,可以在 APP 模块的 build.gradle 里加入以下代码:
android {
defaultConfig {
ndk {
// 只接入 armeabi-v7a 和 x86 架构
abiFilters 'armeabi-v7a', 'x86'
}
}
}
迁移到 WCDB
-
WCDB android 使用与 Android SDK SQLite 框架几乎一样的接口,WCDB API文档链接
-
如果之前使用的是 Android SDK 数据库接口,只需要将 import 里的
android.database.*
改为com.tencent.wcdb.*
,android.database.sqlite.*
改为com.tencent.wcdb.database.*
。 -
若之前使用 SQLCipher Android Binding,也需要对应修改 import。
1. 从非加密数据库迁移到加密数据库
如果之前使用的是非加密数据库,接入后想迁移到加密数据库并保留原来的数据,需要使用SQL函数 sqlcipher_export() 进行迁移。详情请见sample-encryptdb 示例
2. 从 SQLCipher Android 迁移
如果之前使用的是SQLCipher数据库,希望迁移到 WCDB 库并沿用原数据库文件,需要在代码里做一点改动。
String passphrase = "passphrase";
// 加密描述对象
SQLiteCipherSpec cipher = new SQLiteCipherSpec()
.setPageSize(1024) // SQLCipher 默认 Page size 为 1024
.setSQLCipherVersion(3); // 1,2,3 分别对应 1.x, 2.x, 3.x 创建的 SQLCipher 数据库
// 如以前使用过其他PRAGMA,可添加其他选项
SQLiteDatabase db = SQLiteDatabase.openOrCreateDatabase(
"path/to/database", // DB 路径
passphrase.getBytes(), // WCDB 密码参数类型为 byte[]
cipher, // 上面创建的加密描述对象
null, // CursorFactory
null // DatabaseErrorHandler
3 // poolSize
// SQLiteDatabaseHook 参数去掉了,在cipher里指定参数可达到同样目的
)
关键改动点为密码转换为byte[]以及传入SQLiteCipherSpec描述加密方式,加密方式必须和之前的 SQLCipher设置一致,否则会报错误。
SQLCipher密码与加密方式错误可能会导致SQLite框架认为其损坏从而触发DatabaseErrorHandler,默认实现会重命名或删除损坏DB,如果不希望此行为,请务必自定义DatabaseErrorHandler。
DatabaseErrorHandler errorHandler = new DatabaseErrorHandler() {
@Override
public void onCorruption(SQLiteDatabase sqLiteDatabase) {
//数据库损坏时回调
}
};
如果之前调用了SQLCipher的SQLiteDatabase.loadLibs(...),可以将其删去,WCDB 在第一次引用时会自动加载动态库。
数据库修复
WCDB可以使用 Repair Kit 或备份恢复来修复损坏的数据库,请参看Android 数据库修复与sample-repairdb 示例。
日志重定向与性能监控
SQLite 和 WCDB 框架在运行中会产生日志,这些日志默认会打印到系统日志(logcat),但这可能不是 所有开发者都希望的行为。比如担心日志里带有敏感信息,直接输出到系统不妥,或者希望将日志写到文件 用于上报和分析,WCDB 提供接口来完成日志重定向。
//不打印日志
Log.setLogger(Log.LOGGER_NONE);
//自定义日志逻辑
Log.setLogger(new Log.LogCallback() {
@Override
public void println(int priority, String tag, String msg) {
//处理日志
}
});
WCDB 还提供了性能监控接口 SQLiteTrace,实现接口并绑定到 SQLiteDatabase 可以在每次执行 SQL 语句或连接池拥堵的时候得到回调。
SQLiteTrace myTrace = new SQLiteTrace() {
@Override
public void onSQLExecuted(SQLiteDatabase db, String sql, int type, long time) {
//每次执行完一条SQL语句时的回调
Log.i(TAG, "trace", "Execute " + sql + " took " + time + "milliseconds");
}
@Override
public void onConnectionPoolBusy(SQLiteDatabase db,
String sql, List<String> requests, String message) {
//当连接池由于执行其他操作而被长时间阻塞时的回调
Log.i(TAG, "trace", "SQL: " + sql + " is waiting for execution, Message: " + message);
}
@Override
public void onDatabaseCorrupted(SQLiteDatabase sqLiteDatabase) {
//数据库损坏时回调,只有使用默认DatabaseErrorHandler才会回调
//若使用自定义DatabaseErrorHandler,可直接在里面执行相应逻辑
Log.i(TAG, "trace", "Database corrupted!");
}
};
SQLiteDatabase db = getDB();
db.setTraceCallback(myTrace);
SQLiteDatabase 也开放了 dump 方法,可以打印出数据库的当前状态,包括连接池内所有连接 被持有的状态以及最近执行的 SQL 语句和耗时,对排查性能和死锁问题也有很大帮助。
参考文档:
https://github.com/Tencent/wcdb/wiki
https://qcloud.com/community/article/209670