PostgreSQL 数据库迁移完全指南：从 A 服务器到 B 服务器

在数据库运维中，将生产或测试数据从一台服务器迁移到另一台服务器是极其常见的操作。无论是因为硬件升级、机房迁移、灾备演练，还是为了合并数据库实例，掌握一套稳定、高效的 PostgreSQL 迁移方法论，是每一位后端工程师和 DBA 的必备技能。

本文将系统性地阐述 将 A 服务器上的数据库 x 复制到 B 服务器上的数据库 y 的多种实现方案，涵盖逻辑备份、物理复制、流式管道及自动化工具，并深入对比各方案的适用场景、性能优劣及风险点，帮助你根据实际环境做出最佳决策。

1. 迁移前的必要准备

在任何迁移操作开始之前，请务必完成以下检查项，否则可能导致数据不一致或恢复失败：

• 版本兼容性：目标端 PostgreSQL 的主版本号（Major Version） 必须 ≥ 源端。例如，从 PostgreSQL 12 迁移到 16 是安全的，反之则可能因系统表结构差异导致失败。可使用 pg_ctl --version 或 SELECT version(); 确认。
• 扩展模块检查：若源库使用了 postgis、pgvector、pgcrypto 等扩展，请在目标库中预先 CREATE EXTENSION IF NOT EXISTS ...，否则恢复时会报错“类型不存在”。
• 用户权限：执行导出操作的用户需要具备源数据库的 CONNECT 和 SELECT 权限，对于表空间、触发器等对象可能需要 SUPERUSER。目标端恢复用户需要 CREATEDB 权限。
• 网络与防火墙：若采用跨主机管道传输，确保两端防火墙开放 PostgreSQL 端口（默认 5432），且 SSH 或直接 TCP 可达。
• 停机窗口与一致性：若数据库在迁移过程中有写入操作，请根据业务允许的停机时间选择合适的策略。若无法停机，需考虑逻辑复制或第三方增量同步工具。

2. 方案概览与选型矩阵

决策树建议：

• 若源端和目标端版本不同 → 只能选 逻辑备份方案（方案一、二、四）。
• 若你只需要迁移单个数据库，且总大小 < 500GB → 首选 pg_dump + pg_restore（方案一）。
• 若整个实例数据量极大（几 TB），且两端版本、架构一致，且允许短暂停机 → 首选 pg_basebackup（方案三）。
• 若希望最小化停机时间，并追求自动化 → 考虑 pgcopydb（方案四）。

3. 方案一：pg_dump + pg_restore（通用逻辑备份法）

这是生产环境中最成熟、最通用的方案。pg_dump 会生成一个数据库的逻辑快照，导出为自定义格式（-Fc），该格式支持压缩和并行恢复。

步骤 1：在 A 服务器导出数据库 x

pg_dump -U postgres -h localhost -p 5432 -Fc -f /tmp/x_backup.dump x

• -Fc：自定义格式（Custom），压缩率高，且支持 pg_restore 的并行恢复。
• 若数据库较大，可添加 -j 参数加快导出（但需注意 CPU 和 I/O），但 pg_dump 的并行导出要求表被分区或使用多个表，实际收益有限，通常不配置。

步骤 2：传输备份文件至 B 服务器

推荐使用 rsync 或 scp，支持断点续传（大文件时使用 rsync -P）。

scp /tmp/x_backup.dump user@B_IP:/tmp/

步骤 3：在 B 服务器创建空数据库 y

CREATE DATABASE y OWNER your_user;

步骤 4：在 B 服务器恢复数据至 y

pg_restore -U postgres -h localhost -p 5432 -d y -j 4 /tmp/x_backup.dump

• -j 4：使用 4 个并行进程恢复，可大幅缩短时间，但需根据 CPU 核心数和磁盘 I/O 合理调整。
• 恢复后，可执行 ANALYZE 更新统计信息。

优点：灵活、跨版本、可精细控制（可选择性恢复指定表）。
缺点：导出和恢复过程需要两次磁盘 I/O（生成文件 + 传输），且大库下时间较长。

4. 方案二：直接管道流式传输（无中间文件）

若网络带宽足够且两端网络延迟较低，可以省去中间备份文件的步骤，直接通过管道将 pg_dump 的输出实时导入到目标端 psql。

在 A 服务器执行：

pg_dump -U postgres -h localhost x | psql -U postgres -h B_IP -p 5432 -d y

原理：pg_dump 输出的是标准 SQL 文本（默认格式），通过管道传输到 psql 执行。

优点：无需额外磁盘空间，操作简便。
缺点：网络中断将导致恢复失败，且无法利用并行恢复，对大表可能非常缓慢；另外，若导出过程中源端有 DDL 变更，可能导致不一致（建议在业务低峰期或只读模式下执行）。

5. 方案三：pg_basebackup（物理全量复制）

pg_basebackup 是 PostgreSQL 自带的物理备份工具，它通过流复制协议将整个数据库集群（所有数据库）的物理文件完整复制到目标服务器。这类似于“克隆”整个实例，适合大规模迁移，且速度远超逻辑导出。

适用前提

• 源端与目标端 PostgreSQL 主版本完全相同（如 16.x → 16.y）。
• 目标端的数据目录（$PGDATA）必须为空。
• 源端需启用 wal_level = replica 或 logical，且 max_wal_senders 至少为 1。

操作步骤

1. 在 B 服务器停止 PostgreSQL 服务

   Copy

   systemctl stop postgresql
   

2. 清空 B 服务器的数据目录（谨慎操作！）

   Copy

   rm -rf /var/lib/postgresql/data/*
   

3. 从 A 服务器拉取数据
   在 B 服务器上执行：

   Copy

   pg_basebackup -h A_IP -U replication_user -D /var/lib/postgresql/data -P -v -R
   

   • -R：生成 standby.signal 和 postgresql.auto.conf，使得恢复后的实例可直接作为 A 的备用库（若不需要，可去掉）。
   • -P：显示进度。

4. 调整目标端配置（若作为独立主库）
   编辑 postgresql.conf 中与复制相关的参数，或删除 standby.signal 文件以启动为主库。

5. 启动 B 服务器 PostgreSQL

   Copy

   systemctl start postgresql
   

优点：极快的速度（直接复制文件），特别适合超大数据库（数 TB）。
缺点：

• 只能复制整个实例，无法选择单个数据库。
• 目标端必须清空，且版本必须严格一致。
• 需要额外的复制用户权限。

6. 方案四：pgcopydb（现代化并行迁移工具）

pgcopydb 是微软开源的 PostgreSQL 数据库迁移工具，它利用逻辑解码（Logical Decoding）和多个工作进程并行地复制数据，同时支持在线迁移（源端可写入）和断点续传。

安装

# 使用包管理器（如 apt、yum）或从源码编译
curl -L https://github.com/dimitri/pgcopydb/releases/latest/download/pgcopydb.tar.gz | tar xz
sudo mv pgcopydb /usr/local/bin/

迁移命令

pgcopydb clone \
  --source "postgresql://user:pass@A_IP:5432/x" \
  --target "postgresql://user:pass@B_IP:5432/y"

高级特性：

• 支持表分片并行复制，大幅提升速度。
• 支持通过 --resume 断点续传。
• 自动处理外键约束、序列、触发器等的迁移顺序。

优点：速度快、自动化程度高、支持在线迁移。
缺点：需要额外安装工具，且依赖逻辑复制（需源端 wal_level=logical）。

7. 迁移后的验证与收尾工作

无论采用哪种方案，迁移完成后必须执行以下验证步骤，确保数据一致性：

1. 行数验证：对关键表执行 SELECT COUNT(*)，对比源端和目标端。
2. 抽样校验：对部分表进行 MD5 哈希校验，例如使用 pg_checksums 或自写脚本。
3. 索引与约束检查：确认所有索引、主键、外键、触发器均成功创建。可通过 pg_dump -s 仅导出结构进行对比。
4. 统计信息更新：执行 ANALYZE 或 VACUUM ANALYZE 以更新优化器统计信息。
5. 业务测试：使用应用程序连接目标库，执行典型的 CRUD 操作，确认功能正常。

若迁移后需要切换业务流量，请务必规划好 DNS 或连接字符串的切换策略，并保留源端一段时间作为回滚预案。

8. 常见问题与排障

• 恢复时报错 “role does not exist”：因为 pg_dump 默认不导出角色定义（pg_authid），需先在目标端创建相同的角色，或使用 pg_dumpall -g 导出全局角色。
• 恢复时报错 “extension … already exists”：说明目标端已存在同名扩展，可考虑 CREATE EXTENSION IF NOT EXISTS 或恢复时使用 --no-extensions 跳过。
• 网络传输中断：使用 scp 或 rsync 时可搭配 --partial 续传；使用管道时若中断只能重来，建议使用 pv 监控进度。
• 内存不足导致 OOM：若恢复时 work_mem 设置过高，可降低该参数或减少并行度 -j。

9. 总结与推荐

在大多数生产环境中，pg_dump + pg_restore 的组合凭借其稳定性、跨版本兼容性和灵活的并行恢复能力，始终是首选方案。而对于超大规模数据库，物理复制方案则不可替代。

无论选择何种方式，请务必先在测试环境中完整演练，并备份源数据——谨慎总比后悔好。

延伸阅读：

• PostgreSQL 官方文档 - 备份与恢复
• pgcopydb GitHub 仓库