# 现有数据库迁移 Runbook

| 项目 | 内容 |
| --- | --- |
| 状态 | Review；尚未在临时 PostgreSQL 演练 |
| 适用范围 | 任意既有数据库迁移为新建 v1alpha1 Tenant |
| 最后更新 | 2026-09-10 |

v1alpha1 不接管现有 database、role 或 OpenBao record。本流程通过逻辑 dump/restore 把
数据迁移到 controller 创建的新资源，保留旧资源作为限时回滚点。

以下命令是顺序模板，不可原样复制到真实环境。先把尖括号变量解析成明确值，确认当前
连接目标，再逐条执行。dump 可能包含敏感业务数据，必须放在加密临时存储且不得提交 Git。

## 前置条件

- 已验证 PostgreSQL/OpenBao 备份和恢复；记录恢复点。
- Instance 已 Ready，目标 namespace 存在，ESO ClusterSecretStore Ready。
- 最终 database/login role 当前由旧应用占用，但改名后的保留名称、新推导的 Bao path
  均不存在。
- 已记录旧 database owner、grants、extensions、locale/encoding、连接配置和验证清单。
- 已确认应用可停止写入，并确定回滚窗口和负责人。
- 已确认旧 login role 不被其他 database/应用共享，且角色改名不会破坏未纳入本次维护
  的依赖。

## 迁移顺序

### 1. 盘点与预演

```sh
pg_dump --schema-only --no-owner --no-privileges \
  --dbname='<old-admin-connection>' > schema-preview.sql
```

检查不受 v1alpha1 管理的对象：额外 roles、跨库依赖、FDW、large objects、订阅、显式
tablespace、owner/grant 和目标实例不支持的 extension。无法映射为单 database + 单 login
owner 的环境必须先人工简化，不能让 controller 猜测。

### 2. 创建一致性 dump

停止应用写入并确认活跃写事务结束，然后创建最终 custom-format dump：

```sh
pg_dump --format=custom --no-owner --no-privileges \
  --file='<secure-temp>/tenant.dump' \
  --dbname='<old-admin-connection>'
pg_restore --list '<secure-temp>/tenant.dump'
```

不要删除旧 database/role。记录停写时间、dump checksum 和 PostgreSQL 版本。

### 3. 释放最终名称

保持应用停写，终止旧 database 的应用连接。连接其他管理 database，以管理员身份把旧
database 和旧 login role 改为明确的保留名称：

```sql
ALTER DATABASE <old_database> RENAME TO <old_database>_retained_<timestamp>;
ALTER ROLE <old_login_role> RENAME TO <old_login_role>_retained_<timestamp>;
```

identifier 必须由管理员工具安全引用，不能把未经校验的值直接拼入 SQL。PostgreSQL 在
角色改名时会清除以旧角色名加盐的 MD5 密码；使用 MD5 的旧环境必须在维护前准备安全的
密码重设/回滚方法。SCRAM verifier 不受角色名改动影响，但仍须实际验证回滚登录。

### 4. 创建受管空目标

应用 `PostgreSQLTenant`，使用未被占用的 database/loginRole，等待 Ready。确认：

- registry 记录 UID 正确；
- OpenBao metadata 属于该 Tenant；
- ExternalSecret Ready 且目标 Secret 已投射；
- 新凭据可以通过 DNS host 和 IP hostaddr 分别登录空 database。

### 5. Restore

从 OpenBao 或目标 Secret 安全取得新应用凭据，不要把密码放进 shell history。以新 login
owner 连接目标 database：

```sh
pg_restore --exit-on-error --no-owner --no-privileges \
  --dbname='<new-application-connection>' \
  '<secure-temp>/tenant.dump'
```

extension 应由 Tenant spec 创建。若 dump 仍包含 extension 定义，预演必须确认 restore
行为幂等；目标实例不支持的 extension 必须在迁移前解决。

### 6. 验证并切换

- 对比关键 schema、表数、行数/校验和、sequence、function 和 migration version。
- 用新 login 验证读写、migration 和应用健康检查。
- 将应用配置切换到新 Secret 或 OpenBao URL，保持旧数据库只读/停写。
- 观察一个约定窗口，确认错误率、连接数和关键业务功能。

### 7. 收尾

回滚窗口结束后，按独立变更删除旧 database/role/旧凭据；它们不属于 controller，禁止
通过 Tenant `Delete` 清理。安全删除 dump 和临时凭据材料，并记录验证结果。

## 回滚

在新目标出现问题且旧资源仍保留时：

1. 立即停止新目标写入。
2. 评估切换后是否产生新数据；若有，先决定反向迁移或接受丢弃，不能盲目切回。
3. 将应用连接切回 retained database/role；若必须恢复原名称，先确保新受管目标已用
   `Delete` 完整清理或改用不同名称，再安全地反向执行 rename。
4. 恢复旧凭据（MD5 环境可能需要重设），验证旧服务。
5. 保留失败 Tenant 供排障；选择 Retain 或 Delete 前明确其外部资源后果。

若已经删除旧资源，则只能使用已验证备份恢复，不再属于本 runbook 的快速回滚。

## 演练验收

发布首个可用版本前，必须在临时 PostgreSQL/OpenBao/Kind 环境执行本文并记录：

- 使用的 PostgreSQL major version 和命令版本；
- dump/restore 返回码和对象差异；
- DNS/IP TLS 登录结果；
- ESO 投射与应用启动结果；
- 回滚演练结果；
- 哪些命令或前置检查需要修订。

完成演练前，本文不得标记为 `Verified`。