Prisma ORM + PostgreSQL 终极指南（2025 版）

Source: Dev.to

项目初始化

首先设置你的 Node.js 环境并使用 TypeScript。我们使用 tsx 来实现现代、快速的执行。

mkdir prisma-postgres-2025
cd prisma-postgres-2025
npm init -y
npm install typescript tsx @types/node --save-dev
npx tsc --init

安装 Prisma 和 PostgreSQL 驱动

在 2025 年，强烈建议安装官方的 PostgreSQL 适配器，以获得在无服务器和边缘环境中的更好性能。

npm install prisma --save-dev
npm install @prisma/client @prisma/adapter-pg pg

初始化 Prisma

运行以下命令生成模板。这会创建 prisma/schema.prisma 文件和 .env 文件。

npx prisma init --datasource-provider postgresql

配置你的连接

打开 .env 文件。PostgreSQL 连接字符串的格式如下：

# Format: postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public
DATABASE_URL="postgresql://postgres:mypassword@localhost:5432/mydb?schema=public"

定义你的现代 Schema

在 prisma/schema.prisma 中定义模型。这些模型充当数据库的“代理”。

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
  author    User    @relation(fields: [authorId], references: [id])
  authorId  Int
}

应用迁移

使用 Prisma Migrate 将你的 schema 推送到 PostgreSQL。这会创建实际的表并生成类型安全的客户端。

npx prisma migrate dev --name init

实例化客户端（单例模式）

为防止 PostgreSQL 中出现 “Too many connections” 错误（尤其是在热重载的开发环境下），使用以下单例模式：

// db.ts
import { PrismaClient } from '@prisma/client'

const globalForPrisma = global as unknown as { prisma: PrismaClient }

export const prisma = globalForPrisma.prisma || new PrismaClient()

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma

执行 CRUD 操作

现在你可以编写完全类型安全的查询。Prisma 会自动处理 PostgreSQL 的 JOIN 和关联。

import { prisma } from './db'

async function run() {
  // 创建用户并在同一事务中创建帖子
  const user = await prisma.user.create({
    data: {
      email: 'hello@dev.to',
      name: 'Dev Reader',
      posts: {
        create: { title: 'Learning Prisma in 2025' }
      }
    }
  })

  // 读取：获取所有用户并包含他们的帖子
  const allUsers = await prisma.user.findMany({
    include: { posts: true }
  })

  console.log(JSON.stringify(allUsers, null, 2))
}

run()

2025 年 PostgreSQL 的新特性

• Rust‑Free 引擎： Prisma 6/7 转向基于 TypeScript 的引擎，带来更快的冷启动和更小的 Docker 镜像。
• TypedSQL： 在 .sql 文件中编写原始 SQL，Prisma 为其生成 TypeScript 类型，将原始 SQL 的强大功能与 ORM 的安全性相结合。
• Prisma Studio： 运行 npx prisma studio 启动可视化仪表板查看 PostgreSQL 数据——非常适合在没有单独数据库管理工具的情况下快速调试。
• 专业提示： 使用 Supabase、Neon 等托管 PostgreSQL 提供商时，在 .env 中使用它们的 “Connection Pooling” 连接字符串，以高效处理高并发流量。