向现有 MongoDB 项目添加 Prisma ORM

MongoDB 是一款流行的基于文档的 NoSQL 数据库，以其灵活性、可扩展性和对开发人员友好的特性而闻名。在本指南中，你将学习如何向现有的 TypeScript 项目添加 Prisma ORM，将其连接到 MongoDB，自省现有数据库模式，并开始使用类型安全的 Prisma Client 进行查询。

Prisma ORM v7 的 MongoDB 支持

Prisma ORM v7 的 MongoDB 支持即将推出。在此期间，使用 MongoDB 时请使用 Prisma ORM v6.19（最新的 v6 版本）。

本指南使用 Prisma ORM v6.19 以确保与 MongoDB 的完全兼容性。

提示

如果你正在从 Mongoose 迁移到 Prisma ORM，请参阅我们的从 Mongoose 迁移指南。

先决条件

为了成功完成本指南，你需要

• 你的机器上安装了 Node.js（请参阅系统要求以了解官方支持的版本）
• 一个带有 package.json 文件的现有 TypeScript 项目
• 访问具有副本集部署的 MongoDB 4.2+ 服务器。我们建议使用 MongoDB Atlas。

警告

MongoDB 数据库连接器使用事务来支持嵌套写入。事务需要副本集部署。部署副本集的最简单方法是使用 Atlas。它是免费的入门版。

确保你手头有数据库连接 URL（其中包含你的身份验证凭据）！

注意

如果你的项目包含多个带有 package.json 文件的目录（例如，frontend、backend 等），请注意 Prisma ORM 专门设计用于 API/后端层。要设置 Prisma，请导航到包含相关 package.json 文件的相应后端目录并在那里配置 Prisma。

1. 设置 Prisma ORM

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

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

每个包的作用如下

• prisma - 用于运行 prisma init、prisma db pull 和 prisma generate 等命令的 Prisma CLI
• @prisma/client - 用于查询数据库的 Prisma Client 库
• dotenv - 从您的 .env 文件加载环境变量

为什么选择 Prisma v6.19？

这是完全支持 MongoDB 的 Prisma ORM v6 最新稳定版本。Prisma ORM v7 对 MongoDB 的支持即将推出。

你也可以安装 prisma@6 和 @prisma/client@6 以自动获取最新的 v6 版本。

2. 初始化 Prisma ORM

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

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

此命令执行以下操作

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

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

prisma.config.ts

import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  engine: "classic",
  datasource: {
    url: env('DATABASE_URL'),
  },
})

将 dotenv 添加到 prisma.config.ts，以便 Prisma 可以从你的 .env 文件加载环境变量

prisma.config.ts

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  engine: "classic",
  datasource: {
    url: env('DATABASE_URL'),
  },
})

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

prisma/schema.prisma

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

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

3. 连接您的数据库

使用你的 MongoDB 连接 URL 更新 .env 文件

.env

DATABASE_URL="mongodb+srv://username:password@cluster.mongodb.net/mydb"

对于 MongoDB Atlas，连接 URL 格式为

mongodb+srv://USERNAME:PASSWORD@CLUSTER.mongodb.net/DATABASE

自托管 MongoDB 连接 URL 格式

mongodb://USERNAME:PASSWORD@HOST:PORT/DATABASE

连接 URL 组件

• USERNAME：你的数据库用户名
• PASSWORD：你的数据库用户密码
• HOST：运行 mongod 或 mongos 的主机
• PORT：数据库服务器运行的端口（通常为 27017）
• DATABASE：数据库的名称

提示

对于 MongoDB Atlas，你可以手动将数据库名称附加到连接 URL，因为 Atlas 默认不包含它。

连接问题排查

Error in connector: SCRAM failure: Authentication failed.

如果你看到 Error in connector: SCRAM failure: Authentication failed. 错误消息，可以通过在连接字符串末尾添加 ?authSource=admin 来指定身份验证的源数据库。

Raw query failed. Error code 8000 (AtlasError): empty database name not allowed.

如果你看到 Raw query failed. Code: unknown. Message: Kind: Command failed: Error code 8000 (AtlasError): empty database name not allowed. 错误消息，请务必将数据库名称附加到数据库 URL。你可以在此 GitHub 问题 中找到更多信息。

4. 内省您的数据库

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

npx prisma db pull

此命令

• 从你的 .env 文件中读取 DATABASE_URL
• 连接到你的 MongoDB 数据库
• 对集合中的文档进行采样以推断模式
• 在你的 schema.prisma 文件中生成 Prisma 模型

信息

MongoDB 自省限制：Prisma 通过对文档进行采样来对 MongoDB 进行自省。你可能需要手动

• 使用 @relation 属性添加关系字段
• 如果采样未捕获所有变体，请调整字段类型
• 添加自省期间未检测到的索引和约束

5. 生成 Prisma ORM 类型

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

npx prisma generate

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

6. 实例化 Prisma Client

创建实用程序文件以实例化 Prisma Client

lib/prisma.ts

import "dotenv/config";
import { PrismaClient } from '../generated/prisma/client'

const prisma = new PrismaClient()

export { prisma }

7. 查询你的数据库

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

script.ts

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

async function main() {
  // Example: Fetch all records from a collection
  // 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

8. 演进你的模式

MongoDB 不支持像关系数据库那样的迁移。相反，请使用 db push 同步模式更改

8.1. 更新你的 Prisma 模式文件

使用你想要的更改修改你的 Prisma 模式文件。例如，添加一个新模型

prisma/schema.prisma

model Post {
  id        String   @id @default(auto()) @map("_id") @db.ObjectId
  title     String
  content   String?
  published Boolean  @default(false)
  authorId  String   @db.ObjectId
  author    User     @relation(fields: [authorId], references: [id])
}

model User {
  id    String @id @default(auto()) @map("_id") @db.ObjectId
  email String @unique
  name  String?
  posts Post[]
}

信息

在 MongoDB 中，id 字段映射到 _id 并使用 @db.ObjectId 类型。关系使用带有 @db.ObjectId 注解的 String 类型。

8.2. 将更改推送到你的数据库

npx prisma db push

此命令

• 将模式更改应用于你的 MongoDB 数据库
• 自动重新生成 Prisma Client

为什么是 db push 而不是迁移？

MongoDB 使用灵活的模式模型。Prisma Migrate（它创建迁移文件）不支持 MongoDB。始终使用 prisma db push 同步你的模式更改。

9. 探索你的数据

你可以使用 MongoDB Atlas、MongoDB shell 或 MongoDB Compass 查看和管理你的数据。

Prisma Studio 目前不支持 MongoDB。未来版本可能会添加支持。有关更多信息，请参阅Prisma Studio 支持的数据库。

后续步骤

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

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

更多信息

• MongoDB 数据库连接器
• Prisma 配置参考
• 数据库内省