# PostgreSQL 备份与迁移

## 备份脚本

`scripts/pg-backup.sh` 封装了 `pg_dump` / `psql`，跨任何 PG 版本兼容。

```bash
./scripts/pg-backup.sh backup              # 备份
./scripts/pg-backup.sh restore             # 从最新备份恢复
./scripts/pg-backup.sh restore <文件路径>    # 恢复指定备份
```

备份文件写入 `backups/cyrene_YYYYMMDD_HHMMSS.sql`，自动保留最近 7 个。

## PG 大版本升级（16 → 17 等）

生产环境用 `docker-compose.yml`，开发环境用 `docker-compose.dev.yml`。

```bash
# === 步骤 1：备份 ===
./scripts/pg-backup.sh backup

# === 步骤 2：停服并清理 ===
docker compose -f docker-compose.dev.yml down

# 删旧 volume，确保新 PG 从干净状态初始化（可选但推荐）
docker volume rm cyrene_cyrene_pg_data

# === 步骤 3：修改镜像版本 ===
# docker-compose.dev.yml 中:
#   image: pgvector/pgvector:pg16  →  image: pgvector/pgvector:pg17

# === 步骤 4：启动新 PG ===
docker compose -f docker-compose.dev.yml up -d postgres

# 等 healthcheck 通过
docker ps --filter name=cyrene_postgres

# === 步骤 5：恢复数据 ===
./scripts/pg-backup.sh restore

# === 步骤 6：启动全栈 ===
docker compose -f docker-compose.dev.yml up -d
```

## 版本间切换（dev.db.yml ↔ dev.yml）

两个文件的 volume 名和容器名已对齐，直接切换即可，数据自动继承：

```bash
# 从轻量版切到全服务版
docker compose -f docker-compose.dev.db.yml down
docker compose -f docker-compose.dev.yml up -d

# 反向切回
docker compose -f docker-compose.dev.yml down
docker compose -f docker-compose.dev.db.yml up -d
```

原有的 `cyrene_*_data` volume 会被新容器直接挂载，无需恢复。

## 跨服务器迁移

```bash
# 源服务器
./scripts/pg-backup.sh backup
scp backups/cyrene_*.sql user@target:/path/to/backups/

# 目标服务器
./scripts/pg-backup.sh restore backups/cyrene_*.sql
```

## 常见问题

### 新版 PG 启动后不接受旧 volume

`pg_upgrade` 要求 in-place 升级必须用 PG 自带的升级工具，不能直接挂旧数据目录。如果没删旧 volume 导致启动失败：

```bash
docker logs cyrene_postgres   # 会提示 data directory incompatible
docker compose down
docker volume rm cyrene_cyrene_pg_data
docker compose up -d
./scripts/pg-backup.sh restore
```

### 备份文件过大

`pg_dump` 产生的 `.sql` 文件包含全部数据，如果数据库过大可以考虑：

```bash
# 仅导出结构，不导出日志/缓存表
docker exec cyrene_postgres pg_dump -U cyrene -d cyrene_ai \
  --schema-only > schema.sql

# 按表分别导出
docker exec cyrene_postgres pg_dump -U cyrene -d cyrene_ai \
  -t memories -t sessions -t users > core_tables.sql
```