# 洪荒大陆 · 数据库脚本

本目录包含本地开发用的数据库迁移、种子与重置脚本。

## 前置依赖

1. PostgreSQL 16 已运行（本地或 Docker）。
2. 已安装 `psql` 客户端。
3. 项目根目录存在 `.env` 文件，且包含 `DATABASE_URL`。

> 可执行 `cp .env.example .env` 后按需修改。

## 环境变量

| 变量 | 说明 | 示例 |
|------|------|------|
| `DATABASE_URL` | **必须**。PostgreSQL 连接串 | `postgres://honghuang:honghuang@localhost:5432/honghuang?sslmode=disable` |
| `DB_WAIT_TIMEOUT` | 可选。等待数据库就绪的超时秒数，默认 30 | `60` |

## 脚本说明

### `migrate.sh`

执行数据库迁移。

```bash
# 执行 up 迁移（创建表 + 初始参考数据）
./scripts/migrate.sh

# 执行 down 迁移（删除所有表）
./scripts/migrate.sh down
```

### `seed.sh`

在迁移完成后插入开发测试数据：

- 2 名测试玩家
- 2 名测试角色（虎妖 / 光精灵）
- 对应的 `character_race_states` 与 `character_realms`
- 基础货币余额（铜钱、鸿蒙紫气）

```bash
./scripts/seed.sh
```

脚本为幂等设计，可重复执行，重复执行时会更新货币余额为初始值。

### `reset.sh`

开发环境一键重置：先 down，再 up，最后 seed。

```bash
./scripts/reset.sh
```

### `wait-for-it.sh`

TCP 端口等待工具，被 `migrate.sh` / `seed.sh` 内部使用，也可单独调用：

```bash
./scripts/wait-for-it.sh localhost:5432 -t 30
```

## Makefile 快捷入口（可选）

可在项目根目录 `Makefile` 中添加：

```makefile
migrate:
	./scripts/migrate.sh

seed:
	./scripts/seed.sh

reset-db:
	./scripts/reset.sh
```

## 注意事项

- `reset.sh` 会清空当前数据库全部业务数据，**仅用于开发/测试环境**。
- `seed.sh` 中的测试角色名为「测试修士·甲」「测试修士·乙」，创建前会检查重名，因此可安全重复执行。
- 脚本默认在 `DATABASE_URL` 对应的数据库上操作，请确认 `.env` 配置正确。