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

转载于:https://www.cnblogs.com/zhaoxia0815/articles/7278790.html