本地 PostgreSQL 开发指南

本文档说明如何在当前项目中使用 Docker 启动/关闭本地 PostgreSQL，并完成常见数据库开发流程。

1. 当前约定（已配置）

• 开发环境文件：.env.development
• 数据库类型：postgresql
• 连接串：postgresql://postgres:postgres@127.0.0.1:5433/colorwalk
• Docker 配置文件：docker-compose.yml
• 容器名：colorwalk-postgres

说明：本机 5432 端口已被其他 PostgreSQL 占用，所以项目容器使用 5433。

2. 启动本地数据库

docker compose up -d postgres
docker compose ps

看到 colorwalk-postgres 状态为 Up（或 healthy）即可。

3. 关闭本地数据库

只停止容器（保留数据卷）：

docker compose stop postgres

停止并移除容器/网络（仍保留数据卷）：

docker compose down

4. 初始化/更新数据库结构（迁移）

启动数据库后执行：

pnpm db:migrate

该命令会读取 .env.development，并执行 src/config/db/migrations 中的 PostgreSQL 迁移。

5. 日常开发流程（推荐）

1. 启动数据库：docker compose up -d postgres
2. 同步结构：pnpm db:migrate
3. 启动应用：pnpm dev
4. 开发完成后可停止数据库：docker compose stop postgres

6. 常用操作

查看数据库容器日志：

docker compose logs -f postgres

进入 PostgreSQL 命令行：

docker exec -it colorwalk-postgres psql -U postgres -d colorwalk

查看表：

\dt

查看连接是否正确：

select current_database(), current_user;

7. 重置本地数据库（谨慎）

如果你要从零开始（会删除本地全部数据）：

docker compose down -v
docker compose up -d postgres
pnpm db:migrate

-v 会删除 colorwalk_postgres_data 数据卷，请确认后再执行。

8. 常见问题排查

端口冲突（port is already allocated）：

• 说明端口被占用。当前项目已改为 5433，保持 .env.development 与 docker-compose.yml 一致即可。

认证失败（password authentication failed for user "postgres"）：

• 检查 .env.development 中 DATABASE_URL 用户名/密码是否为 postgres:postgres。
• 确认连接的端口是 5433 而不是 5432。

迁移失败：

• 先确认容器已启动：docker compose ps
• 再看日志：docker compose logs postgres
• 然后重试：pnpm db:migrate

9. 与线上环境的关系

• 本地数据库只用于开发和测试。
• 不要把本地数据目录或临时 SQL 直接作为线上变更来源。
• 线上结构变更应通过 PostgreSQL 迁移流程执行（而不是 SQLite 流程）。