QAUP_Management/doc/deploy/database_migration.md

PostgreSQL 数据库迁移指南

概述

本文档描述如何将本地 PostgreSQL 数据库完全覆盖导入到远程服务器。

场景：

• 本地数据库用户：postgres
• 远程数据库用户：qaup
• 数据库名称：qaup
• 操作方式：完全覆盖

第一步：本地数据库导出

导出完整数据库

# 导出数据库（包含结构和数据，处理用户名差异）
pg_dump -h localhost -U postgres -d qaup --no-owner --no-privileges --clean --if-exists -f qaup_database_export.sql

参数说明：

• --no-owner: 不包含对象所有者信息，避免用户名冲突
• --no-privileges: 不包含权限设置，导入后重新设置权限
• --clean --if-exists: 清理现有对象（如果存在）
• -f: 指定输出文件名

第二步：远程服务器完全覆盖

# 1. 删除现有数据库
psql -U qaup -d postgres -c "DROP DATABASE IF EXISTS qaup;"

# 2. 重新创建数据库
psql -U qaup -d postgres -c "CREATE DATABASE qaup OWNER qaup;"

# 3. 设置PostGIS扩展
psql -U qaup -d qaup -c "CREATE EXTENSION IF NOT EXISTS postgis;"

# 4. 导入数据
psql -U qaup -d qaup -f qaup_database_export.sql

第三步：验证导入结果

检查数据库结构

# 查看所有表
psql -U qaup -d qaup -c "\dt"

# 查看特定表结构
psql -U qaup -d qaup -c "\d traffic_lights"

验证数据完整性

# 检查关键表的数据量
psql -U qaup -d qaup -c "SELECT count(*) FROM traffic_lights;"
psql -U qaup -d qaup -c "SELECT count(*) FROM intersections;"
psql -U qaup -d qaup -c "SELECT count(*) FROM sys_vehicle_info;"

检查用户权限

# 确保qaup用户拥有所有表的权限
psql -U qaup -d qaup -c "GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO qaup;"
psql -U qaup -d qaup -c "GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO qaup;"

注意事项

1. 备份重要性：操作前确保远程数据库已备份（如有重要数据）
2. 网络连接：确保网络稳定，大数据库传输可能需要较长时间
3. 磁盘空间：确认远程服务器有足够存储空间
4. 权限检查：确保qaup用户有CREATE DATABASE权限（方案A）
5. 应用停机：建议在应用停机时间窗口执行，避免数据不一致

故障排除

连接失败

# 检查用户权限
psql -U qaup -d postgres -c "SELECT current_user;"

导入错误

# 查看详细错误信息
psql -U qaup -d qaup -f qaup_database_export.sql 2>&1 | tee import.log

权限问题

# 重置所有权限
psql -U qaup -d qaup -c "
GRANT ALL PRIVILEGES ON DATABASE qaup TO qaup;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO qaup;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO qaup;
GRANT ALL PRIVILEGES ON ALL FUNCTIONS IN SCHEMA public TO qaup;
"

完成后清理

# 删除本地导出文件（可选）
rm qaup_database_export.sql

# 删除临时脚本（如果使用了方案B）
rm drop_tables.sql

Java版本兼容性注意事项

如果在执行数据库迁移后更新应用，需要注意Java版本兼容性：

版本匹配检查

• 编译版本: 确保应用jar文件在Java 21环境下编译
• 运行版本: Docker容器中运行Java 21

版本不匹配错误示例

如果遇到 UnsupportedClassVersionError 错误：

class file has been compiled by a more recent version of the Java Runtime 
(class file version 65.0), this version of the Java Runtime only recognizes 
class file versions up to 61.0

解决方案

1. 确认Docker镜像使用Java 21：

   image: eclipse-temurin:21-jre
   

2. 检查容器Java版本：

   docker exec <container-name> java -version
   

---

创建时间： 2025-09-25 适用版本： PostgreSQL 12+ 测试环境： QAUP-Management 1.0.1