跳至主要内容

MongoDB

本指南讨论了使用 Prisma ORM 和 MongoDB 背后的概念,解释了 MongoDB 与其他数据库提供商之间的共性和差异,并指导您完成配置应用程序以使用 Prisma ORM 集成 MongoDB 的过程。

信息

要将 Prisma ORM 连接到 MongoDB,请参阅我们的入门文档

什么是 MongoDB?

MongoDB 是一个 NoSQL 数据库,它以 BSON 格式存储数据,这是一种类似 JSON 的文档格式,旨在以键值对的形式存储数据。它通常用于 JavaScript 应用程序开发,因为文档模型可以轻松映射到应用程序代码中的对象,并且内置支持高可用性和水平扩展。

MongoDB 将数据存储在集合中,这些集合不需要预先定义架构,就像在关系数据库中需要对表进行操作一样。每个集合的结构也可以随着时间的推移而改变。这种灵活性可以使您的数据模型快速迭代,但这也意味着在使用 Prisma ORM 处理您的 MongoDB 数据库时存在一些差异。

与其他数据库提供商的共性

使用 Prisma ORM 与 MongoDB 的某些方面与使用 Prisma ORM 与关系数据库相同。您仍然可以

需要考虑的差异

MongoDB 的基于文档的结构和灵活的架构意味着使用 Prisma ORM 与 MongoDB 的方式与使用它与关系数据库的方式有所不同。以下是一些您需要注意的差异区域

  • **定义 ID**: MongoDB 文档具有一个 _id 字段(通常包含一个 ObjectID)。Prisma ORM 不支持以 _ 开头的字段,因此需要使用 @map 属性将其映射到 Prisma ORM 字段。有关更多信息,请参阅 在 MongoDB 中定义 ID

  • **将现有数据迁移以匹配您的 Prisma 架构**: 在关系数据库中,所有数据都必须与您的架构匹配。如果您在迁移时更改了架构中特定字段的类型,则所有数据也必须更新以匹配。相反,MongoDB 不强制执行任何特定架构,因此在迁移时需要小心。有关更多信息,请参阅 如何将旧数据迁移到新架构

  • **内省和 Prisma ORM 关系**: 当您内省现有的 MongoDB 数据库时,您将获得一个没有关系的架构,并且需要手动添加缺少的关系。有关更多信息,请参阅 如何在内省后添加缺少的关系

  • **筛选 null 和缺少的字段**: MongoDB 区分将字段设置为 null 和根本不设置字段,这在关系数据库中不存在。Prisma ORM 目前不表达这种区别,这意味着在筛选 null 和缺少的字段时需要小心。有关更多信息,请参阅 如何筛选 null 和缺少的字段

  • **启用复制**: Prisma ORM 在内部使用 MongoDB 事务 以避免嵌套查询中的部分写入。使用事务时,MongoDB 需要启用数据集的复制。为此,您需要配置一个 副本集 - 这是一个维护相同数据集的 MongoDB 进程组。请注意,仍然可以使用单个数据库,方法是创建一个只有一个节点的副本集。如果您使用 MongoDB 的 Atlas 托管服务,则会为您配置副本集,但如果您在本地运行 MongoDB,则需要自己设置副本集。有关更多信息,请参阅 MongoDB 的 部署副本集指南

如何使用 Prisma ORM 与 MongoDB

本节提供了有关如何执行需要特定于 MongoDB 的步骤的任务的说明。

如何将现有数据迁移以匹配您的 Prisma 架构

随着时间的推移迁移数据库是开发周期中的重要组成部分。在开发过程中,您需要更新 Prisma 模式(例如,添加新字段),然后更新开发环境数据库中的数据,最终将更新后的模式和新数据推送到生产数据库。

信息

使用 MongoDB 时,请注意模式和数据库之间的“耦合”被有意设计为比 SQL 数据库不那么严格;MongoDB 不会强制执行模式,因此您必须验证数据完整性。

这些更新模式和数据库的迭代任务可能导致模式与数据库中实际数据之间出现不一致。让我们看一下可能发生这种情况的一种场景,然后检查您和您的团队可以考虑用于处理这些不一致的几种策略。

场景:您需要为用户包含电话号码和电子邮件。您当前在 schema.prisma 文件中具有以下 User 模型

prisma/schema.prisma
model User {
id String @id @default(auto()) @map("_id") @db.ObjectId
email String
}

您可以使用多种策略来迁移此模式

  • “按需”更新:使用此策略,您和您的团队已同意可以根据需要对模式进行更新。但是,为了避免由于数据和模式之间不一致而导致迁移失败,团队中达成一致意见,即添加的任何新字段都明确定义为可选的。

    在上面的场景中,您可以将可选的 phoneNumber 字段添加到 Prisma 模式中的 User 模型

    prisma/schema.prisma
    model User {
    id String @id @default(auto()) @map("_id") @db.ObjectId
    email String
    phoneNumber String?
    }

    然后使用 npx prisma generate 命令重新生成 Prisma Client。接下来,更新您的应用程序以反映新字段,并重新部署您的应用程序。

    由于 phoneNumber 字段是可选的,因此您仍然可以查询尚未定义电话号码的旧用户。数据库中的记录将“按需”更新,因为应用程序的用户开始在新字段中输入其电话号码。

    另一种选择是在必填字段上添加默认值,例如

    prisma/schema.prisma
    model User {
    id String @id @default(auto()) @map("_id") @db.ObjectId
    email String
    phoneNumber String @default("000-000-0000")
    }

    然后,当您遇到缺少 phoneNumber 时,该值将强制转换为 000-000-0000

  • “无重大更改”更新:此策略建立在第一个策略的基础上,您的团队进一步达成共识,即您不重命名或删除字段,只添加新字段,并且始终将新字段定义为可选的。可以通过在 CI/CD 流程中添加检查来加强此策略,以验证模式中是否存在任何向后不兼容的更改。

  • “一次性”更新:此策略类似于关系数据库中的传统迁移,其中所有数据都更新以反映新模式。在上述场景中,您将创建一个脚本,为数据库中所有现有用户的电话号码字段添加值。然后,您可以使该字段成为应用程序中的必填字段,因为模式和数据是一致的。

内省后如何添加缺少的关系

在内省现有的 MongoDB 数据库后,您需要手动添加模型之间的关系。MongoDB 没有通过外键定义关系的概念,就像您在关系数据库中一样。但是,如果您在 MongoDB 中有一个集合,其中包含与另一个集合的 ID 字段匹配的“类似外键”字段,则 Prisma ORM 将允许您模拟集合之间的关系。

例如,采用具有两个集合的 MongoDB 数据库,UserPost。这些集合中的数据具有以下格式,其中 userId 字段将用户链接到帖子

User 集合

  • _id 字段,类型为 objectId
  • email 字段,类型为 string

Post 集合

  • _id 字段,类型为 objectId
  • title 字段,类型为 string
  • userId,类型为 objectID

使用 db pull 进行内省时,将按如下方式提取到 Prisma 模式中

prisma/schema.prisma
model Post {
id String @id @default(auto()) @map("_id") @db.ObjectId
title String
userId String @db.ObjectId
}

model User {
id String @id @default(auto()) @map("_id") @db.ObjectId
email String
}

这缺少 UserPost 模型之间的关系。要解决此问题,请使用 userId 作为 fields 值,手动将 user 字段添加到 Post 模型中,并使用 @relation 属性将其链接到 User 模型,以及将 posts 字段添加到 User 模型作为反向关系

prisma/schema.prisma
model Post {
id String @id @default(auto()) @map("_id") @db.ObjectId
title String
userId String @db.ObjectId
user User @relation(fields: [userId], references: [id])
}

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

有关如何在 Prisma ORM 中使用关系的更多信息,请参阅我们的文档

如何过滤 null 和缺少的字段

要了解 MongoDB 如何区分 null 和缺少的字段,请考虑一个具有可选 name 字段的 User 模型的示例

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

首先,尝试创建一个将 name 字段显式设置为 null 的记录。Prisma ORM 将按预期返回 name: null

const createNull = await prisma.user.create({
data: {
email: '[email protected]',
name: null,
},
})
console.log(createNull)
显示CLI结果
{
id: '6242c4ae032bc76da250b207',
email: '[email protected]',
name: null
}

如果直接检查您的 MongoDB 数据库,您还将看到一个新的记录,其中 name 设置为 null

{
"_id": "6242c4af032bc76da250b207",
"email": "[email protected]",
"name": null
}

接下来,尝试创建一个没有显式设置 name 字段的记录

const createMissing = await prisma.user.create({
data: {
email: '[email protected]',
},
})
console.log(createMissing)
显示CLI结果
{
id: '6242c4ae032bc76da250b208',
email: '[email protected]',
name: null
}

Prisma ORM 仍然返回 name: null,但如果直接查看数据库,您会发现该记录根本没有定义 name 字段

{
"_id": "6242c4af032bc76da250b208",
"email": "[email protected]"
}

Prisma ORM 在这两种情况下都返回相同的结果,因为我们目前没有办法在 MongoDB 中指定基础数据库中为 null 的字段和根本未定义的字段之间的这种差异 - 请参阅此 Github 问题以了解更多信息。

这意味着在过滤 null 和缺少的字段时,您目前必须小心。过滤具有 name: null 的记录将只返回第一条记录,其中 name 显式设置为 null

const findNulls = await prisma.user.findMany({
where: {
name: null,
},
})
console.log(findNulls)
显示CLI结果
[
{
id: '6242c4ae032bc76da250b207',
email: '[email protected]',
name: null
}
]

这是因为 name: null 正在检查相等性,并且不存在的字段不等于 null

要包含缺少的字段,请使用isSet 过滤器显式搜索为 null 或未设置的字段。这将返回两条记录

const findNullOrMissing = await prisma.user.findMany({
where: {
OR: [
{
name: null,
},
{
name: {
isSet: false,
},
},
],
},
})
console.log(findNullOrMissing)
显示CLI结果
[
{
id: '6242c4ae032bc76da250b207',
email: '[email protected]',
name: null
},
{
id: '6242c4ae032bc76da250b208',
email: '[email protected]',
name: null
}
]

更多关于使用 MongoDB 和 Prisma ORM 的信息

开始使用 MongoDB 和 Prisma ORM 的最快方法是参考我们的入门文档

这些教程将引导您完成连接到 MongoDB、推送模式更改和使用 Prisma Client 的过程。

更多参考信息可在MongoDB 连接器文档中找到。

有关如何设置和管理 MongoDB 数据库的更多信息,请参阅Prisma 数据指南

示例

要连接到 MongoDB 服务器,请在您的Prisma 模式中配置datasource

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

传递给 datasource 块的字段是

  • provider:指定 mongodb 数据源连接器。
  • url:指定 MongoDB 服务器的连接 URL。在本例中,使用环境变量来提供连接 URL。
警告

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

连接详细信息

连接 URL

MongoDB 连接 URL 可以通过不同的方式配置,具体取决于您托管数据库的方式。标准配置由以下组件组成

Structure of the MongoDB connection URL

基本 URL 和路径

连接 URL 的基本 URL 和路径部分由您的身份验证凭据、主机(以及可选的端口号)和数据库组成。

mongodb://USERNAME:PASSWORD@HOST/DATABASE

以下组件构成数据库的基本 URL

名称占位符描述
用户USERNAME数据库用户的名称,例如 janedoe
密码PASSWORD数据库用户的密码
主机HOST运行mongod实例的主机。如果您正在运行分片集群,这将是mongos实例。这可以是主机名、IP 地址或 UNIX 域套接字。
端口PORT数据库服务器运行的端口,例如 1234。如果未提供,则使用默认值 27017
数据库DATABASE

要使用的数据库名称。如果未指定,但设置了authSource选项,则使用authSource数据库名称。如果连接字符串中的数据库和authSource选项均未指定,则默认为admin

参数

连接 URL 也可以接受参数。以下示例设置了三个参数

  • 一个ssl连接
  • 一个connectTimeoutMS
  • 以及maxPoolSize
mongodb://USERNAME:PASSWORD@HOST/DATABASE?ssl=true&connectTimeoutMS=5000&maxPoolSize=50

有关连接字符串参数的完整列表,请参阅MongoDB 连接字符串文档。没有 Prisma ORM 特定的参数。

使用ObjectId

MongoDB 文档的_id字段通常包含一个ObjectId

{
"_id": { "$oid": "60d599cb001ef98000f2cad2" },
"createdAt": { "$date": { "$numberLong": "1624611275577" } },
"email": "[email protected]",
"name": "Ella",
"role": "ADMIN"
}

任何映射到基础数据库中ObjectId的字段(最常见的是 ID 和关系标量字段)

  • 必须是StringBytes类型
  • 必须包含@db.ObjectId属性
  • 可以选择使用@default(auto())在文档创建时自动生成有效的ObjectId

这是一个使用String的示例

model User {
id String @id @default(auto()) @map("_id") @db.ObjectId
// Other fields
}

这是另一个使用Bytes的示例

model User {
id Bytes @id @default(auto()) @map("_id") @db.ObjectId
// Other fields
}

另请参阅:在 MongoDB 中定义 ID 字段

生成ObjectId

要在您的应用程序中生成有效的ObjectId(用于测试目的或手动设置 ID 字段值),请使用bson包。

npm install --save bson
import { ObjectId } from 'bson'

const id = new ObjectId()

与关系数据库连接器的区别

本节介绍 MongoDB 连接器与 Prisma ORM 关系数据库连接器的区别。

不支持 Prisma Migrate

目前,没有计划添加对Prisma Migrate的支持,因为 MongoDB 项目不依赖于需要使用额外工具管理更改的内部模式。@unique索引的管理是通过db push实现的。

不支持@@idautoincrement()

不支持@@id属性(多个字段的 ID),因为 MongoDB 中的主键始终位于模型的_id字段上。

不支持autoincrement()函数(创建递增的@id值),因为autoincrement()不适用于 MongoDB 中_id字段具有的ObjectID类型。

循环引用和引用操作

如果您的模型中存在循环引用(来自自关联或模型之间的一系列关系),并且您使用引用操作,则必须将引用操作设置为NoAction以防止无限循环操作。

有关更多详细信息,请参阅引用操作的特殊规则

副本集配置

MongoDB 仅允许您在副本集上启动事务。Prisma ORM 在内部使用事务以避免嵌套查询中的部分写入。这意味着我们继承了需要配置副本集的要求。

当您尝试在未配置副本集的部署中使用 Prisma ORM 的 MongoDB 连接器时,Prisma ORM 会显示消息Error: Transactions are not supported by this deployment。错误消息的完整文本如下

PrismaClientUnknownRequestError2 [PrismaClientUnknownRequestError]:
Invalid `prisma.post.create()` invocation in
/index.ts:9:21

6 await prisma.$connect()
7
8 // Create the first post
→ 9 await prisma.post.create(
Error in connector: Database error. error code: unknown, error message: Transactions are not supported by this deployment
at cb (/node_modules/@prisma/client/runtime/index.js:34804:17)
at processTicksAndRejections (internal/process/task_queues.js:97:5) {
clientVersion: '3.xx.0'
}

要解决此问题,我们建议您将部署更改为已配置副本集的部署。

一种简单的方法是使用MongoDB Atlas启动一个免费实例,该实例开箱即用地支持副本集。

还可以使用以下指南在本地运行副本集:https://www.mongodb.com/docs/manual/tutorial/convert-standalone-to-replica-set

MongoDB 和 Prisma 模式之间的类型映射

MongoDB 连接器将 Prisma ORM 数据模型中的标量类型映射到 MongoDB 的原生列类型,如下所示

或者,请参阅Prisma 模式参考,了解按 Prisma 类型组织的类型映射。

从 Prisma ORM 到 MongoDB 的原生类型映射

Prisma ORMMongoDB
Stringstring
Booleanbool
Intint
BigIntlong
Floatdouble
Decimal当前不支持
DateTimetimestamp
BytesbinData
Json

目前不支持的 MongoDB 类型

  • Decimal128
  • Undefined
  • DBPointer
  • Null
  • Symbol
  • MinKey
  • MaxKey
  • Object
  • Javascript
  • JavascriptWithScope
  • Regex

在内省时从 MongoDB 到 Prisma ORM 类型的映射

在内省 MongoDB 数据库时,Prisma ORM 使用相关的标量类型。某些特殊类型还会获得额外的原生类型注释

MongoDB(类型 | 别名)Prisma ORM支持原生数据库类型属性备注
objectIdString✔️@db.ObjectId

内省添加作为Unsupported字段的尚不支持的原生数据库类型

schema.prisma
model Example {
id String @id @default(auto()) @map("_id") @db.ObjectId
name String
regex Unsupported("RegularExpression")
}