PostgreSQL pg_partman advanced 的核心責任是把 declarative partitioning 的日常維護自動化。pg_partman 可以協助建立未來 partition、管理 retention、執行 maintenance job，讓 time-based 或 serial-based partition 不再依賴人工 DDL。

本文的範圍是 pg_partman 跟 PostgreSQL 原生 partition 的責任分界、pg_partman 的 operation vocabulary、setup pattern、maintenance runbook、既有大表的 migration 與 backfill，以及 failure modes。

Responsibility Boundary

Responsibility boundary 的核心責任是區分 PostgreSQL 原生 partition 和 pg_partman。

pg_partman 的價值在於減少重複 DDL。它不會替 application 選出正確 partition key，也不會自動修復跨 partition query 設計。Partition key、query pattern、retention、index、foreign key 與 migration 這些 partition strategy 的決定，仍要先在 Declarative Partitioning 與 Partition Redesign 做對。

Core Concepts

Core concepts 的核心責任是理解 pg_partman operation vocabulary。

Premake 是防止 insert 打到不存在 partition 的保護。若 partition 建立落後於時間，application insert 會失敗或落到 default partition；production 要對 future partition count 設 alert。

Retention 是資料生命週期操作。Drop 舊 partition 速度快，但要先確認 legal retention、backup、analytics dependency 與 downstream CDC。

Setup Pattern

Setup pattern 的核心責任是把 pg_partman 導入流程放進 migration gate。

1CREATE EXTENSION IF NOT EXISTS pg_partman;
2
3CREATE TABLE events (
4  id bigserial,
5  tenant_id uuid NOT NULL,
6  created_at timestamptz NOT NULL,
7  payload jsonb NOT NULL
8) PARTITION BY RANGE (created_at);

以 pg_partman 5.x 為例，下面這段把上方的 events 交給 pg_partman 管理（4.x 的 create_parent 參數不同，照手上版本的文件寫）：

 1CREATE SCHEMA partman;
 2CREATE EXTENSION pg_partman SCHEMA partman;
 3
 4-- 以 created_at 按日切；premake 7：maintenance 維持今天之後 7 天的 partition 已經建好
 5SELECT partman.create_parent(
 6  p_parent_table := 'public.events',
 7  p_control      := 'created_at',
 8  p_interval     := '1 day',
 9  p_premake      := 7
10);
11
12-- retention：超過 90 天的 partition 由 maintenance drop 掉（retention_keep_table = false 表示不保留成獨立 table）
13UPDATE partman.part_config
14SET retention = '90 days', retention_keep_table = false
15WHERE parent_table = 'public.events';
16
17-- maintenance：補建未來 partition、執行 retention；scheduler 定期呼叫的就是這一行
18CALL partman.run_maintenance_proc();
19-- 跑完之後 events 底下有 events_default 與今天前後各 7 天的 events_pYYYYMMDD，共 16 個 child
20-- created_at 落在已建 partition 之外（例：30 天後）的列進 events_default

Managed PostgreSQL 可能限制 extension version、background worker 或 scheduler，因此 setup 前要先確認 provider boundary。

最小 setup evidence：

1. Extension version。
2. Parent table DDL。
3. Partition key 與 interval。
4. Premake 數量。
5. Retention policy。
6. Maintenance job schedule。
7. Test insert 到 current / future partition。

Maintenance Runbook

Maintenance runbook 的核心責任是讓 partition lifecycle 可觀測。

Maintenance job 要有 owner。Cron、pg_cron、background worker、Kubernetes job 或 managed scheduler 都可以；重點是 job failure 會告警，並且有人處理。

Migration and Backfill

Migration and backfill 的核心責任是把既有大表轉成 partman-managed partition。這通常比新表導入更高風險。

Backfill 要控制 WAL、replica lag、autovacuum、index bloat 與 lock。大型 table 應先用 shadow table 或 partition redesign playbook，避開 peak traffic 直接重建。

Failure Modes

Failure modes 的核心責任是列出 pg_partman 常見事故。

pg_partman 事故通常是 lifecycle 事故。Runbook 要先看 maintenance job，再看 partition metadata 與 application query。

下一步路由

pg_partman advanced 完成後，partition 設計讀 Declarative Partitioning；重排策略讀 Partition Redesign；migration gate 讀 Online Schema Change。