微信 WCDB for Android的接入

article/2025/10/9 9:55:12

接入 WCDB

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

通过 Maven 接入

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

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

- 通过 AAR 包接入

你也可以从发布页面下载 AAR 包，然后导入到工程来接入 WCDB。在 Android Studio 选择 File -> New -> New Module... -> Import JAR/AAR Package
在 File -> Project Structure... 或编辑 APP 模块的 build.gradle 将 WCDB 加入依赖项：
dependencies {compile project(':wcdb')
}

- 选择接入的 CPU 架构

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

迁移到 WCDB

Markdown

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

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

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

如果你之前使用的是非加密数据库，接入后想迁移到加密数据库并保留原来的数据，你需要使用 SQL 函数 sqlcipher_export() 进行迁移。

详情请见 sample-encryptdb 示例，它示范了如何使用 SQLiteOpenHelper 实现数据从非加密往加密迁移和 Schema 升级。

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

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

从 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,                   // CursorFactorynull                    // DatabaseErrorHandler// SQLiteDatabaseHook 参数去掉了，在cipher里指定参数可达到同样目的);

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

Markdown