接入 WCDB

Android 项目接入 WCDB，可以选择通过 Maven 接入或通过 AAR 包接入。

通过 Maven 接入

对于大部分开发者，推荐使用 Maven 接入 WCDB，在 APP 模块的 build.gradle 下添加 WCDB 依赖即可

  1. dependencies {
  2.     // 修改"1.0.0"为实际引用的版本
  3.     compile 'com.tencent.wcdb:wcdb-android:1.0.0'
  4. }

通过 AAR 包接入

你也可以从发布页面下载 AAR 包，然后导入到工程来接入 WCDB。

  • 在 Android Studio 选择 File -> New -> New Module… -> Import JAR/AAR Package
  • 在 File -> Project Structure… 或编辑 APP 模块的 build.gradle 将 WCDB 加入依赖项：
  1. dependencies {
  2.     compile project(':wcdb')
  3. }

选择接入的 CPU 架构

WCDB 包含 armeabi, armeabi-v7a, arm64-v8a, x86 四种架构的动态库，如果你的应用希望只接入其中一种或几种架构，可以在 APP 模块的 build.gradle 里加入以下代码来选择要接入的架构：

  1. android {
  2.     defaultConfig {
  3.         ndk {
  4.             // 只接入 armeabi-v7a 和 x86 架构
  5.             abiFilters 'armeabi-v7a', 'x86'
  6.         }
  7.     }
  8. }

迁移到 WCDB

WCDB Android 使用与 Android SDK SQLite 框架几乎一样的接口，如果你的 APP 之前使用 Android SDK的数据库接口，只需要将 import 里的 android.database. 改为 com.tencent.wcdb.，以及android.database.sqlite. 改为 com.tencent.wcdb.database. 即可。 若之前使用 SQLCipherAndroid Binding，也需要对应修改 import。

加密与非加密数据库差异只有打开时，打开后后续操作与 Android SDK 一致。具体请参考 WCDB API 文档。

从非加密数据库迁移到加密数据库

如果你之前使用的是非加密数据库，接入后想迁移到加密数据库并保留原来的数据，你需要使用 SQL 函数sqlcipher_export() 进行迁移。详情请见 sample-encryptdb 示例，它示范了如何使用SQLiteOpenHelper 实现数据从非加密往加密迁移和 Schema 升级。

注意： WCDB 对 sqlcipherexport() 函数做了扩展，原本只接受一个参数为导出到哪个 ATTACHED DB，_现在可以接受第二个参数指定从哪个 DB 导出。因此可以反过来实现导入：

  1. ATTACH 'old_database' AS old;
  2. SELECT sqlcipher_export('main', 'old');   -- 从 'old' 导入到 'main'
  3. DETACH old;

从 SQLCipher Android 迁移

如果你之前使用的是 SQLCipher 数据库，希望迁移到 WCDB 库并沿用原数据库文件，需要在代码里做一点改动。

  1. String passphrase = "passphrase";
  2.  
  3. SQLiteCipherSpec cipher = new SQLiteCipherSpec()  // 加密描述对象
  4.     .setPageSize(1024)        // SQLCipher 默认 Page size 为 1024
  5.     .setSQLCipherVersion(3);  // 1,2,3 分别对应 1.x, 2.x, 3.x 创建的 SQLCipher 数据库
  6.     // 如以前使用过其他PRAGMA，可添加其他选项
  7.  
  8. SQLiteDatabase db = SQLiteDatabase.openOrCreateDatabase(
  9.     "path/to/database",     // DB 路径
  10.     passphrase.getBytes(),  // WCDB 密码参数类型为 byte[]
  11.     cipher,                 // 上面创建的加密描述对象
  12.     null,                   // CursorFactory
  13.     null                    // DatabaseErrorHandler
  14.     // SQLiteDatabaseHook 参数去掉了，在cipher里指定参数可达到同样目的
  15. );

关键改动点为 密码转换为byte[] 以及 传入SQLiteCipherSpec描述加密方式，加密方式必须和之前的 SQLCipher 设置一致，否则会报错误，建议先行测试再上线。SQLCipher密码与加密方式错误可能会导致 SQLite 框架认为其损坏从而触发 DatabaseErrorHandler，默认实现会重命名或删除损坏 DB，如果此行为不是你希望的，请务必自定义 DatabaseErrorHandler。

如果之前调用了 SQLCipher 的 SQLiteDatabase.loadLibs(…)，可以将其删去，WCDB在第一次引用时会自动加载动态库。