pg_rewrite

概览

PIGSTY RPM and PGDG DEB are aligned at 2.2 for PostgreSQL 14-18; shared_preload_libraries=pg_rewrite and wal_level=logical are required.

版本

构建

您可以使用 pig build 命令构建 pg_rewrite 扩展的 RPM 包：

pig build pkg pg_rewrite         # 构建 RPM 包

安装

您可以直接安装 pg_rewrite 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：

pig repo add pgsql -u          # 添加仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展：

• 安装
• pig
• dnf
• apt

pig install pg_rewrite;          # 当前活跃 PG 版本安装

pig ext install -y pg_rewrite -v 18  # PG 18
pig ext install -y pg_rewrite -v 17  # PG 17
pig ext install -y pg_rewrite -v 16  # PG 16
pig ext install -y pg_rewrite -v 15  # PG 15
pig ext install -y pg_rewrite -v 14  # PG 14

dnf install -y pg_rewrite_18       # PG 18
dnf install -y pg_rewrite_17       # PG 17
dnf install -y pg_rewrite_16       # PG 16
dnf install -y pg_rewrite_15       # PG 15
dnf install -y pg_rewrite_14       # PG 14

apt install -y postgresql-18-pg-rewrite   # PG 18
apt install -y postgresql-17-pg-rewrite   # PG 17
apt install -y postgresql-16-pg-rewrite   # PG 16
apt install -y postgresql-15-pg-rewrite   # PG 15
apt install -y postgresql-14-pg-rewrite   # PG 14

预加载配置：

shared_preload_libraries = 'pg_rewrite';

创建扩展：

CREATE EXTENSION pg_rewrite;

用法

pg_rewrite: 允许在表重写期间继续读写的工具

pg_rewrite 需要设置 wal_level = logical，并且必须添加到 shared_preload_libraries 中。常见用例包括更改列数据类型、分区表、重新排列列以及将表移动到不同的表空间——同时允许并发读写。

重写表

创建具有目标架构的目标表，然后调用 rewrite_table()：

-- 源表
CREATE TABLE measurement (id int, city_id int NOT NULL, logdate date NOT NULL, peaktemp int, PRIMARY KEY(id, logdate));

-- 具有新模式的目标表（例如 bigint id + 分区）
CREATE TABLE measurement_aux (id bigint, city_id int NOT NULL, logdate date NOT NULL, peaktemp int, PRIMARY KEY(id, logdate))
  PARTITION BY RANGE (logdate);

CREATE TABLE measurement_y2006m02 PARTITION OF measurement_aux FOR VALUES FROM ('2006-02-01') TO ('2006-03-01');

-- 执行重写（复制数据、应用并发变更，然后重命名）
SELECT rewrite_table('measurement', 'measurement_aux', 'measurement_old');

源表和目标表都必须有一个标识索引（通常是主键）。该函数会复制所有行，通过逻辑解码重放并发变更，然后原子性地重命名表。

进度监控

SELECT * FROM pg_rewrite_progress;

显示 ins_initial（初始复制的行数）、ins、upd、del（应用的并发变更）。

配置

• rewrite.max_xlock_time – 最终重命名阶段持有排他锁的最大时间（毫秒）。默认 0（不限制）。设置为例如 100 可将锁定时间限制在 0.1 秒；超出时函数会重试。

SET rewrite.max_xlock_time TO 100;

约束处理

• PRIMARY KEY、UNIQUE、EXCLUDE：在调用 rewrite_table() 之前添加到目标表
• CHECK、NOT NULL（PG18+）、FOREIGN KEY：自动创建为 NOT VALID；使用 ALTER TABLE ... VALIDATE CONSTRAINT ... 验证