Hello World 快速上手教程

手把手教程：创建 PostgreSQL 行存表，通过 mooncake.create_table 创建实时列存镜像表，并执行增删改、回滚与跨表关联分析查询。

本教程将带你体验 pg_mooncake 的核心操作流程：创建标准的 PostgreSQL 行存表，创建实时同步的列存镜像表（USING mooncake），执行事务级 INSERT、UPDATE、DELETE 与 ROLLBACK，以及在列存镜像表与常规行存表之间执行混合 JOIN 查询。

1. 启用扩展

连接目标 PostgreSQL 数据库，确保已启用 pg_mooncake（及依赖的 pg_duckdb）：

CREATE EXTENSION IF NOT EXISTS pg_mooncake CASCADE;

2. 创建行存表与实时列存镜像表

首先创建一张标准的 PostgreSQL 行存表（user_activity）用于承载业务写入，随后调用 mooncake.create_table 创建它的实时列存镜像表（user_activity_columnstore）：

-- 1. 创建标准的 PostgreSQL 行存（堆）表
CREATE TABLE user_activity (
    user_id BIGINT PRIMARY KEY,
    activity_type TEXT,
    activity_timestamp TIMESTAMP,
    duration INT
);

-- 2. 为 user_activity 创建实时列存镜像表
CALL mooncake.create_table('user_activity_columnstore', 'user_activity');

在后台，mooncake.create_table 会自动创建 user_activity_columnstore USING mooncake 表，为 user_activity 建立逻辑复制槽，并将表元数据注册到 moonlink 引擎中。

3. 执行插入、更新与删除操作

所有写操作（INSERT、UPDATE、DELETE）均针对原始行存表（user_activity）执行，而分析型 SELECT 查询则针对列存镜像表（user_activity_columnstore）执行：

-- 向行存表插入数据
INSERT INTO user_activity VALUES
    (1, 'login', '2024-01-01 08:00:00', 120),
    (2, 'page_view', '2024-01-01 08:05:00', 30),
    (3, 'logout', '2024-01-01 08:30:00', 60),
    (4, 'error', '2024-01-01 08:13:00', 60);

-- 在行存表上更新一行
UPDATE user_activity SET duration = 180 WHERE user_id = 1;

-- 从行存表中删除一行
DELETE FROM user_activity WHERE user_id = 2;

-- 查询列存镜像表（会自动等待最新 WAL LSN 同步完成）
SELECT * FROM user_activity_columnstore ORDER BY user_id;

查询输出：

 user_id | activity_type | activity_timestamp  | duration
---------+---------------+---------------------+----------
       1 | login         | 2024-01-01 08:00:00 |      180
       3 | logout        | 2024-01-01 08:30:00 |       60
       4 | error         | 2024-01-01 08:13:00 |       60
(3 rows)

4. 事务一致性与回滚验证

Moonlink 仅从逻辑复制流中摄取已提交的 PostgreSQL 事务；未提交或已回滚（ROLLBACK）的事务绝不会出现在列存镜像表中：

BEGIN;
INSERT INTO user_activity VALUES
    (5, 'login', '2024-01-02 10:00:00', 200),
    (6, 'login', '2024-01-02 10:30:00', 90);
ROLLBACK;

-- 已回滚的行（user_id 5 和 6）不会出现在查询结果中
SELECT * FROM user_activity_columnstore ORDER BY user_id;

5. 列存表与行存表混合关联（JOIN）

你可以在两张列存镜像表之间执行关联查询，也可以在单条 SQL 中将 USING mooncake 列存镜像表与常规 PostgreSQL 行存表直接 JOIN：

-- 两张列存表之间的关联查询
SELECT ua.user_id, ua.activity_type, ua.duration
FROM user_activity_columnstore ua
JOIN user_activity_columnstore ua2 ON ua.user_id = ua2.user_id;

-- 创建一张常规 PostgreSQL 行存表存储用户信息
CREATE TABLE users (
    user_id BIGINT PRIMARY KEY,
    username TEXT,
    tier TEXT
);

INSERT INTO users VALUES
    (1, 'alice', 'enterprise'),
    (3, 'bob', 'pro'),
    (4, 'charlie', 'free');

-- 直接关联 PostgreSQL 行存表与列存镜像表
SELECT u.username, u.tier, ua.activity_type, ua.duration
FROM users u
JOIN user_activity_columnstore ua ON u.user_id = ua.user_id
ORDER BY u.user_id;

6. 查看复制状态并生成 Iceberg 快照

通过 mooncake.list_tables() 查看当前的提交 LSN、刷盘 LSN 及 Iceberg 仓库目录，或调用 mooncake.create_snapshot 将内存 Arrow 写缓冲区强制刷盘并生成新的 Apache Iceberg v2 快照：

-- 查看复制 LSN 进度与 Iceberg 仓库路径
SELECT * FROM mooncake.list_tables();

-- 将内存 Arrow 缓冲刷写为新的 Apache Iceberg v2 快照
CALL mooncake.create_snapshot('user_activity_columnstore');