Android项目从SQLCipher 3.5.9迁移至4.5.4时崩溃求助

我在Android项目中将net.zetetic:android-database-sqlcipher从3.5.9版本迁移至4.5.4版本，已按照官方文档修改代码——在DatabaseHelper构造函数中添加SQLiteDatabaseHook，于postKey方法异步执行PRAGMA cipher_migrate进行迁移。但出现两处致命崩溃：

• 在AsyncTask中调用clearTables时，执行getWritableDatabase步骤抛出unable to close due to unfinalized statements or unfinished backups异常；
• postKey中执行PRAGMA cipher_migrate后返回cursor为空，触发迁移失败异常。

已参考官方迁移文档但问题仍未解决，恳请协助排查。

迁移前核心代码 #

public class DatabaseHelper extends SQLiteOpenHelper {
        // ... 原有代码 ...
        private DatabaseHelper(Context context) {
            super(context, DBNAME, null, VERSION);
            this.context = context;
        }
        // ... 原有代码 ...
}

迁移后修改的构造函数 #

private DatabaseHelper(Context context) {
          super(context, DBNAME, null, VERSION, new SQLiteDatabaseHook() {
             @Override
             public void preKey(SQLiteDatabase sqLiteDatabase) {}
             @Override
             public void postKey(SQLiteDatabase sqLiteDatabase) {
                 Executors.newSingleThreadExecutor().execute(() -> {
                     try (Cursor cursor = sqLiteDatabase.rawQuery("PRAGMA cipher_migrate", null)) {
                        if (cursor != null && cursor.moveToFirst()) {
                            int result = cursor.getInt(0);
                            if (result != 0) throw new SQLiteException("Cipher migration failed");
                         } else throw new SQLiteException("No result from PRAGMA cipher_migrate");
                      } catch (Exception e) {
                           throw new SQLiteException("Error executing PRAGMA cipher_migrate", e);
                      }
                });
             }
         });
         this.context = context;
     }

崩溃日志1（clearTables时） #

java.lang.RuntimeException: An error occurred while executing doInBackground()
Caused by: android.database.sqlite.SQLiteException: unable to close due to unfinalized statements or unfinished backups: sqlite3_close() failed

崩溃日志2（迁移时） #

android.database.sqlite.SQLiteException: Error executing PRAGMA cipher_migrate
Caused by: android.database.sqlite.SQLiteException: Cipher migration failed

问题分析与修复方案 #

针对崩溃1：未完成语句/备份导致无法关闭数据库

问题根源在于异步执行迁移操作时，数据库连接被多线程持有，同时主线程/AsyncTask尝试关闭或获取可写数据库，引发资源冲突。SQLCipher的PRAGMA cipher_migrate必须在持有数据库连接的同一个线程中同步执行，不能异步放到其他线程池。

修复步骤：

1. 移除Executors.newSingleThreadExecutor().execute()的异步包装，直接在postKey方法所在线程同步执行迁移操作；
2. 确保迁移过程中没有其他线程同时操作数据库，建议在App启动初期完成迁移后再允许其他数据库操作。

针对崩溃2：迁移返回cursor为空或结果非0

可能原因包括：

• 异步执行导致数据库连接状态异常，迁移未正确触发；
• 旧版本数据库存在损坏，或密钥不匹配；
• PRAGMA cipher_migrate执行时缺少必要的权限或文件访问异常。

修复步骤：

1. 同步执行PRAGMA cipher_migrate（解决崩溃1的同时也会修复此问题的大部分场景）；
2. 增加错误日志输出，打印cursor状态和迁移结果码，便于定位具体失败原因：

@Override
public void postKey(SQLiteDatabase sqLiteDatabase) {
    try (Cursor cursor = sqLiteDatabase.rawQuery("PRAGMA cipher_migrate", null)) {
        if (cursor != null) {
            if (cursor.moveToFirst()) {
                int result = cursor.getInt(0);
                Log.d("SQLCipherMigration", "Migration result code: " + result);
                if (result != 0) {
                    throw new SQLiteException("Cipher migration failed with code: " + result);
                }
            } else {
                Log.e("SQLCipherMigration", "Cursor has no rows");
                throw new SQLiteException("No result from PRAGMA cipher_migrate");
            }
        } else {
            Log.e("SQLCipherMigration", "Cursor is null");
            throw new SQLiteException("Null cursor from PRAGMA cipher_migrate");
        }
    } catch (Exception e) {
        Log.e("SQLCipherMigration", "Migration error", e);
        throw new SQLiteException("Error executing PRAGMA cipher_migrate", e);
    }
}

3. 验证数据库文件路径和密钥的正确性，确保迁移前数据库可以正常打开；
4. 若数据库存在损坏，可尝试先使用旧版本SQLCipher打开并备份数据，再迁移到新版本。

内容的提问来源于stack exchange，提问作者Anshuman Biswal