Prisma ORM 与 MongoDB 快速入门

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 的完全兼容性。

先决条件

• 系统已安装 受支持版本的 Node.js
• 一个可以通过连接字符串访问的 MongoDB 数据库

1. 创建新项目

创建一个项目目录并进入该目录

mkdir hello-prisma
cd hello-prisma

初始化一个 TypeScript 项目

npm init -y
npm install typescript tsx @types/node --save-dev
npx tsc --init

2. 安装所需的依赖项

安装本快速入门所需的软件包

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

为什么选择 Prisma v6.19？

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

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

每个包的作用如下

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

注意

MongoDB 不需要驱动程序适配器，因为 Prisma ORM 直接连接到 MongoDB。

3. 配置 ESM 支持

更新 tsconfig.json 以兼容 ESM

tsconfig.json

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "node",
    "target": "ES2023",
    "strict": true,
    "esModuleInterop": true,
    "ignoreDeprecations": "6.0"
  }
}

更新 package.json 以启用 ESM

package.json

{
  "type": "module",
}

4. 初始化 Prisma ORM

现在，您可以通过在 Prisma CLI 前面加上 npx 来调用它

npx prisma

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

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

此命令执行以下操作

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

注意

本指南稍后运行 npx prisma generate 时，Prisma Client 将在 generated/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")
}

使用你的 MongoDB 连接字符串更新 .env 文件。

.env

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

提示

将 username、password、cluster 和 mydb 替换为你的实际 MongoDB 凭据和数据库名称。你可以从 MongoDB Atlas 或你的 MongoDB 部署获取连接字符串。

5. 定义您的数据模型

打开 prisma/schema.prisma 并添加以下模型

prisma/schema.prisma

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

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

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

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

6. 将你的 Schema 推送到 MongoDB

MongoDB 不像关系数据库那样支持迁移。相反，使用 db push 来同步你的 schema。

npx prisma db push

此命令

• 根据你的 schema 在 MongoDB 中创建集合。
• 自动生成 Prisma Client。

信息

与关系数据库不同，MongoDB 使用灵活的 schema。db push 命令确保你的 Prisma schema 反映在数据库中，而无需创建迁移文件。

7. 实例化 Prisma Client

现在你已经安装了所有依赖项，可以实例化 Prisma Client 了。

lib/prisma.ts

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

const prisma = new PrismaClient()

export { prisma }

8. 编写您的第一个查询

创建一个 script.ts 文件来测试您的设置

script.ts

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

async function main() {
  // Create a new user with a post
  const user = await prisma.user.create({
    data: {
      name: 'Alice',
      email: 'alice@prisma.io',
      posts: {
        create: {
          title: 'Hello World',
          content: 'This is my first post!',
          published: true,
        },
      },
    },
    include: {
      posts: true,
    },
  })
  console.log('Created user:', user)

  // Fetch all users with their posts
  const allUsers = await prisma.user.findMany({
    include: {
      posts: true,
    },
  })
  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. 探索你的数据

你可以使用 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 上与其他开发者联系

故障排除

连接器错误：SCRAM 失败：认证失败。

如果你看到 连接器错误：SCRAM 失败：认证失败。 错误消息，可以通过在连接字符串末尾添加 ?authSource=admin 来指定认证的源数据库。

原始查询失败。错误代码 8000 (AtlasError)：不允许使用空数据库名称。

如果你看到 原始查询失败。代码：未知。消息：类型：命令失败：错误代码 8000 (AtlasError)：不允许使用空数据库名称。 错误消息，请确保在数据库 URL 后附加数据库名称。你可以在此 GitHub issue 中找到更多信息。

更多信息

• MongoDB 数据库连接器
• MongoDB 数据建模模式
• MongoDB 部署注意事项