FerretDB v1.6.0 发布解读：SQLite 后端 ping/getParameter、killCursors 游标管理与关键修复

• 后端
• 数据库
• 文档数据库

FerretDB v1.6.0 是面向 MongoDB 兼容层的又一次功能性与健壮性升级：在已有 SQLite 后端 Beta 支持的基础上新增了ping命令与getParameter方法的实现，同时通过killCursors命令显著改善游标生命周期管理，并修复了$set更新同一_id报错、findOne()查询翻译异常等若干历史问题。本文以该版本的官方发布说明为骨架，结合当前仓库源码与集成测试，逐一还原这些功能背后的实现路径，帮助你理解命令解析、参数选择与游标回收的实际行为，并掌握升级到该版本前后的注意事项。

版本背景：SQLite 后端 Beta 能力持续补全

FerretDB v1.6.0 的核心工作围绕此前引入的 SQLite 后端 Beta 支持展开。该版本为 SQLite 后端补齐了两项 MongoDB 协议层面高频使用的能力：

• ping命令：客户端（驱动、监控探针）用于探测服务可用性的标准命令；
• getParameter方法：用于查询服务端运行参数的诊断命令。

这两项命令的加入，让基于 SQLite 后端的部署在健康检查与运维诊断上与基于 PostgreSQL 后端的部署保持同等体验。在当前仓库中，这两个命令分别由 internal/handler/msg_ping.go 与 internal/handler/msg_getparameter.go 实现，二者已被列入 internal/handler/commands.go 的命令注册表，任何后端的 FerretDB 实例都统一走同一套命令分发链路（经由 internal/handler/middleware/dispatcher.go 派发到对应 handler）。

ping 命令：一次真实的往返校验

ping在 MongoDB 生态中承担双重职责：一是确认服务器在线，二是校验客户端与服务端之间连接与认证上下文的有效性。从源码看，FerretDB 的ping并不是简单的空操作：

1. 首先调用h.s.CreateOrUpdateByLSID处理会话标识（lsid），保证逻辑会话状态与客户端同步；
2. 随后通过连接池h.p.WithConn获取一个底层连接，并执行documentdb_api.BinaryExtendedVersion发起一次真实的数据库往返；
3. 最后返回{ "ok": 1 }。

也就是说，FerretDB 的ping会真正触达存储后端完成一次往返校验（见 internal/handler/msg_ping.go），而非仅在内核层面返回成功，这使其可以作为可靠的存活探针使用。

getParameter：受控的参数查询

getParameter命令用于读取服务端运行参数，FerretDB 当前维护了如下参数集合（源码见 internal/handler/msg_getparameter.go）：

该命令支持两种调用形态：

• 传入"*"：返回全部参数（对应源码中的allParameters = true）；
• 传入文档{showDetails: bool, allParameters: bool}：按选项决定是否输出每个参数的value、settableAtRuntime、settableAtStartup细节，以及是否忽略命令体中未显式点名的参数。

其过滤逻辑由selectParameters完成（internal/handler/msg_getparameter.go）：当allParameters为 false 时，只返回命令文档中显式出现的参数键；若最终没有任何参数被选中，则返回错误码 72（InvalidOptions，消息为 "no option found to get"）。这一行为与 MongoDB 保持一致，并在 integration/commands_administration_test.go 中通过数十个用例得到验证，包括通配符、整型/字符串/空值参数、布尔细节开关、负数与最小浮点数等边界输入。

killCursors：游标管理的关键升级

在 v1.6.0 之前，游标的创建与回收机制相对粗放，长时间运行或异常中断的查询可能留下未释放的游标资源。该版本实现了killCursors命令，客户端可以显式请求终止一组游标，从而优化资源管理与后端性能。

从 internal/handler/msg_killcursors.go 的实现看，处理流程如下：

1. 从命令文档中解析$db、集合名以及cursors数组；
2. 逐项校验游标 ID 类型：cursors中每一项必须是int64（long 类型），否则返回类型不匹配错误（错误码 14TypeMismatch）；
3. 依次对每个游标执行会话级游标删除（h.s.DeleteCursor）与底层连接游标终止（h.p.KillCursor）；
4. 按结果分别归类到cursorsKilled、cursorsNotFound、cursorsAlive、cursorsUnknown四个返回字段。

集成测试 integration/cursor/kill_test.go 完整覆盖了四种典型场景：空游标列表、错误类型 ID、已存在游标被成功终止（终止后再次读取返回CursorNotFound）、以及部分游标不存在时的cursorsNotFound归类，确保返回结构（cursorsKilled、cursorsNotFound、cursorsAlive、cursorsUnknown、ok）与 MongoDB 完全对齐。配合 internal/documentdb/cursor 目录下的游标注册表实现，FerretDB 在 v1.6.0 起具备了从协议层到底层的完整游标生命周期闭环。

Bug 修复：$set更新同一_id与findOne()查询翻译

允许$set设置与文档相同的_id

在早期版本中，执行类似db.collection.updateOne({_id: 1}, {$set: {_id: 1, a: 1}})的更新会报错——更新操作被要求不得修改_id字段，即使新值与原值完全相同也会被拒。v1.6.0 修复了该问题：当$set写入的_id与文档现有_id相等时，视为幂等操作直接放行，不再抛出错误。对应的兼容性测试位于 integration/query/findandmodify_compat_test.go，其注释 "to have the same _id for target and compat" 明确验证了目标后端与 MongoDB 参考实现在此场景下行为一致。

findOne()的 PostgreSQL 查询翻译修复

另一个被重点修复的问题是findOne()查询无法被正确翻译为对应的 PostgreSQL 查询语句，并且会引发显著延迟。尽管当前仓库已演进到 v2 架构（查询执行由 internal/documentdb/documentdb_core/documentdb_core.go 等模块承担），该修复的意义在于验证了"单文档读取"这一高频路径在查询翻译层需要被当作特殊形态处理——即限制返回条数并提前结束扫描，而不是退化为全量查询后截断。相关行为可在 integration/query/main_test.go 与 integration/query/findandmodify_compat_test.go 中找到持续回归验证。

其他变化：Tigris 后端终止支持

与功能增强相对的是平台策略的收敛：FerretDB 在 v1.6.0 中正式确认将停止对 Tigris 后端的支持。官方说明明确指出，若仍需使用 Tigris 后端，请不要将 FerretDB 升级到 v1.5.0 之后的版本；更早的、仍含 Tigris 支持的发布版本均可继续使用。与此同时，该版本的 README 补充了更多 SQLite 后端的部署与配置指引，便于用户在新后端上快速上手（相关后端配置可参考仓库根目录的 README.md 与 docker-compose.yml）。

升级建议与总结

综合来看，FerretDB v1.6.0 的增量价值集中在三点：

1. SQLite 后端可用性提升：ping与getParameter让基于 SQLite 的部署具备了完整的健康检查与参数诊断能力；
2. 资源管理更可控：killCursors使客户端能主动回收不再使用的游标，降低长连接场景下的资源占用；
3. 兼容性细节修正：$set幂等更新_id、findOne()查询翻译等问题被修复，减少了应用迁移时遇到的边界错误。

如果你正在从 v1.5.0 及更早版本升级，建议先确认是否仍依赖 Tigris 后端；若已迁移到 PostgreSQL 或 SQLite 后端，则可以放心升级，并通过getParameter快速核验新实例的运行参数是否符合预期。

• 后端
• 数据库
• 文档数据库