WCDB for Android
前言
最近自己项目记录数据库有用户反馈数据会丢失，我们一直都没找到初步原因，因此也是怀疑部分用户数据库损坏导致，查看了下sqlite官网的说法有导致损坏db文件的如下几点原因：
- 文件错写
- 文件锁 bug
- 文件 sync 失败
- 设备损坏
- 内存覆盖
- 操作系统 bug
- SQLite bug
具体的大家可以看下这篇文章：微信客户端SQLite数据库损坏修复实践
因此我们才会调研考虑要不要使用微信自己出的这个WCDB数据库，下面先具体的讲解下WCDB
具体的功能
- 基于SQLCipher的数据库加密
- 使用连接池实现并发读写
- Reparir Kit工具类用于修复损坏数据库
- 针对占用空间大小优化的数据库备份和恢复功能
- 日志输出重定向和性能跟踪接口
- 内建用于全文搜索的mmicu FTS3/4的分词器
接入
在build.gradle下面配置
dependencies {
...
compile 'com.tencent.wcdb:wcdb-android:1.0.2'
}
选择接入的CPU架构，WCDB包含 armeabi, armeabi-v7a, arm64-v8a, x86四种架构的动态库，具体的就想用哪个用哪个了具体配置在build.gradle：
android {
defaultConfig {
...
ndk {
// 接入 armeabi ,armeabi-v7a ,x86
abiFilters 'armeabi', 'armeabi-v7a','x86'
}
}
}
加密：WCDB在android上语法和官方再带的sqlite是一样的，记得导包的时候引用tencent的，下面开始看一个具体的列子：
import android.content.Context;
import com.tencent.wcdb.DatabaseErrorHandler;
import com.tencent.wcdb.database.SQLiteCipherSpec;
import com.tencent.wcdb.database.SQLiteDatabase;
import com.tencent.wcdb.database.SQLiteOpenHelper;
public class DBHelper extends SQLiteOpenHelper {
static final String DATABASE_NAME = "test-repair.db";
static final int DATABASE_VERSION = 1;
static final byte[] PASSPHRASE = "testkey".getBytes();
// The test database is taken from SQLCipher test-suit.
//
// To be compatible with databases created by the official SQLCipher
// library, a SQLiteCipherSpec must be specified with page size of
// 1024 bytes.
static final SQLiteCipherSpec CIPHER_SPEC = new SQLiteCipherSpec()
.setPageSize(1024);
// We don't want corrupted databases get deleted or renamed on this sample,
// so use an empty DatabaseErrorHandler.
static final DatabaseErrorHandler ERROR_HANDLER = new DatabaseErrorHandler() {
@Override
public void onCorruption(SQLiteDatabase dbObj) {
// Do nothing
}
};
public DBHelper(Context context) {
super(context, DATABASE_NAME, null, CIPHER_SPEC, null,
DATABASE_VERSION, ERROR_HANDLER);
// super(context,DATABASE_NAME,null,DATABASE_VERSION);
}
@Override
public void onCreate(SQLiteDatabase db) {
db.execSQL("CREATE TABLE t1(a,b);");
// OPTIONAL: backup master info for corruption recovery.
// However, we want to test recovery feature, so omit backup here.
//RepairKit.MasterInfo.save(db, db.getPath() + "-mbak", PASSPHRASE);
}
@Override
public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
// Do nothing.
}
}
- 也是继承SQLiteOpenHelper去做事情。WCDB 使用了 SQLCipher 的 C 层库，但没有直接使用 SQLCipher Android 的封装层。SQLCipher Android 封装层中很多设置需要手写 PRAGMA 语句实现，比如设置 KDF 迭代次数（兼容老版本 SQLCipher DB）、设置 Page Size 等操作。
- 构造方法中直接传入一个byte[]作为密码加密操作，很简单，WCDB 将 String 类型的密码改为 byte[] 类型，可以支持非打印字符作为密码（比如 hash(user id) 方式），原来字符类型密码只要转换为 UTF-8 的 byte 数组即可，和 SQLCipher Android 兼容。
数据迁移
SQLCipher 提供了 sqlcipher_export SQL 函数用于导出数据到挂载的另一个 DB，可以用于数据迁移。 但这个函数用于 Android 的 SQLiteOpenHelper 并不方便。
SQLiteOpenHelper 主要帮助开发者做 Schema 版本管理，通过它打开 SQLite 数据库，会读取 user_version 字段来判断是否需要升级，并调用子类实现的 onCreate、onUpgrade 等接口来完成创建或升级操作。 sqlcipher_export 由于是导出而非导入，就跟 onCreate 等接口不搭了，因为要关闭原来的 DB， 打开老的 DB，执行 export 到新 DB，再重打开。
为了方便使用，WCDB 就做了扩展，将 sqlcipher_export 扩展为可以接受第二个参数表示从哪里导出， 从而实现了导入,列子看下：
@Override
public void onCreate(SQLiteDatabase db) {
// Check whether old plain-text database exists, if so, export it
// to the new, encrypted one.
File oldDbFile = mContext.getDatabasePath(OLD_DATABASE_NAME);
if (oldDbFile.exists()) {
Log.i(TAG, "Migrating plain-text database to encrypted one.");
// SQLiteOpenHelper begins a transaction before calling onCreate().
// We have to end the transaction before we can attach a new database.
db.endTransaction();
// Attach old database to the newly created, encrypted database.
String sql = String.format("ATTACH DATABASE %s AS old KEY '';",
DatabaseUtils.sqlEscapeString(oldDbFile.getPath()));
db.execSQL(sql);
// Export old database.
db.beginTransaction();
//从old旧的数据库倒出数据库到main
DatabaseUtils.stringForQuery(db, "SELECT sqlcipher_export('main', 'old');", null);
db.setTransactionSuccessful();
db.endTransaction();
// Get old database version for later upgrading.
int oldVersion = (int) DatabaseUtils.longForQuery(db, "PRAGMA old.user_version;", null);
// Detach old database and enter a new transaction.
db.execSQL("DETACH DATABASE old;");
// Old database can be deleted now.
oldDbFile.delete();
// Before further actions, restore the transaction.
db.beginTransaction();
// Check if we need to upgrade the schema.
if (oldVersion > DATABASE_VERSION) {
onDowngrade(db, oldVersion, DATABASE_VERSION);
} else if (oldVersion < DATABASE_VERSION) {
onUpgrade(db, oldVersion, DATABASE_VERSION);
}
} else {
Log.i(TAG, "Creating new encrypted database.");
// Do the real initialization if the old database is absent.
db.execSQL("CREATE TABLE message (content TEXT, "
+ "sender TEXT);");
}
// OPTIONAL: backup master info for corruption recovery.
RepairKit.MasterInfo.save(db, db.getPath() + "-mbak", /*mPassphrase.getBytes()*/null);
}
如此就可以不关闭原来的数据库实现数据导入，可以兼容 SQLiteOpenHelper 的接口了。
数据库修复
Android 接口支持三种修复方法，如下：
| 修复方法 | 简介 | 相关接口 |
|---|---|---|
| Repair Kit | 解析 B-tree 修复 | RepairKit类 |
| 备份恢复 | 压缩备份完整数据，使用备份数据恢复 | BackupKit 和 RecoverKit |
| Dump | .dump 命令，已废弃 | DBDumpUtil |
一，Repair Kit
使用 Repair Kit 可以直接从损坏的数据库里尽量读出未损坏的数据，不需要事先准备， 但是先备份 Master 信息可以大大增加恢复成功率。 如果有意使用 Repair Kit 恢复数据库， 建议备份 Master 信息。Master 信息保存了数据库的 Schema，建议每次执行完数据库创建或升级时执行备份，可以保证备份 是最新的。不修改 Schema 的话 Master 信息不会改变。如果你使用 SQLiteOpenHelper，最佳 实践是在 SQLiteOpenHelper.onCreate(...) 和 SQLiteOpenHelper.onUpgrade(...) 的 最后进行备份。备份 Master 信息只需要调用 RepairKit.MasterInfo.save(...) 即可。备份 Master 信息 典型消耗为几kB ~ 几十kB，几毫秒 ~ 几十毫秒，但如果你有非常非常多的表和索引（万数量级）， 这个过程可能会有点慢，建议放在子线程完成.如下：
public class DBHelper extends SQLiteOpenHelper {
public DBHelper(Context context) {
super(context, DATABASE_NAME, PASSPHRASE, CIPHER_SPEC, null,
DATABASE_VERSION, ERROR_HANDLER);
}
@Override
public void onCreate(SQLiteDatabase db) {
// 执行 CREATE TABLE 创建 Schema
db.execSQL("CREATE TABLE t1(a,b);");
db.execSQL("CREATE TABLE t2(c,d);");
// ......
// 备份 Master 信息
RepairKit.MasterInfo.save(db, db.getPath() + "-mbak", BACKUP_PASSPHRASE);
}
@Override
public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
// 执行升级
db.execSQL("ALTER TABLE t1 ADD COLUMN x TEXT;");
// 备份 Master 信息
RepairKit.MasterInfo.save(db, db.getPath() + "-mbak", BACKUP_PASSPHRASE);
}
}
二，恢复损坏数据库
恢复损坏数据库，首先加载之前备份的 Master 信息（如果有）。
RepairKit.MasterInfo master = RepairKit.MasterInfo.load('/path/to/database.db-mbak',
BACKUP_PASSPHRASE, null);
if (master == null) {
// 加载不成功，可能是不存在或者损坏
}
使用 RepairKit 打开损坏的数据库，使用 SQLiteDatabase 打开新的数据库，调用 output(...) 即可将损坏数据库的内容转移到新数据库。
RepairKit repair = new RepairKit(
"/path/to/corrupted.db" // 损坏的数据库文件
PASSPHRASE, // 数据库密钥（不是备份文件密钥）
CIPHER_SPEC, // 加密描述，与打开DB时一样
master // 之前加载的 Master 信息
);
SQLiteDatabase newDb = SQLiteDatabase.openOrCreateDatabase(...);
// 打开新DB用于承载恢复数据，是否加密没所谓
boolean result = repair.output(newDb, 0);
// 输出恢复数据到新DB
if (!result) {
// 恢复失败
}
repair.release();
// 最后要 release 释放资源
恢复的过程需时较长，请务必在子线程完成，如数据库较大请考虑持有 Wake Lock。
三，选择性恢复
Repair Kit 可以只恢复一部分表，只需要在 MasterInfo.load(...) 或者 MasterInfo.make(...) 里指定白名单即可。
// 白名单，只有白名单里列到的表才会恢复，表对应的索引也会相应恢复
String[] tables = new String[] {
"t1", "t2" // 只恢复 t1 和 t2 两个表
};
RepairKit.MasterInfo master = RepairKit.MasterInfo.load('/path/to/database.db-mbak',
BACKUP_PASSPHRASE, tables);
日志重定向与性能监控
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 trace=new SQLiteTrace() {
@Override
public void onSQLExecuted(SQLiteDatabase db, String sql, int type, long time) {
//每次之行完一条sql的语句执行的回调
}
@Override
public void onConnectionObtained(SQLiteDatabase db, String sql, long waitTime, boolean isPrimary) {
//从连接池获得了链接成功
}
@Override
public void onConnectionPoolBusy(SQLiteDatabase db, String sql, List<String> requests, String message) {
//等待连接池超过3秒的回调，因为存在别的操作占用着连接池
}
@Override
public void onDatabaseCorrupted(SQLiteDatabase db) {
//数据库损坏时回调
}
};
mDB.setTraceCallback(trace);
SQLiteDatabase 也开放了 dump 方法，可以打印出数据库的当前状态，包括连接池内所有连接 被持有的状态以及最近执行的 SQL 语句和耗时，对排查性能和死锁问题也有很大帮助。
优化 Cursor 实现
Android 框架查询数据库使用的是 Cursor 接口，调用 SQLiteDatabase.query(...) 会返回一个Cursor 对象，之后就可以使用 Cursor 遍历结果集了。Android SDK SQLite Cursor 的实现是分配一个固定 2MB 大小的缓冲区，称作 Cursor Window，用于存放查询结果集。
查询时，先分配Cursor Window，然后执行 SQL 获取结果集填充之，直到 Cursor Window 放满或者遍历完结果集，之后将 Cursor 返回给调用者。
假如 Cursor 遍历到缓冲区以外的行，Cursor 会丢弃之前缓冲区的所有内容，重新查询，跳过前面的行，重新选定一个开始位置填充 Cursor Window 直到缓冲区再次填满或遍历完结果集。
这样的实现能保证大部分情况正常工作，在很多情况下却不是最优实现。微信对 DB 操作最多的场景是获取 Cursor 直接遍历获取数据后关闭，获取到的数据，一般是生成对应的实体对象（通过 ORM 或者自行从 Cursor 转换）后放到 List 或 Map 等容器里返回，或用于显示，或用于其他逻辑。
在这种场景下，先将数据保存到 Cursor Window 后再取出，中间要经历两次内存拷贝和转换（SQLite → CursorWindow → Java），这是完全没有必要的。另外，由于 Cursor Window 是定长的，对于较小的结果集，需要无故分配 2MB 内存，对于大结果集，如果 2MB 不足以放下，遍历到途中还会引发 Cursor 重查询，这个消耗就相当大了。
Cursor Window，其实也是在 JNI 层通过 SQLite 库的 Statement 填充的，Statement 这里可以理解为一个轻量但只能往前遍历，没有缓存的 Cursor。这个不就跟我们的场景一致吗？何不直接使用底层的 Statement 呢？我们对 Statement 做了简单的封装，暴露了 Cursor 接口， SQLiteDirectCursor 就诞生了，它直接操作底层 SQLite 获取数据，只能执行往前迭代的操作，但这完全满足需要。
com.tencent.wcdb.Cursor cursor=mDB.rawQueryWithFactory(SQLiteDirectCursor.FACTORY,sql,null);
try {
while (cursor.moveToNext()) {
//处理数据
}
}catch (Exception e){
e.printStackTrace();
}
在大部分不需要将 Cursor 传递出去的场景，能很好的解决 Cursor 的额外消耗，特别是结果集大于 2MB 的场合。
