# v0.1 与 v0.2 / v0.3 架构演进对比

> 全面对比 pg_mooncake v0.1（USING columnstore + Delta Lake）、v0.2（USING mooncake + Moonlink + Iceberg）与 PGSTY v0.3.0 正式版。

---

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

---

`pg_mooncake` 的技术架构经历了三个关键演进阶段：

1. **`v0.1`（早期 Delta Lake 架构）**：引入直接通过 `CREATE TABLE ... USING columnstore` 创建的列存表，底层基于 Delta Lake 与早期 `pg_duckdb` 实现读写。
2. **`v0.2`（Moonlink 与 Apache Iceberg 架构重设计）**：废弃对列存表的直接写入，改用由 [`moonlink`](/zh/docs/intro/moonlink/) 逻辑复制驱动的**实时列存镜像（Columnstore Mirror）**架构（`CALL mooncake.create_table(dst, src)` + `USING mooncake`），引入内存 Arrow 写缓冲、Roaring 删除向量与 Apache Iceberg v2 元数据。
3. **`v0.3.0`（PGSTY 社区维护正式版）**：将 `pg_mooncake` 升级至 `pgrx 0.19.3`（全面支持 PostgreSQL 14–18），将 [`duckdb_mooncake v0.0.2`](/zh/docs/intro/duckdb-mooncake/) 移植适配至 `pg_duckdb 1.2.0` 与 **DuckDB `v2.0.0`**，修复了 Moonlink（`v0.0.1`）在无关表推进 WAL 时的快照挂起问题与分区表复制标识设置，并修复了 20 余项 RustSec 依赖安全漏洞。

> [!TIP] 寻找 `v0.1` 历史版本文档？
> 早期 `v0.1` 版本（`USING columnstore`、`mooncake.create_secret`、`mooncake.columnstore_tables`、`mooncake.read_parquet`）的完整文档已归档保留在 [v0.1 历史文档 (Delta Lake)](/zh/docs/v0.1/) 中。

## 核心架构对比表 {#comparison}

| 特性维度 | `v0.1`（早期版本） | `v0.2`（Moonlink 重构版） | `v0.3.0`（当前 PGSTY 正式版） |
|:---|:---|:---|:---|
| **列存表创建方式** | `CREATE TABLE t (...) USING columnstore;` | `CALL mooncake.create_table(dst, src);` | `CALL mooncake.create_table(dst, src, src_uri, table_config);` |
| **表访问方法 (TAM)** | `USING columnstore` | `USING mooncake`（只读镜像表） | `USING mooncake`（只读镜像表） |
| **写入路径设计** | 直接向列存表执行 DML（每笔事务生成 1 个 Parquet 文件） | 写入标准 Postgres 行存表，通过 `moonlink` 逻辑复制实时同步 | 写入普通堆表或分区表，通过 `moonlink v0.0.1` 逻辑复制实时同步 |
| **高频小写入与更新处理** | 高频小事务下产生大量小文件，更新需重写文件 | 亚秒级内存 Arrow 写缓冲 + Roaring Bitmap 删除向量 | 亚秒级 Arrow 写缓冲 + 删除向量 + 非阻塞 LSN 快照屏障 |
| **开放湖仓格式** | Delta Lake（`mooncake.columnstore_tables`） | Apache Iceberg v2（`mooncake.list_tables()`） | Apache Iceberg v2（`mooncake.list_tables()`） |
| **DuckDB 执行引擎** | DuckDB 1.1 / `pg_duckdb 0.2` | DuckDB 1.3 / `pg_duckdb` | **DuckDB `v2.0.0`** / **`pg_duckdb 1.2.0`**（`duckdb_mooncake v0.0.2`） |
| **PostgreSQL 版本支持** | PostgreSQL 14–17（`pgrx 0.12`） | PostgreSQL 14–17（`pgrx 0.16.1`） | **PostgreSQL 14–18**（`pgrx 0.19.3`） |
| **分区源表支持** | 不支持 | 支持（需手动为子分区设置复制标识） | 创建镜像时自动为所有现有叶子分区设置 `REPLICA IDENTITY FULL` |
{.wide .expand}

## 为什么 `v0.2` / `v0.3` 放弃了 `v0.1` 的直接写入模型？ {#why-v02}

### `v0.1` 直接写入模型的局限性

在 `v0.1` 中，直接向 `USING columnstore` 表写入数据虽然在大批量导入（单事务 `100,000`–`1,000,000` 行）时表现良好，但在真实的在线 PostgreSQL 业务负载中存在明显瓶颈：

- **不支持索引与约束**：无法在 `USING columnstore` 表上创建主键、唯一约束、外键或 B-Tree 索引。
- **小文件写放大**：每一笔 `INSERT` 或 `UPDATE` 事务都会生成一个新的 Parquet 文件，在高频 OLTP 流量下会导致文件碎片激增、查询性能快速下降。
- **DuckDB 写入路径耦合**：在 PostgreSQL 事务执行器内部通过 DuckDB 执行写入，带来了较高的内存开销与事务状态管理复杂度。

### `v0.2` 与 `v0.3.0` 如何解决这些问题

通过将 OLTP 写入路径（标准 PostgreSQL 行存表）与分析存储计算路径（`moonlink` + `pg_duckdb 1.2.0` + `duckdb_mooncake v0.0.2`）彻底解耦：

1. **对在线 OLTP 业务零侵入**：源业务表完整保留 PostgreSQL 的全部能力——主键、外键、B-Tree/GIN/vchord 索引、触发器与行级并发锁。
2. **高吞吐增量变更摄取**：`moonlink` 利用内存 Arrow 写缓冲与 Roaring 删除向量高效吸收高频 `INSERT`、`UPDATE`、`DELETE` 变更流，并在后台异步刷写与合并优化后的 Parquet 文件。
3. **自动同步表结构变更**：在源行存表上执行 `ALTER TABLE ... ADD COLUMN` 与 `DROP COLUMN` 会自动同步至列存镜像表。
4. **支持远程实例复制（`src_uri`）**：你甚至可以在专门的分析型 PostgreSQL 实例上部署 `pg_mooncake`，通过 `src_uri => 'postgresql://...'` 实时镜像远程生产数据库（包括 AWS RDS、Aurora、Supabase 或 Neon）中的业务表。

---

反链：

- [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/)