数据库

配置 PostgreSQL，并使用经过审查的 Drizzle 迁移演进数据库结构。

VibeAny 使用 PostgreSQL 和 Drizzle ORM。随附的本地数据库与托管 PostgreSQL 服务商使用相同的数据库结构和已提交 SQL 迁移。

连接 PostgreSQL

在 .env.local 中设置标准 PostgreSQL 连接 URL：

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/vibeany

设置向导接受以 postgresql:// 或 postgres:// 开头的 URL，并会在写入所选值之前验证连接。

本地开发可以通过以下命令启动 PostgreSQL 16：

docker compose up -d db

如果 5432 端口已被占用，请通过向导使用其他主机端口：

VIBEANY_POSTGRES_PORT=55432 npm run setup

你也可以使用 Neon、Supabase PostgreSQL 或其他兼容的托管服务。请使用该服务商推荐的直连或连接池 URL，并包含它要求的 TLS 参数。

只使用迁移的政策

绝不要在本地、预览、测试或生产环境运行 db:push 或 drizzle-kit push。

db:push npm 脚本会有意报错退出。数据库结构变更必须记录在经过审查的迁移文件中，确保每个环境执行同一套历史记录。

应用交付的数据库结构

交付的源码归档包已经包含当前版本所需的已提交迁移：

npm run db:migrate

迁移程序会：

在一般的本地执行中读取 .env.local
在需要时创建 app_migrations 迁移记录表
按词法顺序执行 drizzle/*.sql 文件
跳过已经记录为完成的文件
在同一个数据库事务中执行每个迁移及其记录
遇到第一个失败时停止

重复运行 npm run db:migrate 是安全的；已经成功记录的文件不会再次执行。

修改数据库结构

数据库结构的源文件是 src/lib/db/schema.ts。每次修改都应使用以下工作流：

# 1. Edit src/lib/db/schema.ts

# 2. Generate a migration in drizzle/
npm run db:generate

# 3. Review the generated SQL before execution

# 4. Apply it to the intended development database
npm run db:migrate

# 5. Inspect data and structure when useful
npm run db:studio

请同时提交数据库结构修改、生成的 SQL 和 Drizzle 元数据。绝不要用手动修改生产数据库结构来代替迁移。

现有数据领域

交付的数据库结构包含以下数据：

Better Auth 用户、会话、账户和验证令牌
与服务商无关的订阅和结账尝试
一次性订单和积分包
积分余额和 FIFO 事务历史
幂等 Webhook 收件箱记录
已上传文件的元数据
MCP API key、OAuth 客户端、授权、同意和令牌状态

与服务商无关的账单行会同时记录服务商和外部 ID。即使之后切换新结账流量所使用的服务商，也能保留现有订阅的来源。

生产环境执行前审查迁移

生成的 SQL 只是起点，不代表已经自动获批。请检查：

破坏性的 column 或 table 变更
现有数据上的 nullable-to-required 转换
现有数据可能违反的 index 或 constraint
长时间运行的 rewrite 或 lock
必要的数据回填顺序
回滚或恢复步骤

执行高风险迁移前，请按照数据库服务商的流程备份重要数据。上线生产环境前，用有代表性的数据测试完全相同的已提交迁移。

验证生产目标

部署前，配置目标生产环境的 DATABASE_URL，然后运行：

npm run preflight
npm run db:migrate

Preflight 会验证连接和已知的迁移安全约束。受支持的部署流程会先运行 preflight，再执行已提交的迁移。

接下来可以阅读身份认证与邮件；Better Auth 状态也使用同一个 PostgreSQL 数据库。