Drift数据库迁移中布尔列添加失败问题解析

问题背景

在使用Drift（原Moor）数据库框架进行SQLite数据库迁移时，开发者遇到了一个典型问题：在从Schema 1升级到Schema 2的过程中，尝试添加一个带有默认值(false)的布尔(BoolColumn)列时，迁移操作失败并抛出SQLite异常。

问题现象

迁移脚本执行时出现以下错误：

SqliteException(1): while executing, SQL logic error, SQL logic error (code 1)
Causing statement: ALTER TABLE "input_db" ADD COLUMN "status" INTEGER NOT NULL DEFAULT (0) CHECK ("status" IN (0, 1));

技术分析

SQLite的布尔类型实现

SQLite本身没有专门的布尔数据类型，而是使用整数类型(INTEGER)来存储布尔值，其中0表示false，1表示true。Drift框架的BoolColumn实际上就是在底层转换为这种实现方式。

问题根源

这个问题与SQLite 3.37.2版本中的一个已知bug有关。该bug在特定条件下会影响ALTER TABLE语句的执行，特别是当数据库启用了双引号字符串字面量(double-quoted string literals)功能时。

SQLite的限制

根据SQLite官方文档，ALTER TABLE语句添加列时有明确的限制：

• 新添加的列不能使用CURRENT_TIME、CURRENT_DATE或CURRENT_TIMESTAMP作为默认值
• 默认值不能是括号内的表达式

解决方案

临时解决方案

对于使用SQLite 3.37.2或更低版本的情况，可以通过以下方式解决：

1. 在测试设置中修改SchemaVerifier的配置
2. 对于低于3.38.0的SQLite版本，显式启用双引号字符串字面量功能

示例代码：

setUpAll(() {
  verifier = SchemaVerifier(
    GeneratedHelper(),
    setup: (database) {
      if (sqlite3.version.versionNumber < 3038000) {
        database.config.doubleQuotedStringLiterals = true;
      }
    },
  );
});

长期建议

1. 考虑升级SQLite到3.38.0或更高版本，该版本已修复此问题
2. 如果暂时无法升级，可以使用IntColumn替代BoolColumn作为临时解决方案
3. 在迁移测试中保持与实际应用环境一致的SQLite配置

最佳实践

1. 在进行数据库迁移前，先了解当前使用的SQLite版本及其已知问题
2. 为重要的数据库变更编写充分的迁移测试
3. 考虑在应用启动时检查数据库版本和SQLite版本，必要时提示用户升级
4. 对于关键业务数据，考虑实现数据备份和回滚机制

总结

数据库迁移是应用开发中的关键环节，特别是在处理已有数据的表结构变更时需要格外谨慎。通过理解底层数据库引擎的特性和限制，可以避免许多潜在的迁移问题。Drift框架虽然提供了便利的迁移工具，但开发者仍需对SQLite本身的行为有基本了解，才能编写出健壮的迁移代码。