# PostgreSQL 数据库迁移指南

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

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

## 第一步：本地数据库导出

### 导出完整数据库
```bash
# 导出数据库（包含结构和数据，处理用户名差异）
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`: 指定输出文件名

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

```bash
# 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
```

## 第三步：验证导入结果

### 检查数据库结构
```bash
# 查看所有表
psql -U qaup -d qaup -c "\dt"

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

### 验证数据完整性
```bash
# 检查关键表的数据量
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;"
```

### 检查用户权限
```bash
# 确保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. **应用停机**：建议在应用停机时间窗口执行，避免数据不一致

## 故障排除

### 连接失败
```bash
# 检查用户权限
psql -U qaup -d postgres -c "SELECT current_user;"
```

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

### 权限问题
```bash
# 重置所有权限
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;
"
```

## 完成后清理

```bash
# 删除本地导出文件（可选）
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：
   ```yaml
   image: eclipse-temurin:21-jre
   ```

2. 检查容器Java版本：
   ```bash
   docker exec <container-name> java -version
   ```

---

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