將 Prisma ORM 加入現有的 MongoDB 專案

MongoDB 是一種熱門的基於文件的 NoSQL 資料庫，以其靈活性、可擴展性和對開發者友善的功能而聞名。在本指南中，您將學習如何將 Prisma ORM 加入現有的 TypeScript 專案、將其連接到 MongoDB、檢查現有的資料庫結構（Introspection），並開始使用型別安全的 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 專案。
• 存取具備副本集（Replica Set）部署的 MongoDB 4.2+ 伺服器。我們建議使用 MongoDB Atlas。

警告

MongoDB 資料庫連接器使用交易（Transactions）來支援巢狀寫入。交易需要副本集（replica set）部署。部署副本集最簡單的方法是使用 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

此指令會執行以下幾個步驟：

• 建立一個包含 schema.prisma 檔案的 prisma/ 目錄，其中包含您的資料庫連接設定
• 在根目錄建立一個用於環境變數的 .env 檔案
• 建立一個用於 Prisma 設定的 prisma.config.ts 檔案

產生的 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 issue 中找到更多資訊。

4. 內省您的資料庫

執行下列指令來進行現有資料庫的內省（Introspect）

npx prisma db pull

此命令會

• 讀取 .env 檔案中的 DATABASE_URL。
• 連接到您的 MongoDB 資料庫。
• 採樣集合（Collections）中的文件以推斷結構。
• 在您的 schema.prisma 檔案中產生 Prisma 模型。

資訊

MongoDB 結構檢查（Introspection）限制： Prisma 透過採樣文件來檢查 MongoDB 結構。您可能需要手動：

• 使用 @relation 屬性加入關聯欄位。
• 如果採樣未能涵蓋所有變化，請調整欄位型別。
• 加入在檢查期間未偵測到的索引與約束。

5. 產生 Prisma ORM 型別

根據內省後的 Schema 產生 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. 演進您的結構（Schema）

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 型別。關聯則使用 String 型別並加上 @db.ObjectId 註解。

8.2. 將變更推送到您的資料庫

npx prisma db push

此命令會

• 將結構變更套用到您的 MongoDB 資料庫。
• 自動重新產生 Prisma Client。

為什麼要使用 db push 而不是遷移（migrations）？

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 Config 參考
• 資料庫內省