PostgreSQL / 系统课时
搭建可复现迁移实验环境
搭建可复现迁移实验环境
低停机迁移要反复演练“建环境、做初始同步、制造增量、验证一致性、彻底清理”这一完整闭环。本课用两个独立 PostgreSQL 容器搭建最小实验场,确保每次都能从干净状态重建并复现逻辑复制行为。
学习目标
- 启动相互独立的源库与目标库,并在源库开启逻辑复制所需参数
- 创建测试表、发布与订阅,验证初始复制和后续增量同步
- 用固定清理命令删除数据卷,保证下一轮实验从零开始
明确实验边界
实验只模拟一条最小迁移链路:源库 appdb 中的 orders 表发布到目标库同名表。源库负责 WAL 与 publication,目标库负责 subscription;表结构不会被逻辑复制自动创建,因此两端要先准备兼容 schema。

这个环境用于本机实验,不等同于生产安全配置。生产迁移还应叠加 TLS、精确的 pg_hba.conf、密钥管理、监控与容量评估。
启动两个 PostgreSQL 实例
新建 compose.yaml。示例使用 PostgreSQL 17 镜像,并显式给源库设置 wal_level=logical、复制槽数量和 WAL sender 数量。把 <PASSWORD> 替换为实验密码。
services:
source:
image: postgres:17
container_name: pg-logical-source
environment:
POSTGRES_DB: appdb
POSTGRES_PASSWORD: "<PASSWORD>"
command:
- postgres
- -c
- wal_level=logical
- -c
- max_replication_slots=10
- -c
- max_wal_senders=10
ports:
- "5433:5432"
volumes:
- source-data:/var/lib/postgresql/data
target:
image: postgres:17
container_name: pg-logical-target
environment:
POSTGRES_DB: appdb
POSTGRES_PASSWORD: "<PASSWORD>"
ports:
- "5434:5432"
volumes:
- target-data:/var/lib/postgresql/data
volumes:
source-data:
target-data:该配置生效后,源库具备创建逻辑复制槽的条件;目标库保持普通 PostgreSQL 实例。可用下面命令启动并确认容器状态。
docker compose up -d
docker compose ps预期结果
pg-logical-source 和 pg-logical-target 均为 running 状态;
宿主机端口 5433 与 5434 可分别连接源库和目标库。初始化表、发布与订阅
下面的 Bash 示例会在源库创建测试表与两条数据,再创建专用复制账号和 publication;随后在目标库创建同构表并建立 subscription。逻辑复制不负责 DDL,因此目标表必须先存在。
docker exec -i pg-logical-source psql -U postgres -d appdb <<'SQL'
CREATE TABLE public.orders (
id bigint PRIMARY KEY,
status text NOT NULL,
amount numeric(12,2) NOT NULL
);
INSERT INTO public.orders (id, status, amount)
VALUES
(1, 'new', 100.00),
(2, 'new', 250.00);
CREATE ROLE repl_lab
WITH LOGIN REPLICATION PASSWORD '<PASSWORD>';
GRANT CONNECT ON DATABASE appdb TO repl_lab;
GRANT USAGE ON SCHEMA public TO repl_lab;
GRANT SELECT ON TABLE public.orders TO repl_lab;
CREATE PUBLICATION migration_pub
FOR TABLE public.orders;
SQL
docker exec -i pg-logical-target psql -U postgres -d appdb <<'SQL'
CREATE TABLE public.orders (
id bigint PRIMARY KEY,
status text NOT NULL,
amount numeric(12,2) NOT NULL
);
CREATE SUBSCRIPTION migration_sub
CONNECTION 'host=source port=5432 dbname=appdb user=repl_lab password=<PASSWORD>'
PUBLICATION migration_pub;
SQL预期输出
CREATE TABLE
INSERT 0 2
CREATE ROLE
GRANT
GRANT
GRANT
CREATE PUBLICATION
CREATE TABLE
CREATE SUBSCRIPTIONCREATE SUBSCRIPTION 成功只说明订阅对象已经建立,初始复制仍是异步过程,因此后续验收不能依赖“命令返回成功”这一点。
验证初始复制与增量同步
为了同时验证初始数据和持续复制,先在源库更新一行并插入一行,再轮询目标库直到出现期望状态。这样可以避免用固定 sleep 猜同步时间。
docker exec pg-logical-source psql -U postgres -d appdb -c "UPDATE public.orders SET status = 'paid' WHERE id = 1; INSERT INTO public.orders (id, status, amount) VALUES (3, 'new', 80.00);"
for i in {1..20}; do
result="$(docker exec pg-logical-target psql -U postgres -d appdb -Atc "SELECT string_agg(id || ':' || status, ',' ORDER BY id) FROM public.orders;")"
if [[ "$result" == "1:paid,2:new,3:new" ]]; then
echo "$result"
exit 0
fi
sleep 1
done
echo "replication did not converge"
exit 1预期输出
UPDATE 1
INSERT 0 1
1:paid,2:new,3:new如果最终仍未收敛,可在目标库查询 pg_stat_subscription,再到源库检查 replication slot 与发布表权限。优先判断订阅 worker 是否在线,再判断是连接、权限还是表结构不兼容。
清理并重新开始
可复现实验的关键是清理时同时删除持久化数据卷,否则下一轮会残留 publication、subscription、复制槽和旧表数据。下面命令会停止容器并删除本实验声明的 named volumes。
docker compose down -v预期结果
两个实验容器被停止并删除,source-data 与 target-data 数据卷被删除。再次执行 docker compose up -d,并重新运行初始化脚本,就会得到一套全新的源库与目标库。每次迁移演练都从相同初始状态开始,才能可靠比较参数调整、故障注入和切换步骤带来的差异。