PostgreSQL 跨版本数据迁移：解决「unsupported version in file header」报错全记录

Qin Yang
阅读量:
目录

关键字

PostgreSQL、pg_restore、版本兼容性、数据库迁移、pg_dump、备份恢复、unsupported version in file header

背景环境

系统配置

环境类型 操作系统 PostgreSQL 版本 内存 工具链
测试环境 Windows 11 16 16GB Navicat/PgAdmin
生产环境 Windows Server 2012 R2 12 8GB PgAdmin/命令行工具

查看 pgsql 官网安装包版本信息：https://postgres.ac.cn/download/windows/，选择 Windows Server 2012 R2 支持的 pg 最高版本。

问题场景

  1. 备份导出（测试环境） 
    psql.exe -d postgres -h localhost -p 5432 -U postgres -f D:/pgsql/data.dmp
  2. 恢复导入（生产环境） 
    pg_restore.exe -d postgres -h localhost -p 5432 -U postgres D:/pgsql/data.dmp
  3. 触发报错（生产环境） 
    pg_restore: [archiver] unsupported version (1.16) in file header

原因分析

核心矛盾：版本兼容性

  • 二进制格式的版本锁 PostgreSQL 的 pg_dump -Fc 生成的自定义二进制文件（.dmp）会记录格式版本号（如 1.16），要求 pg_restore 必须使用匹配版本解析。

  • 高低版本限制规则

✅ 允许从低版本向高版本恢复（如 12→16）

❌ 禁止从高版本向低版本恢复（如 16→12）

  • 工具链的隐藏陷阱

Navicat 导出的 SQL 文件可能包含高版本语法糖（如 GENERATED ALWAYS AS）

PgAdmin 的 GUI 工具存在版本依赖，需与数据库版本严格匹配

解决过程

试错路径记录

尝试方案 操作步骤 结果状态 根本原因分析
Navicat SQL 导出 通过客户端导出 SQL 文件 → 生产环境导入 报错：语法错误 SQL 文件包含高版本专属语法
PgAdmin 二进制迁移 测试环境导出.dmp → 生产环境安装 PgAdmin → GUI 导入 工具版本不兼容 PgAdmin 版本与 PostgreSQL 版本强绑定
命令行直接恢复 pg_restore 加载.dmp 文件 报错：版本头不匹配 二进制文件版本锁机制触发

最终解决

标准化迁移流程

  • 步骤一：生成版本无关 SQL 文件
# 在PostgreSQL 16测试环境执行（注意未使用-Fc参数！）
pg_dump -h localhost -U postgres postgres > db_250217.sql
  • 步骤二：执行全量 SQL 导入
# 在PostgreSQL 12生产环境执行
psql -U postgres -d postgres < D:\data\backup\db_250217.sql
  • 关键参数说明 无-Fc，强制生成纯 SQL 文本格式（无版本限制），避免使用二进制格式跨版本迁移。