FerretDB v1.13.0 新 PostgreSQL 后端:默认启用、Docker 数据目录与 pushdown 增强解读

原创2026-09-23 13:52:251,602 阅读
文章标签:数据库后端API网关

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 带来了什么

本次发布的核心变更可以归纳为四点:

  1. 新 PostgreSQL 后端正式默认启用,旧后端可通过 --postgresql-old 标志或 FERRETDB_POSTGRESQL_OLD=true 环境变量临时回退,但该回退开关将在下一个版本移除;
  2. Docker 镜像的 SQLite 默认数据目录改为 /state,该目录同时声明为 Docker 卷(volume),容器重启后数据默认得以保留;
  3. 新增 linux/arm/v7 支持,覆盖二进制、Docker 镜像以及 .deb/.rpm 软件包;
  4. 性能与兼容性增强: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 等统计命令"的描述,也说明统计类命令最终是在 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(或参考其配置模式部署新版本)时有几点实践建议:

  1. 新后端默认启用,先做兼容性验证:升级后先运行常规读写、查询与聚合用例,确认业务行为符合预期;若遇到问题,可用 --postgresql-old 或 FERRETDB_POSTGRESQL_OLD=true 临时回退,但应尽快定位并跟进修复,因为回退开关将在下一版本移除;
  2. Docker 部署注意数据目录:镜像默认将 SQLite 数据写入 /state,该目录已是 Docker 卷,重启不会丢数据;若需要自定义位置,可显式指定 --state-dir(或 FERRETDB_STATE_DIR)并手动挂载对应卷;
  3. 连接串两种注入方式:PostgreSQL 连接既可用 --postgresql-url 指定,也可用 --postgresql-url-file 指向包含连接串的文件(后者优先级更高),适合在容器或密钥管理场景下使用(参考 cmd/ferretdb/main.go);
  4. 查询性能:依赖 _id: <string> 精确过滤、以及可下推的过滤/排序/聚合条件的查询,在本次发布后可获得更好的执行效率。

结语

FerretDB v1.13.0 通过"新 PostgreSQL 后端默认启用 + Docker 默认持久化目录 + arm/v7 支持 + 更深的下推优化"这组组合拳,显著降低了用户的上手成本与部署门槛,同时为后续性能与兼容性工作奠定了基础。理解这些变更背后的配置机制(标志与环境变量的双通道、/state 卷约定、下推与统计命令的数据库端实现),有助于在升级 FerretDB 时做出正确的部署决策,也能为阅读当前仓库中 cmd/ferretdb/main.go、internal/handler 与 build/ferretdb 下的源码提供清晰的上下文。

登录后查看全文
FerretDB