SQLCipher for Android 数据库加密库迁移指南

概述

SQLCipher for Android 是一个为 Android 应用提供数据库加密功能的开源库。随着技术发展，官方推出了新版本的库(sqlcipher-android)来替代旧版本(android-database-sqlcipher)。本文将详细介绍如何从旧版本迁移到新版本，以及在此过程中可能遇到的问题和解决方案。

迁移背景

Google Play 商店已经开始提示开发者，使用旧版 android-database-sqlcipher 3.5.9 的应用将无法发布新版本。官方已明确表示 android-database-sqlcipher 库已被弃用，建议开发者迁移到 sqlcipher-android 4.5.5 或更高版本。

迁移步骤

1. 依赖项变更

首先需要修改项目的 build.gradle 文件，将旧版依赖替换为新版：

// 替换前
implementation 'net.zetetic:android-database-sqlcipher:3.5.9@aar'

// 替换后
implementation 'net.zetetic:sqlcipher-android:4.5.5@aar'
implementation 'androidx.sqlite:sqlite:2.2.0'

2. 初始化代码调整

旧版初始化方式：

SQLiteDatabase.loadLibs(context);

新版初始化方式：

SQLiteDatabase.loadLibs(context, libraries -> {
    for (String library : libraries) {
        ReLinker.loadLibrary(context, library);
    }
});

3. 数据库迁移处理

从 SQLCipher 3.x 升级到 4.x 时，需要执行数据库格式迁移。可以通过以下 PRAGMA 命令实现：

database.execSQL("PRAGMA cipher_migrate;");

注意：必须检查该命令的返回结果是否为0，表示迁移成功。不能仅依赖后续可能抛出的异常来判断迁移是否成功。

常见问题及解决方案

1. 原生库冲突问题

在迁移过程中，可能会遇到以下错误：

2 files found with path 'lib/arm64-v8a/libsqlcipher.so'

解决方案：

• 确保项目中只包含一个 SQLCipher 库依赖
• 检查所有直接和间接依赖项，避免同时引入新旧两个版本
• 清理 Gradle 缓存（删除 .gradle/caches 目录）
• 在 Android Studio 中执行 "Invalidate Caches/Restart"

2. 数据库文件兼容性问题

升级后首次运行时可能出现错误：

net.sqlcipher.database.SQLiteException: file is not a database

解决方案：

• 确保已正确执行数据库迁移操作
• 如果测试环境下可以接受数据丢失，可以卸载应用后重新安装
• 对于生产环境，必须实现完整的迁移路径

3. 多库共存问题

重要警告：在同一个应用中同时使用多个 SQLite/SQLCipher 库可能导致数据库损坏。应避免以下情况：

• 同时使用 android-database-sqlcipher 和 sqlcipher-android
• 混合使用不同版本的 SQLCipher
• 同时使用加密和非加密的 SQLite 实现

迁移建议

1. 测试策略：在开发环境中充分测试迁移过程，特别是数据完整性和性能方面
2. 备份机制：实现数据库备份功能，以防迁移失败
3. 分阶段发布：考虑分阶段向用户推送更新，先小范围测试再全面推广
4. 监控机制：添加迁移成功率的监控，及时发现潜在问题

总结

SQLCipher for Android 的库迁移是一个需要谨慎处理的过程。虽然官方暂时仍允许使用旧版 android-database-sqlcipher 4.x 系列，但建议开发者尽快规划迁移到 sqlcipher-android，以获得长期的技术支持和安全性更新。迁移过程中要特别注意数据兼容性和性能影响，确保用户体验不受影响。