# 欢迎使用 pg_mooncake

> pg_mooncake (v0.3.0) 概览：在 PostgreSQL 内提供实时列存镜像表、Moonlink CDC 逻辑复制摄取、DuckDB 2.0 向量化执行与 Apache Iceberg v2 湖仓表。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

**`pg_mooncake`** 是一款 PostgreSQL 扩展，能够在数据库内部直接提供**实时列存镜像表**（`USING mooncake`）、基于 **DuckDB 2.0** 的向量化分析执行引擎（通过 [`pg_duckdb`](https://pgext.cloud/e/pg_duckdb) 与 [`duckdb_mooncake`](/zh/docs/intro/duckdb-mooncake/)），以及开放的 **Apache Iceberg v2** 湖仓存储（由 [`moonlink`](/zh/docs/intro/moonlink/) 驱动）。

搭载 `pg_mooncake` 的 PostgreSQL 在 ClickBench 分析基准测试中名列前茅，同时完全保留原有的 PostgreSQL 事务写入路径。该扩展套件原由 [Mooncake Labs](https://github.com/Mooncake-Labs) 开发，现由 [PGSTY](https://pigsty.cc/) 社区维护（包含 `pg_mooncake v0.3.0`、`duckdb_mooncake v0.0.2` 与 `moonlink v0.0.1`），全面支持 **PostgreSQL 14–18**。

> [!NOTE] PGSTY 维护的扩展套件（`v0.3.0`）
> - **[`pgsty/pg_mooncake`](https://github.com/pgsty/pg_mooncake)**（`v0.3.0`，`MIT` 许可证）：PostgreSQL 核心扩展，提供 `USING mooncake` 表访问方法、`mooncake.*` SQL 存储过程以及内嵌的 Moonlink 后台工作进程（基于 `pgrx 0.19.3`）。
> - **[`pgsty/moonlink`](https://github.com/pgsty/moonlink)**（`v0.0.1`，`BSL-1.1` 附带 [`pg_mooncake` 链接与分发豁免](/zh/docs/about/license/)）：Rust 实时列存摄取引擎，通过 PostgreSQL 逻辑复制接收 WAL 变更，维护内存 Arrow 写缓冲区、Roaring Bitmap 删除向量以及 Apache Iceberg v2 / Parquet 文件。
> - **[`pgsty/duckdb_mooncake`](https://github.com/pgsty/duckdb_mooncake)**（`v0.0.2`，`MIT` 许可证）：随 `pg_mooncake` 一同打包的 DuckDB 2.0 存储扩展，支持扫描 Moonlink 表并利用多文件 Parquet 统计信息执行高效分段跳过。

## 传统方案的痛点 {#problem}

PostgreSQL 是极其优秀的事务型（OLTP）数据库，但其面向行的堆表存储与逐行执行器并非为大规模分析扫描（OLAP）而设计。长期以来，PostgreSQL 用户往往面临两难选择：

1. **引入外部独立分析引擎（ClickHouse、Snowflake、BigQuery）**
   需要额外部署并维护脆弱的 CDC 数据管道（Debezium + Kafka），被迫重构数据模型，承受最终一致性延迟，且无法在单条 SQL 中直接关联实时业务表与历史分析表。
2. **使用缺乏向量化引擎或高频 CDC 能力的库内列存扩展**
   传统库内列存方案要么缺乏现代向量化执行引擎，要么在面对高频 OLTP `INSERT`、`UPDATE`、`DELETE` 时产生海量微小的 Parquet 文件（小文件风暴），导致读写性能迅速劣化。

![pg_mooncake 定位示意图](/img/mooncake/pg_mooncake_intro.jpg)

## `pg_mooncake` 的解决之道 {#solution}

从 `v0.2` 架构重设计并在 PGSTY 维护的 **`v0.3.0`** 版本中进一步完善，`pg_mooncake` 采用了**实时列存镜像（Columnstore Mirror）**架构：

```sql
-- 1. 启用 pg_mooncake（自动加载依赖的 pg_duckdb 1.2.0）
CREATE EXTENSION IF NOT EXISTS pg_mooncake CASCADE;

-- 2. 现有的 OLTP 行存业务表保持 100% 原样不变
CREATE TABLE trades (
    id BIGINT PRIMARY KEY,
    symbol TEXT,
    price DOUBLE PRECISION,
    volume INT,
    traded_at TIMESTAMPTZ
);

-- 3. 仅需一条命令，创建实时同步的列存镜像表
CALL mooncake.create_table('trades_analytics', 'trades');
```

1. **写入行存表，查询列存表**：业务应用继续向标准的 PostgreSQL `trades` 行存表执行 `INSERT`、`UPDATE`、`DELETE`，享受完整的 ACID 事务与行存索引性能。
2. **基于 Moonlink 的亚秒级逻辑复制**：`pg_mooncake` 后台工作进程将 WAL 变更实时推送至 `moonlink`；最新写入在内存中缓冲为 **Apache Arrow** 列存批次，`UPDATE` 与 `DELETE` 通过 **Roaring Bitmap 删除向量**就地标记，并在后台异步刷盘与合并为 **Parquet** 文件。
3. **DuckDB 2.0 向量化查询与 LSN 屏障**：针对 `trades_analytics` 的分析查询由 `pg_duckdb 1.2.0` 与 `duckdb_mooncake v0.0.2` 接管，在等待目标 WAL LSN 同步屏障后，零拷贝融合扫描内存 Arrow 缓冲与磁盘 Parquet 文件。
4. **开放 Apache Iceberg v2 湖仓表**：执行 `CALL mooncake.create_snapshot('trades_analytics')` 即可在本地磁盘、AWS S3 或 Cloudflare R2 上生成标准 Apache Iceberg v2 元数据快照，无需任何 ETL 即可供 Spark、Snowflake、DuckDB 或 PyIceberg 直接读取。

## 本章内容导航 {#explore}


- [系统架构剖析](/zh/docs/intro/architecture/) — 深入了解 `pg_mooncake`、`pg_duckdb`、`duckdb_mooncake` 与 `moonlink` 如何协同完成写入、查询与 Iceberg 快照生成。
- [Moonlink 实时摄取引擎](/zh/docs/intro/moonlink/) — 深入剖析 Moonlink（`v0.0.1`）的内存 Arrow 写缓冲、删除向量机制，以及独立 HTTP/RPC 服务部署方式。
- [duckdb\_mooncake 与 DuckDB 2\.0](/zh/docs/intro/duckdb-mooncake/) — 了解 `duckdb_mooncake v0.0.2` 如何适配 DuckDB 2.0 与 `pg_duckdb 1.2.0`，实现多文件 Parquet 统计信息剪枝。
- [v0\.1 与 v0\.2 \/ v0\.3 架构演进](/zh/docs/intro/0.1-vs-0.2/) — 对比早期 `v0.1` Delta Lake（`USING columnstore`）架构、`v0.2` Moonlink 镜像架构以及 PGSTY `v0.3.0` 的工程改进。

---

本节页面：

- [系统架构](/zh/docs/intro/architecture/): 深入解析 pg_mooncake (v0.3.0)、pg_duckdb (1.2.0)、duckdb_mooncake (v0.0.2) 与 moonlink (v0.0.1) 如何协同在 PostgreSQL 内实现实时列式分析。
- [Moonlink 实时摄取引擎](/zh/docs/intro/moonlink/): 深入剖析 Moonlink (v0.0.1)：实时 CDC 数据摄取、Arrow 内存写缓冲、Roaring 删除向量、LSN 快照屏障与独立 HTTP/RPC 服务部署。
- [duckdb_mooncake 与 DuckDB 2.0 集成](/zh/docs/intro/duckdb-mooncake/): 解析 duckdb_mooncake (v0.0.2) 如何连接 DuckDB 2.0 与 pg_duckdb 1.2.0 至 Moonlink 表、执行多文件 Parquet 统计剪枝，并通过本地扩展仓库加载。
- [v0.1 与 v0.2 / v0.3 架构演进对比](/zh/docs/intro/0.1-vs-0.2/): 全面对比 pg_mooncake v0.1（USING columnstore + Delta Lake）、v0.2（USING mooncake + Moonlink + Iceberg）与 PGSTY v0.3.0 正式版。

---

反链：

- [ClickBench 基准测试证明：Postgres 是一流的分析型数据库](/zh/blog/post/clickbench-v0.1/)
- [如何让 DuckDB 在 Parquet 文件上的查询性能再上一个台阶](/zh/blog/post/duckdb-parquet/)
- [pg_mooncake：基于列存表与 DuckDB 的 Postgres 极速分析引擎](/zh/blog/post/how-we-built-pgmooncake/)
- [Mooncake 正式加入 Databricks！](/zh/blog/post/mooncake-and-databricks/)
- [Mooncake：下一代搜索与分析系统](/zh/blog/post/mooncake-launch/)
- [pg_mooncake 🤝 Drizzle：用强类型 ORM 驱动分析查询](/zh/blog/post/pgmooncake-drizzle/)
- [pg_mooncake + Neon：PostgreSQL 中的 Serverless 实时分析](/zh/blog/post/pgmooncake-neon/)
- [可是，我的 Postgres（+ 数据湖仓）是免费的呀](/zh/blog/post/postgres-lakehouse-free/)
- [Mooncake 技术白皮书：面向 Apache Iceberg 的实时存储引擎](/zh/blog/post/white-paper/)
- [“在 Postgres 中做分析”究竟意味着什么？](/zh/blog/post/why-postgres-analytics/)
- [pg_mooncake v0.2 架构前瞻：开箱即用的实时列存与逻辑复制](/zh/blog/release/pgmooncake-v02discussion/)
- [Moonlink 引擎](/zh/docs/intro/moonlink/)
- [v0.1 历史归档 (Delta Lake)](/zh/docs/v0.1/)
- [v0.1 架构说明](/zh/docs/v0.1/architecture/)
- [v0.1 数据归档](/zh/docs/v0.1/archiving/)
- [v0.1 对象存储配置](/zh/docs/v0.1/cloud-storage/)
- [v0.1 列存 DDL](/zh/docs/v0.1/columnstore-ddl/)
- [v0.1 元数据与外部查询](/zh/docs/v0.1/columnstore-metadata/)
- [v0.1 配置参数](/zh/docs/v0.1/configurations/)
- [v0.1 快速开始](/zh/docs/v0.1/get-started/)
- [v0.1 Hello World](/zh/docs/v0.1/hello-world/)
- [v0.1 数据导入](/zh/docs/v0.1/load-data/)
- [v0.1 在 Neon 上运行](/zh/docs/v0.1/neon-postgres/)
- [v0.1 操作型分析](/zh/docs/v0.1/operational-analytics/)
- [v0.1 查询外部文件](/zh/docs/v0.1/query-external-files/)
- [v0.1 支持的查询形态](/zh/docs/v0.1/query-shapes/)
- [v0.1 参考总览](/zh/docs/v0.1/reference/)
- [v0.1 数据仓库与 dbt](/zh/docs/v0.1/warehousing/)
- [下载](/zh/download/)