KuzuDB Node.js 连接关闭异常问题分析与解决方案

问题背景

在使用 KuzuDB 的 Node.js 客户端时，开发者可能会遇到一个隐蔽的内存管理问题。当执行数据库查询后立即关闭连接和数据库实例时，进程可能会异常退出，返回错误代码 -1073740940 (0xC0000374)。这个问题在 Windows 10 系统上尤为明显，但在其他平台也可能存在类似隐患。

问题本质

该问题的根源在于 Node.js 绑定层对 KuzuDB C++ 核心资源的管理机制。在当前的实现中：

1. 每个查询操作都会隐式创建一个 QueryResult 对象
2. 这些结果对象需要显式释放资源
3. 如果未正确释放就关闭上级连接和数据库实例，会导致堆损坏

技术细节

当执行以下典型操作序列时容易触发问题：

1. 创建数据库连接
2. 执行查询（隐式创建 QueryResult）
3. 直接关闭连接和数据库
4. 隐式创建的 QueryResult 未被正确释放

这种资源管理问题在 C++/Node.js 混合编程环境中较为常见，特别是在涉及多级资源依赖时。

解决方案

正确的资源管理方式应该是显式关闭所有层级的对象，按照从内到外的顺序：

import * as kuzu from "kuzu";

// 初始化数据库和连接
const db = new kuzu.Database(":memory:");
const connection = new kuzu.Connection(db);

// 执行查询并获取显式结果引用
const result = await connection.query(
  "CREATE NODE TABLE User(name STRING, age INT64, PRIMARY KEY (name))"
);

// 按正确顺序释放资源
result.close();      // 先关闭结果集
await connection.close();  // 再关闭连接
await db.close();    // 最后关闭数据库

最佳实践建议

1. 显式资源管理：对所有可能创建资源的操作都保持显式引用
2. 释放顺序：遵循从内到外的释放顺序（结果集→连接→数据库）
3. 错误处理：在 try-catch-finally 块中确保资源释放
4. 版本跟踪：关注后续版本对此问题的修复情况

底层原理

这个问题本质上反映了 Node.js 与原生 C++ 库交互时的常见挑战。KuzuDB 的核心是用 C++ 编写的，通过 Node-API 暴露给 JavaScript。当 JavaScript 对象被垃圾回收时，并不总是能及时触发原生资源的释放，特别是在存在复杂依赖关系的情况下。

未来改进

KuzuDB 开发团队已经意识到这个问题，计划在后续版本中改进资源管理机制，可能的改进方向包括：

1. 实现自动资源回收
2. 提供更友好的错误提示
3. 完善文档中的资源管理说明

对于开发者而言，在当前版本中遵循显式资源管理规范是最稳妥的解决方案。