Drizzle ORM 中 SQLite 数据库迁移的常见问题与解决方案

问题背景

在使用 Drizzle ORM 进行 SQLite 数据库迁移时，许多开发者遇到了一个特定的错误："This statement does not return data. Use run() instead"。这个问题主要出现在执行 db:push 命令时，特别是在 Mac 系统上，但 Windows 用户也报告了类似情况。

错误分析

该错误的核心在于 Drizzle Kit 在执行 SQL 语句时错误地使用了 query() 方法而不是 run() 方法。在 SQLite 中，对于不返回数据的 DDL（数据定义语言）和 DML（数据操作语言）语句，应该使用 run() 方法而非 query() 方法。

技术细节

SQLite 驱动区分了两种执行 SQL 语句的方式：

1. query() - 用于执行会返回数据的 SELECT 查询
2. run() - 用于执行不返回数据的 INSERT、UPDATE、DELETE 等语句

在数据库迁移场景中，执行的通常是 CREATE TABLE、ALTER TABLE 等 DDL 语句，这些语句不返回数据，因此应该使用 run() 方法。

解决方案演进

临时解决方案

开发者们发现了以下几种临时解决方案：

1. 手动修改 Drizzle Kit 源码： 找到 node_modules 中的相关文件，将所有 db.query() 调用替换为 db.run()

2. 降级 Drizzle Kit 版本： 使用 0.22.8 版本可以避免此问题，因为该版本正确使用了 run() 方法

官方修复

Drizzle 团队在 0.28.0 版本中正式修复了这个问题。更新日志显示：

• 修复了 SQLite 迁移时错误使用 query() 而不是 run() 的问题
• 确保了 BEGIN、COMMIT 和 ROLLBACK 等事务语句也使用正确的执行方法

最佳实践建议

1. 版本选择： 确保使用 Drizzle Kit 0.28.0 或更高版本

2. 环境一致性： 虽然问题最初在 Mac 上报告，但实际是跨平台的，建议所有开发环境使用相同版本

3. 迁移策略： 对于关键项目，建议先在小规模测试环境中验证迁移操作

4. 错误处理： 实现完善的错误处理机制，特别是在自动迁移脚本中

技术原理延伸

理解这个问题有助于深入掌握数据库操作的基本原理。SQL 语句分为两大类：

• 查询语句（SELECT）：需要返回数据结果集
• 非查询语句（INSERT/UPDATE/DELETE/CREATE 等）：只返回执行状态

现代 ORM 工具通常会抽象这些细节，但在底层实现中仍需正确处理。Drizzle ORM 的这个案例展示了即使高级抽象层也可能暴露底层细节，理解这些机制有助于更好地使用工具和调试问题。

总结

Drizzle ORM 的 SQLite 迁移问题是一个典型的 API 使用不当案例，通过分析这个问题，我们不仅找到了解决方案，还加深了对数据库操作原理的理解。对于开发者而言，保持工具链更新和深入理解底层原理同样重要。