awoooi/docs/runbooks/awooop-partition-retention.md

AwoooP Partition & Retention Runbook

建立：2026-05-04（台北） ADR 依據：ADR-114（channel_event_dedupe）、ADR-119（run_state） 關聯：Phase 1 Task 1.4、Phase 4/7（run_state / mcp_gateway_audit 建立時套用）

---

概覽

表	Partition 策略	Retention	建立 Phase
awooop_channel_event_dedupe	RANGE by created_at（日）	7 天	Phase 1 ✅
awooop_run_state	RANGE by created_at（月）	90 天 hot + 1 年 warm	Phase 4
awooop_mcp_gateway_audit	RANGE by created_at（月）	90 天 hot + 1 年 warm	Phase 5
awooop_agent_audit_log	RANGE by created_at（月）	90 天 hot + 1 年 warm	Phase 7

---

1. awooop_channel_event_dedupe（Phase 1，已完成）

pg_partman 維護（建議）

-- 確認 pg_partman 已安裝
SELECT extname, extversion FROM pg_extension WHERE extname = 'pg_partman';

-- 初始化（若 Phase 1 migration 未自動完成）
SELECT partman.create_parent(
    p_parent_table := 'public.awooop_channel_event_dedupe',
    p_control      := 'created_at',
    p_type         := 'native',
    p_interval     := '1 day',
    p_premake      := 4
);

UPDATE partman.part_config
   SET retention = '7 days',
       retention_keep_table = false
 WHERE parent_table = 'public.awooop_channel_event_dedupe';

pg_partman 定期維護（CronJob，每天 00:00）

# K8s CronJob 或 pg_cron 執行
psql $DATABASE_URL -c "SELECT partman.run_maintenance('public.awooop_channel_event_dedupe');"

手動維護（無 pg_partman）

-- 查看現有 partition
SELECT inhrelid::regclass AS partition_name,
       pg_get_expr(c.relpartbound, c.oid) AS bounds
  FROM pg_inherits i
  JOIN pg_class c ON c.oid = i.inhrelid
 WHERE inhparent = 'awooop_channel_event_dedupe'::regclass
 ORDER BY bounds;

-- 建立下一週 partition（每天執行一次）
DO $$
DECLARE
    d DATE := CURRENT_DATE + 1;
BEGIN
    EXECUTE format(
        'CREATE TABLE IF NOT EXISTS awooop_channel_event_dedupe_%s
         PARTITION OF awooop_channel_event_dedupe
         FOR VALUES FROM (%L) TO (%L)',
        to_char(d, 'YYYYMMDD'),
        d::TIMESTAMPTZ,
        (d + INTERVAL '1 day')::TIMESTAMPTZ
    );
END $$;

-- 刪除 7 天前的 partition（毫秒級，遠優於 DELETE）
DO $$
DECLARE
    old_date DATE := CURRENT_DATE - 8;
    partition_name TEXT := 'awooop_channel_event_dedupe_' || to_char(old_date, 'YYYYMMDD');
BEGIN
    EXECUTE 'DROP TABLE IF EXISTS ' || partition_name;
    RAISE NOTICE 'Dropped partition: %', partition_name;
END $$;

---

2. awooop_run_state（Phase 4 建立時套用）

尚未建立。Phase 4 建立 awooop_run_state 表時使用以下模板。

月份 Partition 建立模板

CREATE TABLE awooop_run_state (
    run_id          UUID NOT NULL DEFAULT gen_random_uuid(),
    project_id      VARCHAR(64) NOT NULL,
    -- ... 其他欄位 ...
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    PRIMARY KEY (run_id, created_at)
) PARTITION BY RANGE (created_at);

-- pg_partman 初始化
SELECT partman.create_parent(
    p_parent_table := 'public.awooop_run_state',
    p_control      := 'created_at',
    p_type         := 'native',
    p_interval     := '1 month',
    p_premake      := 3
);

UPDATE partman.part_config
   SET retention              = '90 days',   -- hot tier: 90 天自動 DROP
       retention_keep_table   = true,         -- warm tier: 保留為 detached table
       retention_schema       = 'warm_archive'-- warm partition 移到此 schema
 WHERE parent_table = 'public.awooop_run_state';

Retention 策略

Tier	資料年齡	存放位置	清理方式
Hot	0~90 天	public.awooop_run_state_*	pg_partman 自動管理
Warm	91 天~1 年	warm_archive.awooop_run_state_*	保留（detach，不 DROP）
Cold	> 1 年	S3 / GCS export（可選）	手動 COPY TO 後 DROP

---

3. awooop_mcp_gateway_audit + awooop_agent_audit_log（Phase 5/7）

與 awooop_run_state 相同策略（月份 partition，90 天 hot + 1 年 warm）。

建立時直接套用同一 pg_partman 模板，替換表名即可。

---

健康檢查

-- 確認各 partition 的資料分佈
SELECT
    child.relname AS partition,
    pg_size_pretty(pg_total_relation_size(child.oid)) AS size,
    (SELECT count(*) FROM ONLY pg_class WHERE oid = child.oid) AS approx_rows
FROM pg_inherits
JOIN pg_class parent ON parent.oid = pg_inherits.inhparent
JOIN pg_class child  ON child.oid  = pg_inherits.inhrelid
WHERE parent.relname = 'awooop_channel_event_dedupe'
ORDER BY child.relname;

-- 確認最舊 partition（應 <= 7 天前）
SELECT min(created_at), max(created_at) FROM awooop_channel_event_dedupe;

---

告警規則（建議加入 Prometheus）

# partition 數量異常（應維持 7 ± 2 個）
- alert: AwoooPDedupPartitionCountAbnormal
  expr: |
    (SELECT count(*) FROM pg_inherits
     WHERE inhparent = 'awooop_channel_event_dedupe'::regclass) NOT BETWEEN 5 AND 10
  labels:
    severity: warning

# pg_partman maintenance 未執行（超過 25 小時）
- alert: AwoooPPartmanMaintenanceStale
  expr: time() - awooop_partman_last_run_timestamp > 90000
  labels:
    severity: warning