lawless/scripts/README.md

洪荒大陆 · 数据库脚本

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

前置依赖

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

执行数据库迁移。

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

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

seed.sh

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

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

./scripts/seed.sh

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

reset.sh

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

./scripts/reset.sh

wait-for-it.sh

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

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

Makefile 快捷入口（可选）

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

migrate:
	./scripts/migrate.sh

seed:
	./scripts/seed.sh

reset-db:
	./scripts/reset.sh

注意事项

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