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 与关系数据库相同。您仍然可以
- 使用 Prisma Schema Language 对您的数据库进行建模
- 使用
mongodb
数据库连接器 连接到您的数据库 - 如果您的项目已经拥有 MongoDB 数据库,则可以使用 内省
- 使用
db push
将架构中的更改推送到数据库 - 在您的应用程序中使用 Prisma Client,以基于 Prisma Schema 以类型安全的方式查询数据库
需要考虑的差异
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
模型
model User {
id String @id @default(auto()) @map("_id") @db.ObjectId
email String
}
您可以使用多种策略来迁移此模式
-
“按需”更新:使用此策略,您和您的团队已同意可以根据需要对模式进行更新。但是,为了避免由于数据和模式之间不一致而导致迁移失败,团队中达成一致意见,即添加的任何新字段都明确定义为可选的。
在上面的场景中,您可以将可选的
phoneNumber
字段添加到 Prisma 模式中的User
模型prisma/schema.prismamodel User {
id String @id @default(auto()) @map("_id") @db.ObjectId
email String
phoneNumber String?
}然后使用
npx prisma generate
命令重新生成 Prisma Client。接下来,更新您的应用程序以反映新字段,并重新部署您的应用程序。由于
phoneNumber
字段是可选的,因此您仍然可以查询尚未定义电话号码的旧用户。数据库中的记录将“按需”更新,因为应用程序的用户开始在新字段中输入其电话号码。另一种选择是在必填字段上添加默认值,例如
prisma/schema.prismamodel 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 数据库,User
和 Post
。这些集合中的数据具有以下格式,其中 userId
字段将用户链接到帖子
User
集合
_id
字段,类型为objectId
email
字段,类型为string
Post
集合
_id
字段,类型为objectId
title
字段,类型为string
userId
,类型为objectID
使用 db pull
进行内省时,将按如下方式提取到 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
}
这缺少 User
和 Post
模型之间的关系。要解决此问题,请使用 userId
作为 fields
值,手动将 user
字段添加到 Post
模型中,并使用 @relation
属性将其链接到 User
模型,以及将 posts
字段添加到 User
模型作为反向关系
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)
{
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)
{
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)
[
{
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)
[
{
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
块
datasource db {
provider = "mongodb"
url = env("DATABASE_URL")
}
传递给 datasource
块的字段是
连接详细信息
连接 URL
MongoDB 连接 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 和关系标量字段)
- 必须是
String
或Bytes
类型 - 必须包含
@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
实现的。
不支持@@id
和autoincrement()
不支持@@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 ORM | MongoDB |
---|---|
String | string |
Boolean | bool |
Int | int |
BigInt | long |
Float | double |
Decimal | 当前不支持 |
DateTime | timestamp |
Bytes | binData |
Json |
目前不支持的 MongoDB 类型
Decimal128
Undefined
DBPointer
Null
Symbol
MinKey
MaxKey
Object
Javascript
JavascriptWithScope
Regex
在内省时从 MongoDB 到 Prisma ORM 类型的映射
在内省 MongoDB 数据库时,Prisma ORM 使用相关的标量类型。某些特殊类型还会获得额外的原生类型注释
MongoDB(类型 | 别名) | Prisma ORM | 支持 | 原生数据库类型属性 | 备注 |
---|---|---|---|---|
objectId | String | ✔️ | @db.ObjectId |
内省添加作为Unsupported
字段的尚不支持的原生数据库类型
model Example {
id String @id @default(auto()) @map("_id") @db.ObjectId
name String
regex Unsupported("RegularExpression")
}