React / 系统课时

配置 PostgreSQL 与 Prisma

配置 PostgreSQL 与 Prisma

本课从空目录搭建一套可验证的本地数据环境:启动 PostgreSQL、初始化 Prisma ORM、配置连接字符串、创建首个迁移,并通过 TypeScript 查询确认应用能够访问数据库。

学习目标

  • 启动并检查本地 PostgreSQL 实例
  • 初始化 Prisma 7 并管理本地连接配置
  • 创建迁移、生成客户端并执行一次真实查询

检查本地工具

示例使用 Node.js、npm 和 Docker。先确认命令可用;版本号会因本机环境不同而变化,只要三个命令都能正常返回即可。

bash
node --version
npm --version
docker --version

预期输出:

text
v<VERSION>
<VERSION>
Docker version <VERSION>, build <ID>

启动一个固定版本的 PostgreSQL 容器,并创建名为 react_task 的数据库。端口 5432 若已被占用,可将左侧端口改为其他值,并同步修改后面的连接字符串。

bash
docker run --name react18-postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=react_task -p 5432:5432 -d postgres:17-alpine

预期输出:

text
<ID>

容器首次启动需要完成初始化。执行健康检查,直到看到接受连接的提示。

bash
docker exec react18-postgres pg_isready -U postgres -d react_task

预期输出:

text
/var/run/postgresql:5432 - accepting connections

初始化 Prisma 项目

创建一个最小 TypeScript 项目,安装 Prisma CLI、PostgreSQL 驱动适配器和运行工具,再生成 Prisma 的基础目录。Prisma 7 连接 PostgreSQL 时需要将驱动适配器传给客户端。

bash
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

预期结果:

text
已创建 prisma/schema.prisma
已创建 prisma.config.ts
已创建 .env
依赖已写入 package.json

初始化命令的提示文字可能随小版本变化,应以文件是否生成和命令退出码是否为零作为判断标准。

配置连接与数据模型

Prisma 的本地配置链路包含环境变量、CLI 配置、数据模型、迁移和生成客户端。分清各文件职责,可以避免把密码写入代码或把迁移配置散落在业务模块中。

PostgreSQL 与 Prisma 本地配置链路

将 .env 设置为本地数据库连接。真实项目不要把该文件提交到代码仓库。

bash
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/react_task?schema=public"

在 .gitignore 中排除本地密钥、依赖和生成代码:

text
node_modules
.env
generated

使用 prisma.config.ts 告诉 Prisma CLI 模型文件、迁移目录和连接地址的位置:

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/schema.prisma 改为最小用户模型。连接地址不写在模型文件中,而是由 prisma.config.ts 从环境变量读取。

prisma
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 迁移并应用到本地数据库。

bash
npx prisma migrate dev --name init
npx prisma generate

预期结果:

text
已创建并应用迁移 prisma/migrations/<TIME>_init
数据库结构与 Prisma schema 同步
Prisma Client 已生成到 <PATH>/generated/prisma

创建 src/check-db.ts,通过 PostgreSQL 驱动适配器实例化 Prisma Client。示例使用 upsert,重复执行不会因邮箱唯一约束而失败。

ts
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();
  });

执行验证脚本:

bash
npx tsx src/check-db.ts

预期输出:

text
数据库连接成功:demo@example.com

处理典型连接失败

出现 P1001 时,先检查容器是否运行、端口映射是否正确,再确认连接地址中的主机和端口。认证失败通常来自用户名、密码或数据库名不一致,可对照 docker run 中的环境变量逐项检查。

若迁移提示权限不足,应使用拥有建表和创建迁移对象权限的本地开发账号。若环境变量未读取,确认 .env 位于项目根目录,并保留 prisma.config.ts 与查询脚本中的 dotenv/config 导入。

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

目录与阅读设置

阅读设置

17

记录一个想法

配置 PostgreSQL 与 Prisma

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

登录哪都通