将 Prisma ORM 添加到现有的 Prisma Postgres 项目

Prisma Postgres 是一个完全托管的 PostgreSQL 数据库，可扩展到零，并与 Prisma ORM 和 Prisma Studio 无缝集成。本指南将介绍如何将 Prisma ORM 添加到现有 TypeScript 项目中，将其连接到 Prisma Postgres，内省现有数据库模式，并开始使用类型安全的 Prisma Client 进行查询。

先决条件

您需要

• 您的机器上安装了 Node.js v20.19+、v22.12+ 或 v24.0+
• JavaScript 或 TypeScript 基础知识

1. 设置 Prisma ORM

导航到您现有的项目目录并安装所需的依赖项

npm install prisma @types/node @types/pg --save-dev
npm install @prisma/client @prisma/adapter-pg pg dotenv

每个包的作用如下

• prisma - 用于运行 prisma init、prisma db pull 和 prisma generate 等命令的 Prisma CLI
• @prisma/client - 用于查询数据库的 Prisma Client 库
• @prisma/adapter-pg - 将 Prisma Client 连接到数据库的 node-postgres 驱动程序适配器
• pg - node-postgres 数据库驱动程序
• @types/pg - node-postgres 的 TypeScript 类型定义
• dotenv - 从您的 .env 文件加载环境变量

2. 初始化 Prisma ORM

使用以下命令创建 Prisma Schema 文件来设置您的 Prisma ORM 项目

npx prisma init --datasource-provider postgresql --output ../generated/prisma

此命令执行以下操作

• 创建一个 prisma/ 目录，其中包含一个 schema.prisma 文件，其中包含您的数据库连接配置
• 在根目录中创建一个 .env 文件用于环境变量
• 创建一个 prisma.config.ts 文件用于 Prisma 配置

生成的 prisma.config.ts 文件如下所示

prisma.config.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'),
  },
})

生成的 schema 使用带有自定义输出路径的 ESM 优先的 prisma-client 生成器

prisma/schema.prisma

generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

datasource db {
  provider = "postgresql"
}

3. 连接您的数据库

使用 Prisma Postgres 连接 URL 更新 .env 文件

.env

DATABASE_URL="postgresql://user:password@host:5432/database?schema=public"

将占位符值替换为实际的 Prisma Postgres 连接详细信息。

4. 内省您的数据库

运行以下命令以内省您现有的数据库

npx prisma db pull

此命令读取 DATABASE_URL 环境变量，连接到您的数据库，并内省数据库模式。然后，它将数据库模式从 SQL 转换为您的 Prisma 模式中的数据模型。

内省后，您的 Prisma 模式将包含代表您现有数据库表的模型。

5. 基线化您的数据库

要将 Prisma Migrate 与现有数据库一起使用，您需要基线化您的数据库。

首先，创建一个 migrations 目录

mkdir -p prisma/migrations/0_init

接下来，使用 prisma migrate diff 生成迁移文件

npx prisma migrate diff --from-empty --to-schema prisma/schema.prisma --script > prisma/migrations/0_init/migration.sql

检查生成的迁移文件，确保它与您的数据库模式匹配。

然后，将迁移标记为已应用

npx prisma migrate resolve --applied 0_init

您现在拥有当前数据库模式的基线。

6. 生成 Prisma ORM 类型

根据您内省的模式生成 Prisma Client

npx prisma generate

这会在 generated/prisma 目录中创建一个根据您的数据库模式量身定制的类型安全的 Prisma Client。

7. 实例化 Prisma Client

创建一个实用文件来实例化 Prisma Client。您需要将 Prisma ORM 驱动程序适配器的实例传递给 PrismaClient 构造函数

lib/prisma.ts

import "dotenv/config";
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from '../generated/prisma/client'

const connectionString = `${process.env.DATABASE_URL}`

const adapter = new PrismaPg({ connectionString })
const prisma = new PrismaClient({ adapter })

export { prisma }

提示

如果需要通过 HTTP 从边缘运行时（Cloudflare Workers、Vercel Edge Functions 等）查询数据库，请使用 Prisma Postgres 无服务器驱动程序。

8. 查询您的数据库

现在您可以使用 Prisma Client 查询您的数据库。创建一个 script.ts 文件

script.ts

import { prisma } from './lib/prisma'

async function main() {
  // Example: Fetch all records from a table
  // Replace 'user' with your actual model name
  const allUsers = await prisma.user.findMany()
  console.log('All users:', JSON.stringify(allUsers, null, 2))
}

main()
  .then(async () => {
    await prisma.$disconnect()
  })
  .catch(async (e) => {
    console.error(e)
    await prisma.$disconnect()
    process.exit(1)
  })

运行脚本

npx tsx script.ts

9. 演进您的模式

要更改您的数据库模式

9.1. 更新您的 Prisma 模式文件

更新您的 Prisma 模式文件以反映您想要对数据库模式进行的更改。例如，添加一个新模型

prisma/schema.prisma

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

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

9.2. 创建并应用迁移：

npx prisma migrate dev --name your_migration_name

此命令将

• 创建一个新的 SQL 迁移文件
• 将迁移应用到您的数据库
• 重新生成 Prisma Client

10. 使用 Prisma Studio 探索您的数据

Prisma Studio 是一个用于数据库的可视化编辑器。使用以下命令启动它

npx prisma studio --config ./prisma.config.ts

这会打开一个 Web 界面，您可以在其中查看和编辑数据。

支持的数据库

Prisma Studio 目前支持 PostgreSQL、MySQL 和 SQLite。有关更多详细信息，请参阅Prisma Studio 支持的数据库。

后续步骤

您已成功设置 Prisma ORM。接下来您可以探索

• 了解有关 Prisma Client 的更多信息：探索 Prisma Client API 以进行高级查询、筛选和关系操作
• 数据库迁移：了解 Prisma Migrate 以演进您的数据库模式
• 性能优化：发现查询优化技术
• 构建完整的应用程序：查看我们的框架指南，将 Prisma ORM 与 Next.js、Express 等集成
• 加入社区：在 Discord 上与其他开发者联系

更多信息

• Prisma Postgres 文档
• Prisma 配置参考
• 数据库内省
• Prisma Migrate
• 缓存您的查询