React / 系统课时
连接关系型数据库
连接关系型数据库
数据库代码能通过类型检查,不代表运行时一定能连接成功。本课以 PostgreSQL 和 Prisma ORM 7 为例,完成依赖安装、连接配置、客户端单例和健康检查,最终用接口确认当前数据库可访问。
学习目标
- 配置 PostgreSQL 连接字符串与 Prisma CLI
- 在 Next.js 开发环境复用 Prisma Client
- 通过真实查询验证网络、凭据和数据库名称
安装并初始化 Prisma
在 Next.js 项目根目录执行:
bash
npm install @prisma/client @prisma/adapter-pg pg dotenv
npm install --save-dev prisma @types/pg
npx prisma init --datasource-provider postgresql --output ../generated/prisma预期结果:
text
Prisma initialized in your project
Prisma schema created at prisma/schema.prisma
Prisma config created at prisma.config.ts不同 CLI 版本的提示文字可能略有差异,但项目中应出现 prisma/schema.prisma、prisma.config.ts 和 .env。
配置连接与生成客户端
在 .env 中填写开发数据库连接。用户名、密码、主机、端口和库名都应替换为实际值,且不要提交到版本库。
text
DATABASE_URL="postgresql://<USER>:<PASSWORD>@<HOST>:<PORT>/<DATABASE>?schema=public"生效行为:Next.js 运行时和 Prisma CLI 都可以从环境变量取得连接地址。
确认 prisma/schema.prisma 至少包含生成器和数据源:
prisma
generator client {
provider = "prisma-client"
output = "../generated/prisma"
}
datasource db {
provider = "postgresql"
}生效行为:prisma generate 会把类型安全客户端生成到项目根目录的 generated/prisma。配置 prisma.config.ts:
ts
import "dotenv/config";
import { defineConfig, env } from "prisma/config";
export default defineConfig({
schema: "prisma/schema.prisma",
migrations: {
path: "prisma/migrations",
},
datasource: {
url: env("DATABASE_URL"),
},
});生效行为:Prisma CLI 使用 .env 中的 DATABASE_URL 连接 PostgreSQL。生成客户端:
bash
npx prisma generate预期结果:
text
Generated Prisma Client to ./generated/prisma创建连接单例与健康检查
开发模式热更新可能重复加载模块,因此把客户端缓存在 globalThis。PostgreSQL 驱动适配器需要 Node.js 运行时。
ts
// lib/prisma.ts
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "@/generated/prisma/client";
const globalForPrisma = globalThis as unknown as {
prisma: PrismaClient | undefined;
};
function createPrismaClient() {
const connectionString = process.env.DATABASE_URL;
if (!connectionString) {
throw new Error("缺少 DATABASE_URL");
}
const adapter = new PrismaPg({ connectionString });
return new PrismaClient({ adapter });
}
export const prisma =
globalForPrisma.prisma ?? createPrismaClient();
if (process.env.NODE_ENV !== "production") {
globalForPrisma.prisma = prisma;
}
// app/api/health/database/route.ts
import { prisma } from "@/lib/prisma";
export const runtime = "nodejs";
export async function GET() {
const rows = await prisma.$queryRaw<
Array<{ database: string; now: Date }>
>`SELECT current_database() AS database, NOW() AS now`;
const row = rows[0];
return Response.json({
code: "OK",
message: "数据库连接正常",
data: {
database: row.database,
time: row.now.toISOString(),
},
});
}生效行为:开发环境只复用一个 Prisma Client;健康检查执行真实 SQL,而不是仅判断环境变量是否存在。
启动项目后执行,其中 <PORT> 替换为 Next.js 实际端口:
bash
curl "http://localhost:<PORT>/api/health/database"预期输出中的数据库名称和 <TIME> 以实际环境为准:
json
{"code":"OK","message":"数据库连接正常","data":{"database":"<DATABASE>","time":"<TIME>"}}连接失败时按顺序检查连接串格式、数据库进程、网络与防火墙、用户密码、目标库是否存在,以及云数据库是否允许当前来源地址。不要把完整连接串写入错误响应或日志。
按自己的节奏,确认真正理解。