MuseMVP

全面梳理数据库配置：schema 设计、连接策略与 query 层扩展实践。

MuseMVP 使用 Drizzle ORM 与 PostgreSQL 进行数据持久化。数据库层同时支持标准 Node.js（Vercel、Docker）和 Cloudflare Workers（通过 Hyperdrive 连接池）。

数据库下载与配置

下载数据库（本地）或创建 Neon 实例（远程）

下载 PostgreSQL

官方安装入口（建议 16+，含 Windows/macOS/Linux 安装说明）

安装并启动服务后，创建开发数据库（示例）：

createdb musemvp

Windows 可直接使用官方安装器（附带 pgAdmin）；安装完成后确认 postgresql 服务已启动。
macOS / Linux 可通过包管理器安装并启动服务。

打开 Neon 控制台并创建 Project。
在 Connection Details 复制 Pooled connection string（推荐用于应用运行时）。

postgresql://neondb_username:npg_password@ep-xxx-bush-xxxx-pooler.ap-xxx-1.xxx.neon.tech/demo-musemvp-com?sslmode=require&channel_binding=require

配置数据库

在项目根目录创建 .env（可由 .env.local.example 复制），至少包含：

# 本地开发 / Vercel / Docker
DATABASE_CONNECTION_STRATEGY="database_url_first"
DATABASE_URL="postgresql://<user>:<password>@<host>:5432/<database>"

完成后运行：

pnpm drizzle:generate
pnpm drizzle:push

本地开发注意

本地 Node.js 开发不要使用 hyperdrive_first，请使用 database_url_first。

Cloudflare Worker 部署

部署到 Cloudflare Worker 时可改为 DATABASE_CONNECTION_STRATEGY="hyperdrive_first"，并配置 Hyperdrive；DATABASE_URL 可作为回退连接。

验证连接：

pnpm drizzle:studio

常用命令

pnpm drizzle:generate   # 根据 schema 变更生成迁移
pnpm drizzle:migrate    # 将迁移应用到数据库
pnpm drizzle:push       # 直接推送 schema（仅开发）
pnpm drizzle:studio     # 打开 Drizzle Studio GUI

npm run drizzle:generate
npm run drizzle:migrate
npm run drizzle:push
npm run drizzle:studio

连接策略

src/backend/database/client.ts 中的数据库客户端根据运行时解析连接：

Cloudflare Worker：优先使用 Hyperdrive 绑定（HYPERDRIVE.connectionString）实现边缘连接池。

Node.js（Vercel、Docker）：使用 DATABASE_URL 环境变量。

回退：Cloudflare 中若 Hyperdrive 不可用，则回退到 DATABASE_URL。

环境变量

本地开发与非 Cloudflare 部署需设置 DATABASE_URL。Cloudflare Workers 需配置 Hyperdrive，可选 DATABASE_URL 作为回退。

增量扩展流程

在 schema.ts 中添加或更新表。

运行 pnpm drizzle:generate 生成迁移文件。

运行 pnpm drizzle:migrate 应用迁移。

在 queries/* 中添加 query 函数。

在 src/backend/api/routes/* 中暴露行为。

通过 src/backend/api-client/* 消费。

运维清单

将迁移历史提交到版本控制
避免在路由 handler 中使用 raw SQL — 使用 query 层
在 API 中间件中做鉴权与所有权校验
对增长表使用显式索引（参见 schema.ts 示例）

数据库配置