SQLDelight 2.0 升级指南：关键变更与迁移策略

SQLDelight 2.0 升级指南：关键变更与迁移策略

sqldelight SQLDelight - Generates typesafe Kotlin APIs from SQL 项目地址: https://gitcode.com/gh_mirrors/sq/sqldelight

前言

SQLDelight 作为一款强大的 SQL 类型安全生成工具，在 2.0 版本中进行了多项重大改进。本文将详细介绍从 1.x 版本升级到 2.0 版本需要注意的关键变更点，帮助开发者顺利完成迁移。

包名与依赖变更

2.0 版本最显著的变化是包名和 Maven 依赖的 groupId 发生了改变：

- com.squareup.sqldelight
+ app.cash.sqldelight

具体变更包括：

1. Gradle 插件声明：需要更新插件 ID
2. 运行时依赖：所有相关依赖的 groupId 都需要修改
3. 代码中的导入语句：所有 SQLDelight 相关的 import 都需要更新

对于纯 Android 项目，特别注意协程扩展模块现在需要明确指定 JVM 目标平台：

dependencies {
  implementation("app.cash.sqldelight:android-driver:版本号")
  implementation("app.cash.sqldelight:coroutines-extensions-jvm:版本号")
}

Gradle 配置变更

环境要求

• 构建环境：需要 Java 11 或更高版本
• 运行时环境：最低支持 Java 8

数据库配置新语法

2.0 版本引入了更现代的 Gradle 配置 API，主要变化包括：

1. 使用 databases 作为 DomainObjectCollection 包装器
2. 配置属性现在使用 Property<T> 类型
3. sourceFolders 重命名为 srcDirs

Kotlin DSL 示例：

sqldelight {
  databases {
    create("Database") {
      packageName.set("com.example")
      srcDirs.setFrom("src/main/sqldelight")
    }
  }
}

SQL 方言配置

现在通过 Gradle 依赖来指定 SQL 方言：

dialect("app.cash.sqldelight:mysql-dialect:版本号")

支持的方言包括：

• MySQL
• PostgreSQL
• HSQL
• 多个 SQLite 版本（3.18、3.24、3.25、3.30、3.35、3.38）

运行时 API 变更

类型系统改进

1. 基本类型显式导入：.sq 文件中现在需要显式导入 Kotlin 基本类型
2. 类型适配器：某些类型现在需要适配器，基本类型适配器可通过 primitive-adapters 模块获取

示例变更：

+import kotlin.Boolean;

CREATE TABLE HockeyPlayer (
  name TEXT NOT NULL,
  good INTEGER AS Boolean
);

迁移 API 重构

1. AfterVersionWithDriver 被移除，统一使用 AfterVersion
2. migrateWithCallbacks 被移除，迁移回调现在直接通过 migrate 方法提供

新迁移示例：

Database.Schema.migrate(
  driver = driver,
  oldVersion = 1,
  newVersion = Database.Schema.version,
  AfterVersion(3) { driver ->
    driver.execute(null, "INSERT INTO test (value) VALUES('hello')", 0)
  }
)

架构相关变更

1. Schema 不再是 SqlDriver 的嵌套类型，重命名为 SqlSchema
2. Schema.Version 类型从 Int 改为 Long，支持使用时间戳作为版本号

扩展 API 变更

协程扩展

现在需要显式指定调度器：

val players: Flow<List<HockeyPlayer>> =
  playerQueries.selectAll()
    .asFlow()
+   .mapToList(Dispatchers.IO)

分页扩展

Paging3 扩展 API 现在仅支持 Int 类型的计数。

异步支持增强

多个驱动方法现在返回 QueryResult 对象，支持非阻塞 API：

driver.executeQuery(null, "PRAGMA user_version", { /*...*/ }).value

关键方法变更：

• execute()
• executeQuery()
• newTransaction()
• endTransaction()
• SqlCursor.next()

迁移建议

1. 逐步迁移：先更新依赖和包名，再处理 API 变更
2. 类型适配器：检查 .sq 文件中的类型使用，添加必要的导入和适配器
3. 测试验证：特别注意迁移逻辑和异步操作的变更点
4. 多平台项目：注意同步和异步驱动混合使用时的兼容性问题

结语

SQLDelight 2.0 的这些变更为框架带来了更好的类型安全性和异步支持，虽然迁移需要一些工作，但这些改进将为项目带来长期收益。建议开发者参考官方文档和变更日志，制定适合自己项目的迁移计划。

sqldelight SQLDelight - Generates typesafe Kotlin APIs from SQL 项目地址: https://gitcode.com/gh_mirrors/sq/sqldelight