FerretDB v1.13.0 新 PostgreSQL 后端:默认启用、Docker 数据目录与 pushdown 增强解读
FerretDB v1.13.0 新 PostgreSQL 后端:默认启用、Docker 数据目录与 pushdown 增强解读
FerretDB v1.13.0 是 FerretDB 在 2023 年 10 月发布的一个重要里程碑版本:此前数月持续迭代的新 PostgreSQL 后端在该版本中正式默认启用,同时带来了 Docker 镜像默认 SQLite 数据目录改为 /state 卷、linux/arm/v7 平台支持、以及针对 PostgreSQL/SQLite 两个后端的查询下推(pushdown)增强。本文以官方发布说明 website/blog/2023-10-24-ferretdb-v1130-new-postgresql-backend.md 为主线,结合当前仓库中的源码与构建配置,逐项解读这些变更的技术细节、配置方式与升级注意事项。
说明:本文描述的是 FerretDB v1.13.0 发布时的历史事实;当前仓库代码已演进至 v2 架构(基于 PostgreSQL DocumentDB 扩展),文中引用当前仓库文件仅用于佐证相关机制(如
/state目录、--postgresql-url参数等)的延续与实现,请注意区分版本语境。
版本概览:v1.13.0 带来了什么
本次发布的核心变更可以归纳为四点:
- 新 PostgreSQL 后端正式默认启用,旧后端可通过
--postgresql-old标志或FERRETDB_POSTGRESQL_OLD=true环境变量临时回退,但该回退开关将在下一个版本移除; - Docker 镜像的 SQLite 默认数据目录改为
/state,该目录同时声明为 Docker 卷(volume),容器重启后数据默认得以保留; - 新增
linux/arm/v7支持,覆盖二进制、Docker 镜像以及.deb/.rpm软件包; - 性能与兼容性增强:PostgreSQL 后端新增更多查询下推,SQLite 后端新增
_id: <string>过滤条件下推;修复了_id字段校验 bug;补齐了collStats、dbStats、聚合管道$collStats的部分缺失字段;并为 PostgreSQL 后端加入基础日志能力。
其中"新 PostgreSQL 后端默认启用"是本次发布最值得关注的架构级变化,下文优先展开。
新 PostgreSQL 后端:从默认关闭到默认开启
为什么会有"新 PostgreSQL 后端"
在 v1.13.0 之前的版本中,FerretDB 同时维护两套 PostgreSQL 后端实现:旧后端承载着早期功能,而新后端是团队花数月时间重写的实现,目标是更完整的 MongoDB 兼容性、更高效的查询下推以及更稳定的行为。v1.13.0 将新后端提升为默认路径,标志着它已具备承担日常使用的能力。
默认启用与临时回退开关
升级到 v1.13.0 后,无需任何额外配置即可使用新后端。如果遇到新后端行为与旧后端不一致的问题,可以临时回退:
# 方式一:命令行标志
ferretdb --postgresql-old
# 方式二:环境变量
FERRETDB_POSTGRESQL_OLD=true ferretdb
发布说明明确强调:该回退选项将在下一版本(v1.14)中移除,因此它只适合作为升级过渡期的应急手段,不应作为长期运行配置。
从当前仓库的 CLI 定义(cmd/ferretdb/main.go)可以看到,PostgreSQL 连接相关的核心参数至今依然沿用 --postgresql-url 形态,默认值为 postgres://127.0.0.1:5432/postgres,并支持通过 --postgresql-url-file 从文件中读取连接串(非空时覆盖前者)。这类"标志 + 同名环境变量(FERRETDB_ 前缀,见 kong.DefaultEnvars("FERRETDB"))"的双通道配置模式,正是发布说明中 FERRETDB_POSTGRESQL_OLD 环境变量能够生效的底层机制——所有 CLI 参数都可以用 FERRETDB_ + 大写参数名的方式以环境变量注入。
从源码看新后端的运行形态
虽然仓库当前已是 v2 代码库,但从结构上仍能清晰地看到新后端的核心特征:
- 处理命令直接面向 PostgreSQL 连接:例如
collStats与dbStats命令的处理逻辑(internal/handler/msg_collstats.go、internal/handler/msg_dbstats.go)都通过h.p.WithConn取得一个pgx.Conn,再调用documentdb_api.CollStats/documentdb_api.DbStats执行实际查询; - 命令处理与数据库访问解耦:命令入口位于 internal/handler,实际 SQL 执行位于 internal/documentdb/documentdb_api,中间由 internal/documentdb 的连接池(
pool.go)管理连接生命周期。
这印证了发布说明中"PostgreSQL 后端承载 collStats/dbStats 等统计命令"的描述,也说明统计类命令最终是在 PostgreSQL 侧计算并返回结果的。
Docker 镜像:SQLite 默认数据目录改为 /state 卷
变更内容
从 v1.13.0 起,FerretDB 的 Docker 镜像为 SQLite 后端引入了默认数据目录 /state。该目录被声明为 Docker 卷,因此:
- 容器重启后数据默认保留,无需手动挂载 volume;
- 数据持久化的"默认体验"得到显著改善,降低了误操作丢失数据的风险。
影响范围与例外
发布说明特别指出:此变更不影响二进制发行版以及 .deb/.rpm 软件包——这些形态的默认数据目录保持原样,只有 Docker 镜像采用了新的 /state 约定。
当前仓库中的印证
虽然 v1.13.0 距今已久,但 /state 目录约定在仓库中一直延续至今。在 build/ferretdb/production.Dockerfile 中可以看到:
VOLUME /state
ENV FERRETDB_STATE_DIR=/state
development.Dockerfile、eval.Dockerfile、eval-dev.Dockerfile 同样声明了 VOLUME /state 与 ENV FERRETDB_STATE_DIR=/state。对应地,cmd/ferretdb/main.go 中的 StateDir 参数(--state-dir,默认 .)与 state.NewProviderDir(cli.StateDir)(cmd/ferretdb/main.go)构成了状态目录的解析链路——镜像通过 ENV FERRETDB_STATE_DIR=/state 将进程状态目录指到 /state,再叠加 VOLUME 声明实现数据持久化。这正是 v1.13.0 发布说明所述"目录同时是 Docker 卷,重启后数据默认保留"的完整实现。
平台支持:linux/arm/v7
v1.13.0 是 FerretDB 较早覆盖 32 位 ARM 平台(arm/v7)的版本之一,新增形态包括:
linux/arm/v7二进制;- 对应架构的 Docker 镜像;
linux/arm/v7的.deb/.rpm软件包。
这对于运行在树莓派等 ARM 单板计算机上的用户尤为重要——意味着小型化、边缘化部署场景(如自建家庭服务器、IoT 环境中的数据存储)可以使用官方发布产物,而无需自行交叉编译。所有发行产物均可在项目的 GitHub Releases 页面按 tag 下载。
提示:当前仓库的构建体系已演进,
arm/v7是否仍作为持续发布的架构矩阵之一,以各版本实际发布的 Release 产物为准。本段落描述的是 v1.13.0 发布时的客观事实。
性能增强:更深的查询下推(pushdown)
PostgreSQL 后端:新增更多下推
"查询下推"是指把本应在 FerretDB 进程内完成的过滤、排序、聚合等操作,转换为 SQL 交给 PostgreSQL 执行,从而:
- 减少 FerretDB 与数据库之间的数据传输量;
- 充分利用 PostgreSQL 的索引与执行引擎;
- 降低内存占用与 CPU 开销。
v1.13.0 为 PostgreSQL 后端引入了额外的下推,使得更多类型的查询能够直接在数据库层完成。发布说明推荐通过此前的博客文章了解 FerretDB 下推的整体原理;仓库内亦可参考 website/versioned_docs/version-v1.24/pushdown.md 了解下推机制的文档化描述。
SQLite 后端:_id: <string> 过滤下推
SQLite 后端在 v1.13.0 中新增了 _id: <string> 形式过滤条件的下推。当查询形如:
db.collection.find({ _id: "some-string-id" })
时,该条件可以被直接下推到 SQLite 的 WHERE 子句,而无需先全量拉取文档再在内存中过滤。字符串类型的 _id 是 MongoDB 中最常见的文档标识形态,因此该优化覆盖面广、实用价值高。
其他变更:bug 修复与统计命令补齐
修复 _id 字段非法校验导致的误报
此前版本存在一个由 _id 字段校验逻辑不严谨引发的 bug:当尝试插入形如下面的文档时:
db.test.insertOne({ _id: 1, v: { _id: ["foo", "bar"] } })
会被错误地拒绝,并返回"_id value cannot be of type array"的错误。问题根源在于校验逻辑未能区分"顶层 _id"与"嵌套在普通字段 v 内部的 _id"——后者只是嵌套文档中的一个普通字段,其值完全可以是数组。v1.13.0 修正了这一误判,仅对真正的顶层 _id 字段施加类型约束。
补齐 collStats、dbStats、$collStats 字段
本次发布补齐了 collStats、dbStats 以及聚合管道 $collStats 阶段中此前缺失的部分字段,使统计类输出更贴近 MongoDB 的返回结构。从当前仓库实现看,collStats 命令支持 scale 参数(internal/handler/msg_collstats.go),并通过 documentdb_api.CollStats 在 PostgreSQL 侧计算;dbStats 命令则固定以 scale=1 调用 documentdb_api.DbStats(internal/handler/msg_dbstats.go)。这些细节说明统计命令并非简单转发,而是有真实的数据库端计算逻辑支撑。
PostgreSQL 后端基础日志
v1.13.0 为 PostgreSQL 后端加入了基础日志能力,便于排查连接问题、慢查询与错误行为。日志体系与 FerretDB 主进程一致(当前仓库中由 internal/util/logging 统一管理,支持 console/text/json/mongo 等格式,见 cmd/ferretdb/main.go 的 logFormats 定义),用户在调试后端行为时可通过日志定位 SQL 执行层面的异常。
升级与运行建议
结合发布说明与当前仓库的配置机制,升级到 v1.13.0(或参考其配置模式部署新版本)时有几点实践建议:
- 新后端默认启用,先做兼容性验证:升级后先运行常规读写、查询与聚合用例,确认业务行为符合预期;若遇到问题,可用
--postgresql-old或FERRETDB_POSTGRESQL_OLD=true临时回退,但应尽快定位并跟进修复,因为回退开关将在下一版本移除; - Docker 部署注意数据目录:镜像默认将 SQLite 数据写入
/state,该目录已是 Docker 卷,重启不会丢数据;若需要自定义位置,可显式指定--state-dir(或FERRETDB_STATE_DIR)并手动挂载对应卷; - 连接串两种注入方式:PostgreSQL 连接既可用
--postgresql-url指定,也可用--postgresql-url-file指向包含连接串的文件(后者优先级更高),适合在容器或密钥管理场景下使用(参考 cmd/ferretdb/main.go); - 查询性能:依赖
_id: <string>精确过滤、以及可下推的过滤/排序/聚合条件的查询,在本次发布后可获得更好的执行效率。
结语
FerretDB v1.13.0 通过"新 PostgreSQL 后端默认启用 + Docker 默认持久化目录 + arm/v7 支持 + 更深的下推优化"这组组合拳,显著降低了用户的上手成本与部署门槛,同时为后续性能与兼容性工作奠定了基础。理解这些变更背后的配置机制(标志与环境变量的双通道、/state 卷约定、下推与统计命令的数据库端实现),有助于在升级 FerretDB 时做出正确的部署决策,也能为阅读当前仓库中 cmd/ferretdb/main.go、internal/handler 与 build/ferretdb 下的源码提供清晰的上下文。