Drift数据库加密迁移方案详解

背景介绍

在使用Drift（原名Moor）框架开发Flutter应用时，数据库加密是一个重要的安全特性。然而在实际开发中，可能会遇到这样的情况：应用最初发布时未启用数据库加密，后续版本需要将现有未加密数据库迁移到加密数据库，同时保留所有数据。

核心问题

当开发者发现应用发布时意外使用了未加密数据库，而后续版本需要启用加密功能时，面临的主要挑战是如何安全地将现有数据从明文数据库迁移到加密数据库，同时确保：

1. 所有现有数据完整保留
2. 数据库结构保持不变
3. 版本信息等重要元数据不丢失

解决方案

Drift官方推荐的方法是创建一个新的加密数据库，然后将现有数据从旧数据库完整复制过去。这种方法安全可靠，避免了直接修改现有数据库文件可能带来的风险。

具体实现步骤

1. 准备阶段：

   • 确定原始数据库路径和加密后数据库路径
   • 准备加密密钥

2. 迁移过程：

   • 检查原始数据库是否存在且加密数据库尚未创建
   • 记录原始数据库的user_version（存储数据库版本号）
   • 使用SQLCipher的sqlcipher_export函数将数据导出到加密数据库
   • 验证加密数据库创建成功
   • 将原始数据库的user_version应用到新数据库
   • 删除原始数据库文件

3. 初始化加密数据库：

   • 设置加密密钥
   • 配置SQLCipher相关选项

关键代码实现

final existingDatabasePath = '/path/to/your/database.db';
final encryptedDatabasePath = '/path/to/your/encrypted.db';
const yourKey = 'passphrase';

// 创建加密数据库
NativeDatabase.createInBackground(
  File(encryptedDatabasePath),
  isolateSetup: () async {
    // 初始化环境
    BackgroundIsolateBinaryMessenger.ensureInitialized(token);
    await setupSqlCipher();

    final existing = File(existingDatabasePath);
    final encrypted = File(encryptedDatabasePath);

    if (await existing.exists() && !await encrypted.exists()) {
      // 记录原始数据库版本
      final userVersion = db.select('PRAGMA user_version;').first.columnAt(0) as int;

      // 执行数据迁移
      sqlite3.open(existingDatabasePath)
        ..execute("ATTACH DATABASE '${escapeString(encryptedDatabasePath)}' "
            "AS encrypted KEY '${escapeString(yourKey)}';")
        ..execute("SELECT sqlcipher_export('encrypted');")
        ..execute('DETACH DATABASE encrypted;')
        ..dispose();

      // 验证迁移成功
      assert(await encrypted.exists());

      // 设置新数据库版本
      sqlite3.open(encryptedDatabasePath)
        ..execute("PRAGMA key = '$password'");
        ..execute('PRAGMA user_version = $userVersion');
        ..dispose();

      // 清理原始数据库
      await existing.delete();
    }
  },
  setup: (rawDb) {
    // 验证加密支持
    assert(_debugCheckHasCipher(rawDb));
    rawDb.execute("PRAGMA key = '${escapeString(yourKey)}';");

    // 推荐配置
    rawDb.config.doubleQuotedStringLiterals = false;
  },
);

注意事项

1. 版本号迁移：必须手动迁移user_version，否则数据库迁移后版本号会丢失，导致后续迁移脚本无法正确执行。

2. 字符串转义：处理数据库路径和密钥时需要进行适当的转义，防止SQL注入。

3. 原子性操作：确保整个迁移过程是原子性的，要么完全成功，要么完全失败，避免处于中间状态。

4. 错误处理：实际应用中需要添加适当的错误处理和日志记录。

5. 性能考虑：对于大型数据库，迁移可能需要较长时间，应考虑在后台执行并显示进度。

替代方案分析

另一种理论上的方法是直接对现有数据库文件应用加密，但这种方法存在以下问题：

1. SQLite不直接支持对现有数据库文件进行加密转换
2. 操作风险较高，可能导致数据损坏
3. 缺乏标准化的实现方式

因此，创建新数据库并复制数据的方案更为可靠和安全。

最佳实践建议

1. 开发阶段启用加密：即使最初不需要加密，也建议在开发阶段就启用数据库加密，避免后续迁移。

2. 测试迁移流程：在实际应用前，充分测试迁移流程，特别是针对不同大小的数据库。

3. 备份机制：在执行迁移前，考虑实现备份机制，以防迁移失败需要回滚。

4. 用户通知：对于大型数据库迁移，考虑通知用户可能需要较长时间。

通过遵循这些指导原则，开发者可以安全可靠地将现有Drift数据库从明文状态迁移到加密状态，确保应用数据的安全性。