SQLDelight 数据库迁移在 Compose Desktop 中的实践

问题背景

在使用 SQLDelight 2.0.1 版本开发 Compose Desktop 应用时，开发者遇到了数据库表结构变更的迁移问题。具体场景是需要在已有的 Config 表中添加一个新字段 keytool_path，但迁移过程未能按预期执行。

初始表结构

最初的 Config 表定义如下：

CREATE TABLE IF NOT EXISTS Config (
   id INTEGER NOT NULL PRIMARY KEY,
   dark_mode INTEGER NOT NULL,
   aapt_path TEXT NOT NULL,
   flag_delete INTEGER AS Boolean NOT NULL,
   signer_suffix TEXT NOT NULL,
   output_path TEXT NOT NULL,
   is_align_file_size INTEGER AS Boolean NOT NULL
);

表创建时还包含了一个初始化数据的 INSERT 语句。

迁移需求

开发者需要为 Config 表添加一个名为 keytool_path 的新字段，类型为 TEXT，不允许为空，默认值为空字符串。

迁移方案

第一步：创建迁移文件

按照 SQLDelight 的迁移规范，创建了 1.sqm 文件，内容为：

ALTER TABLE Config ADD COLUMN keytool_path TEXT NOT NULL DEFAULT '';

第二步：更新表定义

同时更新了 Config.sq 文件中的表定义，添加了新字段：

CREATE TABLE IF NOT EXISTS Config (
   id INTEGER NOT NULL PRIMARY KEY,
   dark_mode INTEGER NOT NULL,
   aapt_path TEXT NOT NULL,
   flag_delete INTEGER AS Boolean NOT NULL,
   signer_suffix TEXT NOT NULL,
   output_path TEXT NOT NULL,
   is_align_file_size INTEGER AS Boolean NOT NULL,
   keytool_path TEXT NOT NULL DEFAULT ''
);

第三步：遇到的问题

执行迁移时出现了错误，提示 Config 表不存在 keytool_path 列。这表明迁移脚本没有正确执行。

问题分析

1. 迁移机制理解不足：开发者可能没有正确理解 SQLDelight 的自动迁移机制
2. 驱动初始化方式：直接调用 Schema.create 而不是让驱动自动处理迁移
3. 版本控制：数据库版本号管理可能存在问题

解决方案

正确使用 JdbcSqliteDriver

关键点在于正确初始化数据库驱动，让 SQLDelight 自动处理迁移：

JdbcSqliteDriver(
    url = "jdbc:sqlite:test.db",
    properties = Properties(),
    schema = Database.Schema,
    migrateEmptySchema = false
)

迁移机制工作原理

SQLDelight 的 JdbcSqliteDriver 构造函数内部会：

1. 检查当前数据库版本
2. 如果是空数据库且 migrateEmptySchema 为 false，直接创建最新表结构
3. 如果当前版本低于目标版本，执行迁移脚本
4. 更新数据库版本号

迁移脚本编写规范

1. 每个迁移文件应命名为 [version].sqm
2. 文件内容应为纯 SQL 语句
3. 不需要手动更新 INSERT 语句，除非有特殊需求
4. 迁移脚本应专注于表结构变更

最佳实践

1. 版本控制：每次表结构变更都应增加版本号并创建对应的 .sqm 文件
2. 测试迁移：在开发环境中测试从旧版本到新版本的完整迁移流程
3. 数据备份：重要数据在迁移前应做好备份
4. 回滚计划：为可能失败的迁移准备回滚方案

总结

SQLDelight 提供了完善的数据库迁移机制，但在 Compose Desktop 环境中使用时需要注意驱动初始化的正确方式。通过理解其内部迁移流程和版本控制机制，可以确保数据库结构变更能够平滑执行。开发者应遵循迁移脚本的编写规范，并在实际项目中充分测试迁移过程。