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

引言

SQLDelight 是一个强大的 SQL 代码生成库，它能够帮助开发者编写类型安全的 SQL 查询语句。在 Compose Desktop 应用开发中，数据库迁移是一个常见需求，本文将详细介绍如何在 SQLDelight 中正确执行数据库迁移操作。

数据库迁移的基本原理

SQLDelight 的数据库迁移机制基于版本控制。每个数据库都有一个版本号，当检测到当前数据库版本低于最新定义的模式版本时，系统会自动执行迁移脚本。

迁移脚本通常以 .sqm 为后缀，命名规则为 [version].sqm，其中 [version] 是迁移的目标版本号。例如 1.sqm 表示从版本 0 迁移到版本 1 的脚本。

常见问题分析

在实际开发中，开发者经常会遇到以下两类问题：

1. 迁移脚本未执行：通常是由于版本号设置不正确或迁移机制未被正确触发导致的。
2. 迁移执行失败：往往是因为迁移脚本与当前数据库状态不兼容，或者迁移脚本本身存在语法错误。

解决方案

正确配置数据库驱动

在 Compose Desktop 中创建数据库驱动时，需要确保正确传递模式对象和迁移回调：

JdbcSqliteDriver(
    url = "jdbc:sqlite:test.db",
    properties = Properties(),
    schema = Database.Schema,
    migrateEmptySchema = false, // 根据需求设置
    callbacks = arrayOf(afterVersionCallback) // 可选的迁移回调
)

编写迁移脚本

迁移脚本应只包含变更部分，不需要重复完整的表定义。例如，添加一个新列的迁移脚本应如下：

-- 1.sqm
ALTER TABLE Config ADD COLUMN keytool_path TEXT NOT NULL DEFAULT '';

处理初始数据插入

在表结构变更后，初始数据插入语句也需要相应更新：

INSERT INTO Config(id, dark_mode, aapt_path, flag_delete, signer_suffix, output_path, is_align_file_size, keytool_path)
SELECT 0, 0,"", 1, "_sign", "", 1, ""
WHERE (SELECT COUNT(*) FROM Config WHERE id = 0) = 0;

最佳实践

1. 版本控制：每次数据库结构变更都应创建一个新的迁移脚本，并递增版本号。
2. 测试迁移：在实际应用前，应在测试环境中验证迁移脚本的正确性。
3. 备份数据：执行迁移前建议备份数据库，以防意外情况发生。
4. 原子性操作：确保每个迁移脚本都是原子性的，要么全部成功，要么全部失败。

常见错误排查

1. 表不存在或列不存在错误：检查迁移脚本的执行顺序是否正确。
2. 约束冲突：确保新增的非空列有默认值或迁移脚本提供了合理的默认值。
3. 版本不一致：确认数据库的实际版本与代码中定义的版本一致。

总结

SQLDelight 提供了强大的数据库迁移支持，但在 Compose Desktop 环境中使用时需要注意一些细节。通过正确配置数据库驱动、编写规范的迁移脚本以及遵循最佳实践，可以确保数据库迁移过程顺利进行。当遇到问题时，应仔细检查错误信息，确认迁移脚本与数据库当前状态的兼容性。

掌握这些技巧后，开发者可以更加自信地在 Compose Desktop 应用中管理数据库变更，确保应用数据的完整性和一致性。