React / 系统课时
配置 PostgreSQL 与 Prisma
配置 PostgreSQL 与 Prisma
本课从空目录搭建一套可验证的本地数据环境:启动 PostgreSQL、初始化 Prisma ORM、配置连接字符串、创建首个迁移,并通过 TypeScript 查询确认应用能够访问数据库。
学习目标
- 启动并检查本地 PostgreSQL 实例
- 初始化 Prisma 7 并管理本地连接配置
- 创建迁移、生成客户端并执行一次真实查询
检查本地工具
示例使用 Node.js、npm 和 Docker。先确认命令可用;版本号会因本机环境不同而变化,只要三个命令都能正常返回即可。
node --version
npm --version
docker --version预期输出:
v<VERSION>
<VERSION>
Docker version <VERSION>, build <ID>启动一个固定版本的 PostgreSQL 容器,并创建名为 react_task 的数据库。端口 5432 若已被占用,可将左侧端口改为其他值,并同步修改后面的连接字符串。
docker run --name react18-postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=react_task -p 5432:5432 -d postgres:17-alpine预期输出:
<ID>容器首次启动需要完成初始化。执行健康检查,直到看到接受连接的提示。
docker exec react18-postgres pg_isready -U postgres -d react_task预期输出:
/var/run/postgresql:5432 - accepting connections初始化 Prisma 项目
创建一个最小 TypeScript 项目,安装 Prisma CLI、PostgreSQL 驱动适配器和运行工具,再生成 Prisma 的基础目录。Prisma 7 连接 PostgreSQL 时需要将驱动适配器传给客户端。
mkdir prisma-demo
cd prisma-demo
npm init -y
npm install @prisma/client @prisma/adapter-pg pg dotenv
npm install -D prisma typescript tsx @types/node
npx prisma init --datasource-provider postgresql --output ../generated/prisma预期结果:
已创建 prisma/schema.prisma
已创建 prisma.config.ts
已创建 .env
依赖已写入 package.json初始化命令的提示文字可能随小版本变化,应以文件是否生成和命令退出码是否为零作为判断标准。
配置连接与数据模型
Prisma 的本地配置链路包含环境变量、CLI 配置、数据模型、迁移和生成客户端。分清各文件职责,可以避免把密码写入代码或把迁移配置散落在业务模块中。

将 .env 设置为本地数据库连接。真实项目不要把该文件提交到代码仓库。
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/react_task?schema=public"在 .gitignore 中排除本地密钥、依赖和生成代码:
node_modules
.env
generated使用 prisma.config.ts 告诉 Prisma CLI 模型文件、迁移目录和连接地址的位置:
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/schema.prisma 改为最小用户模型。连接地址不写在模型文件中,而是由 prisma.config.ts 从环境变量读取。
generator client {
provider = "prisma-client"
output = "../generated/prisma"
}
datasource db {
provider = "postgresql"
}
model User {
id Int @id @default(autoincrement())
email String @unique
name String
createdAt DateTime @default(now()) @map("created_at")
@@map("app_user")
}配置生效后,Prisma 会把 User 模型迁移为数据库中的 app_user 表,并将 createdAt 字段映射为 created_at 列。
创建迁移并验证连接
运行开发迁移。该命令会比较 Prisma 模型与数据库状态,生成 SQL 迁移并应用到本地数据库。
npx prisma migrate dev --name init
npx prisma generate预期结果:
已创建并应用迁移 prisma/migrations/<TIME>_init
数据库结构与 Prisma schema 同步
Prisma Client 已生成到 <PATH>/generated/prisma创建 src/check-db.ts,通过 PostgreSQL 驱动适配器实例化 Prisma Client。示例使用 upsert,重复执行不会因邮箱唯一约束而失败。
import "dotenv/config";
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "../generated/prisma/client";
const connectionString = process.env.DATABASE_URL;
if (!connectionString) {
throw new Error("缺少 DATABASE_URL");
}
const adapter = new PrismaPg({ connectionString });
const prisma = new PrismaClient({ adapter });
async function main(): Promise<void> {
const user = await prisma.user.upsert({
where: { email: "demo@example.com" },
update: { name: "演示用户" },
create: {
email: "demo@example.com",
name: "演示用户",
},
});
console.log(`数据库连接成功:${user.email}`);
}
main()
.catch((error: unknown) => {
console.error(error);
process.exitCode = 1;
})
.finally(async () => {
await prisma.$disconnect();
});执行验证脚本:
npx tsx src/check-db.ts预期输出:
数据库连接成功:demo@example.com处理典型连接失败
出现 P1001 时,先检查容器是否运行、端口映射是否正确,再确认连接地址中的主机和端口。认证失败通常来自用户名、密码或数据库名不一致,可对照 docker run 中的环境变量逐项检查。
若迁移提示权限不足,应使用拥有建表和创建迁移对象权限的本地开发账号。若环境变量未读取,确认 .env 位于项目根目录,并保留 prisma.config.ts 与查询脚本中的 dotenv/config 导入。