跳转到主要内容

pg_mooncake 0.3.0 · PostgreSQL 14–18 · DuckDB 2.0 与 Apache Iceberg v2

实时列存与湖仓引擎为 PostgreSQL 而生

基于 moonlink 逻辑复制 CDC、pg_duckdb 向量化执行引擎与开放 Apache Iceberg v2 存储格式， 为 PostgreSQL 行存表提供亚秒级同步的实时列存镜像表。

Fork 自 Mooncake Labs · 现由 PGSTY 社区维护 · MIT 与 BSL-1.1 链接豁免许可

快速开始 Hello World 架构总览

了解 pg_mooncake 0.3.0 新特性

实时 HTAP 与湖仓一体性能

无需外部 ETL 管道的数据库内列式分析

将 PostgreSQL 事务写入能力与 DuckDB 2.0 向量化执行引擎、开放 Apache Iceberg v2 对象存储无缝融合。

1000× 提速向量化分析扫描基于 DuckDB 2.0 扫描 Parquet 与内存 Arrow 缓冲区，大幅超越传统堆表扫描
< 10 ms亚秒级 CDC 实时同步通过 PostgreSQL 逻辑复制将 INSERT、UPDATE 与 DELETE 实时流入 Moonlink 缓冲区
Iceberg v2开放湖仓表格式将快照导出至 S3、Cloudflare R2 或本地磁盘，供 Spark、Snowflake 与 PyIceberg 直接查询
Zero ETL告别 Kafka 与 Debezium仅需一行 CALL mooncake.create_table() 即可镜像本地或远程 PostgreSQL 表

核心引擎架构

行存承载事务写入，列存加速分析读取

pg_mooncake 将内嵌式 Rust 实时摄取引擎（moonlink）与基于 pg_duckdb / duckdb_mooncake 的 DuckDB 2.0 向量化执行深度结合。

01 / PG_MOONCAKE · 实时列存镜像

一条命令为任意 Postgres 表创建列存镜像

◇ 原生 USING mooncake 表访问方法 + 逻辑复制流

  • 为任意普通堆表或分区表创建基于 USING mooncake 的只读列存镜像表
  • 保持现有 OLTP 业务写入路径 100% 不变，无需触发器或应用层双写
  • 既可镜像当前数据库中的本地表，也可通过 src_uri 复制远程 PostgreSQL 实例

让慢速聚合报表查询瞬间转化为亚秒级向量化扫描。

create_mirror.sql
-- 启用 pg_mooncake（自动加载 pg_duckdb 1.2.0）
CREATE EXTENSION IF NOT EXISTS pg_mooncake CASCADE;
-- 为 orders 行存表创建实时列存镜像
CALL mooncake.create_table('orders_analytics', 'orders');
-- 写入原行存表，从列存镜像表执行聚合分析
INSERT INTO orders (customer_id, amount) VALUES (42, 199.95);
SELECT customer_id, SUM(amount) FROM orders_analytics
  GROUP BY customer_id;

02 / MOONLINK · 实时 CDC 摄取引擎

高效处理更新删除与 LSN 事务一致性

◇ 内嵌 PostgreSQL 后台工作进程与独立 HTTP/RPC 摄取服务

  • 最新写入在内存中缓冲为 Apache Arrow 列存批次，立即可查
  • 通过 Roaring Bitmap 删除向量（Deletion Vectors）高效处理高频 UPDATE 与 DELETE
  • 查询自动等待目标 WAL LSN 屏障，确保分析读取具备强事务一致性

彻底解决传统 Parquet / Iceberg 实时写入产生海量小文件的顽疾。

moonlink_status.sql
-- 查看所有活跃列存镜像表及其 WAL LSN 进度
SELECT * FROM mooncake.list_tables();
-- 返回列: table, commit_lsn, flush_lsn, iceberg_warehouse_location
-- 将内存 Arrow 缓冲区刷盘并生成新的 Iceberg 快照
CALL mooncake.create_snapshot('orders_analytics');
-- 合并 Parquet 文件并重写删除向量
CALL mooncake.optimize_table('orders_analytics', 'full');

03 / DUCKDB_MOONCAKE · 向量化扫描

基于 DuckDB 2.0 与 pg_duckdb 1.2 驱动

◇ 多文件 Parquet 统计信息剪枝 + 零拷贝 Arrow 融合扫描

  • 查询时无缝合并已刷盘的 Parquet 数据文件与内存中的 Arrow 实时缓冲
  • 适配 DuckDB 2.0 多文件 Parquet 统计信息接口，实现高效文件段跳过（Segment Elimination）
  • 支持列存镜像表与常规 PostgreSQL 行存表之间的直接混合 JOIN

通过标准 PostgreSQL 连接直接获得 DuckDB 2.0 的极致分析性能。

hybrid_join.sql
-- 直接关联 PostgreSQL 普通堆表与列存镜像表
SELECT u.region, date_trunc('day', o.created_at) AS day,
       COUNT(*) AS orders, SUM(o.amount) AS revenue
FROM users u
JOIN orders_analytics o ON u.id = o.customer_id
WHERE o.created_at >= NOW() - INTERVAL '30 days'
GROUP BY u.region, day ORDER BY day DESC;

04 / APACHE ICEBERG v2 · 零 ETL 湖仓一体

导出至 S3 / R2 并直接查询外部数据湖

◇ 标准 Iceberg v2 元数据生成 + 外部 Parquet / Delta / Iceberg 直接扫描

  • 自动在本地磁盘、AWS S3 或 Cloudflare R2 上维护标准 Apache Iceberg v2 表元数据
  • 在 PostgreSQL 内直接查询外部 Parquet、CSV、Iceberg、Delta Lake 与 HuggingFace 数据集
  • 冷热分层归档模式：直接 DROP 旧行存分区释放磁盘，列存镜像完整保留全部历史数据

无需维护繁重的外部数据管道，打通业务库与云端数据湖。

iceberg_lakehouse.sql
-- 配置 S3 / R2 凭据与默认存储桶路径
INSERT INTO duckdb.secrets (name, type, key_id, secret, region, scope)
  VALUES ('s3_lake', 'S3', 'AKIA...', 'secret...', 'us-east-1', 's3://my-bucket');
SET mooncake.default_bucket = 's3://my-bucket/warehouse';
-- 在对象存储上物化生成最新 Iceberg v2 快照
CALL mooncake.create_snapshot('orders_analytics');

文档导航

探索完整的 Mooncake 技术文档

统一涵盖 pg_mooncake v0.3.0、Moonlink v0.0.1、duckdb_mooncake v0.0.2、典型架构场景指南以及 v0.1 Delta Lake 历史归档文档。

核心架构 · v0.3.0

简介与核心架构

深入理解 pg_mooncake、Moonlink、duckdb_mooncake 与 pg_duckdb 1.2.0 的读写路径设计，以及从 v0.1 到 v0.2/v0.3 的架构演进。

安装 · Hello World · 限制

快速开始与安装

使用 Pigsty 软件包或从源码在 PostgreSQL 14–18 上构建安装 pg_mooncake，跟随 Hello World 教程上手，并了解当前已知限制。

存储过程 · 查询 · Iceberg

SQL 与配置参考手册

完整涵盖 mooncake.create_table、create_snapshot、optimize_table、list_tables、查询形态、Iceberg S3/R2 配置及外部数据湖查询。

实时分析 · 分区归档 · 湖仓 · 日志

应用场景与架构模式

详解实时操作分析（HTAP）、时间分区大表冷热归档、零 ETL Postgres 湖仓一体以及 OpenTelemetry 日志分析最佳实践。

旧版参考手册

v0.1 历史归档 (Delta Lake)

完整保留 pg_mooncake v0.1 历史技术文档（采用直接 USING columnstore DDL 与 Delta Lake 存储引擎的第一代架构）。

MIT · BSL-1.1 豁免 · 安全审计

关于、许可证与 SBOM

了解 PGSTY 社区接手维护背景、MIT 与 BSL-1.1 链接豁免许可证条款、Wayback Machine 文档恢复来源以及 Cargo 安全审计报告。

快速上手

三步运行 pg_mooncake

通过 Pigsty 安装原生软件包，配置预加载扩展，即可创建你的第一张实时列存镜像表。

  1. 安装扩展软件包

    使用 pig 包管理器在 16 个 Linux 发行版平台与 PostgreSQL 14–18 上一键安装 pg_duckdb 与 pg_mooncake。

    pig repo add pgsql -u && pig install pg_duckdb pg_mooncake

  2. 启用 pg_mooncake 扩展

    设置 wal_level = logical 与 shared_preload_libraries = 'pg_duckdb,pg_mooncake'，重启后创建扩展。

    psql -d postgres -c "CREATE EXTENSION IF NOT EXISTS pg_mooncake CASCADE;"

  3. 创建镜像并实时分析

    调用 mooncake.create_table 为业务行存表创建实时列存镜像，并直接执行向量化分析查询。

    psql -d postgres -c "CALL mooncake.create_table('orders_analytics', 'orders');"

常见问题

了解 Mooncake 扩展套件与 PGSTY 社区维护说明

为什么由 PGSTY 社区维护 pg_mooncake、duckdb_mooncake 与 moonlink？

原开发团队 Mooncake Labs Inc. 被 Databricks 收购后，原官方文档站（docs.mooncake.dev）下线，上游开源仓库亦停止日常维护。 PGSTY（Pigsty） 社区从 Internet Archive Wayback Machine 完整找回并核验了全部 34 个历史文档页面， 并正式维护三个核心开源仓库——pgsty/pg_mooncake、pgsty/duckdb_mooncake 与 pgsty/moonlink——以保障 PostgreSQL 开源生态用户的持续可用性。

PGSTY 发布的 pg_mooncake 0.3.0 版本有哪些核心改进？

pg_mooncake 0.3.0 将 PostgreSQL 扩展升级至 pgrx 0.19.3（全面支持 PostgreSQL 14–18）， 将 duckdb_mooncake（v0.0.2） 适配至 pg_duckdb 1.2.0 与 DuckDB v2.0.0（改用导出的多文件 Parquet 统计信息接口并消除对象缓存互斥锁重入死锁）， 修复了 moonlink（v0.0.1） 在其他表推进数据库 WAL 时导致 create_snapshot(lsn) 挂起超时的问题，自动为现有分区叶子表设置 REPLICA IDENTITY FULL， 并修复了 20 余项 RustSec 依赖安全公告。

pg_mooncake v0.2 / v0.3 与早期的 v0.1 架构有什么区别？

在早期的 v0.1 中，用户直接向基于 Delta Lake 的 CREATE TABLE ... USING columnstore 表写入数据，不适合高频小事务 OLTP 写入与更新。 从 v0.2 与 v0.3.0 起，pg_mooncake 采用由 moonlink 驱动的**实时列存镜像（Columnstore Mirror）**架构： 业务应用继续向标准 PostgreSQL 行存表执行 INSERT、UPDATE、DELETE，而 moonlink 通过逻辑复制实时摄取变更并维护内存 Arrow 缓冲、Roaring 删除向量与 Apache Iceberg v2 Parquet 文件。 详见 v0.1 与 v0.2 / v0.3 架构演进对比。

pg_mooncake、duckdb_mooncake 与 moonlink 分别采用什么开源许可证？

pg_mooncake 与 duckdb_mooncake（以及 moonlink_rpc、moonlink_proto、moonlink_error、moonlink_table_metadata 客户端库） 均采用宽松的 MIT 许可证。核心摄取引擎 moonlink 采用 BSL-1.1 许可证（将于 2029 年 5 月 5 日自动转为 Apache-2.0）， 并附带明确的 PG_MOONCAKE LINKING & DISTRIBUTION EXCEPTION（链接与分发豁免条款），允许在作为 pg_mooncake 一部分嵌入或分发时自由链接、修改与再分发。详见许可证说明。

为什么按旧文档传入 source_uri 调用 mooncake.create_table 会报错？

上游 v0.2 历史文档中存在参数名笔误（写成了 source_uri => ...）。pg_mooncake 源码中的真实存储过程签名为 mooncake.create_table(dst text, src text, src_uri text DEFAULT NULL, table_config json DEFAULT NULL)。当从远程 PostgreSQL URI 复制时，请务必使用 src_uri 参数。详见创建列存表参考。

PGSTY 社区的维护范围与安全漏洞反馈渠道是什么？

PGSTY 社区重点保障开源供应链连续性、PostgreSQL 14–18 与 pg_duckdb 兼容性，以及 16 个 Linux 发行版与架构平台的原生软件包构建， 并在 SBOM 页面完整披露依赖项与安全审计状态。我们不承诺开发上游路线图中的新功能（将视维护精力余量响应）， 但如果您发现任何安全漏洞或严重缺陷，欢迎随时通过 GitHub Issues 提交报告。

准备好在 PostgreSQL 中开启实时列存与湖仓分析了吗？阅读快速开始指南，查阅 SQL 参考手册，或深入了解 v0.3.0 发布说明。

快速开始SQL 参考手册v0.3.0 发布说明