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>"}}

连接失败时按顺序检查连接串格式、数据库进程、网络与防火墙、用户密码、目标库是否存在,以及云数据库是否允许当前来源地址。不要把完整连接串写入错误响应或日志。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

连接关系型数据库

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通