將 Prisma ORM 加入至現有的 PlanetScale 專案

PlanetScale 是一個無伺服器（serverless）資料庫平台。本指南涵蓋了基於 Vitess 建構並提供資料庫分支、非阻塞式架構變更及自動備份功能的 PlanetScale MySQL。在本指南中，您將學習如何將 Prisma ORM 加入至現有的 TypeScript 專案、連接到 PlanetScale MySQL、對現有的資料庫架構進行內省（Introspection），並開始使用型別安全的 Prisma Client 進行查詢。

注意

PlanetScale 也提供 PostgreSQL 資料庫。如果您使用的是 PlanetScale PostgreSQL，請改為參考加入至現有的 PostgreSQL 專案指南。

先決條件

您需要

• Node.js v20.19+、v22.12+ 或 v24.0+ 已安裝於您的機器上
• JavaScript 或 TypeScript 的基礎知識

1. 設定 Prisma ORM

導航至您現有的專案目錄並安裝必要的相依套件

npm install prisma @types/node --save-dev
npm install @prisma/client @prisma/adapter-planetscale undici dotenv

以下是各個套件的功能說明

• prisma - 用於執行 prisma init、prisma db pull 和 prisma generate 等指令的 Prisma CLI
• @prisma/client - 用於查詢資料庫的 Prisma Client 函式庫
• @prisma/adapter-planetscale - 將 Prisma Client 連接到資料庫的 PlanetScale 驅動程式轉接器
• undici - PlanetScale 轉接器所需的快速 HTTP/1.1 用戶端
• dotenv - 從您的 .env 檔案載入環境變數

2. 初始化 Prisma ORM

透過建立 Prisma Schema 檔案來設定您的 Prisma ORM 專案，請執行以下指令

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

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

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

產生的 prisma.config.ts 檔案如下所示

prisma.config.ts

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

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

產生的 Schema 使用了以 ESM 為優先的 prisma-client 產生器，並設定了自訂的輸出路徑

prisma/schema.prisma

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

datasource db {
  provider     = "mysql"
  relationMode = "prisma"
}

資訊

由於 PlanetScale 不支援外鍵限制，因此需要設定 relationMode = "prisma"。

3. 連接您的資料庫

使用您的 PlanetScale 連接網址更新 .env 檔案

.env

DATABASE_URL="mysql://username:password@host.connect.psdb.cloud/mydb?sslaccept=strict"

您可以在 PlanetScale 控制面板中找到您的連接字串。

4. 內省您的資料庫

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

npx prisma db pull

此指令會讀取 DATABASE_URL 環境變數、連接至您的資料庫，並對資料庫結構進行內省。接著，它會將資料庫結構從 SQL 轉換為 Prisma Schema 中的資料模型。

內省完成後，您的 Prisma Schema 將包含代表現有資料庫資料表的模型。

5. 產生 Prisma ORM 型別

根據內省後的 Schema 產生 Prisma Client

npx prisma generate

這會在 generated/prisma 目錄中建立一個為您的資料庫結構量身打造、具備型別安全的 Prisma Client。

6. 實例化 Prisma Client

建立一個工具檔案來實例化 Prisma Client。您需要將 Prisma ORM 驅動程式轉接器的實例傳遞給 PrismaClient 建構函式

lib/prisma.ts

import "dotenv/config";
import { PrismaPlanetScale } from '@prisma/adapter-planetscale'
import { PrismaClient } from '../generated/prisma/client'
import { fetch as undiciFetch } from 'undici'

const adapter = new PrismaPlanetScale({ url: process.env.DATABASE_URL, fetch: undiciFetch })
const prisma = new PrismaClient({ adapter })

export { prisma }

7. 查詢您的資料庫

現在您可以使用 Prisma Client 來查詢資料庫。建立一個 script.ts 檔案

script.ts

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

async function main() {
  // Example: Fetch all records from a table
  // 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. 演進您的架構

PlanetScale 使用分支工作流程而非傳統的遷移（migrations）。若要對資料庫架構進行變更：

8.1. 更新您的 Prisma schema 檔案

更新您的 Prisma Schema 檔案以反映您想要對資料庫結構進行的變更。例如，新增一個模型

prisma/schema.prisma

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  authorId  Int
  author    User     @relation(fields: [authorId], references: [id])
}

model User {
  id    Int    @id @default(autoincrement())
  email String @unique
  name  String?
  posts Post[]
}

8.2. 將變更推送至您的開發分支：

npx prisma db push

此指令將：

• 將架構變更套用到您的 PlanetScale 資料庫
• 重新產生 Prisma Client

資訊

對於正式環境部署，請使用 PlanetScale 的分支工作流程來建立部署請求。

9. 使用 Prisma Studio 探索您的資料

Prisma Studio 是一個資料庫視覺化編輯器。使用以下指令啟動它

npx prisma studio --config ./prisma.config.ts

這將開啟一個網頁介面，您可以在其中檢視和編輯資料。

支援的資料庫

Prisma Studio 目前支援 PostgreSQL、MySQL 和 SQLite。更多詳細資訊，請參閱Prisma Studio 支援的資料庫。

後續步驟

您已成功設定 Prisma ORM。接下來您可以探索以下內容：

• 深入了解 Prisma Client：探索 Prisma Client API 以進行進階查詢、篩選和關聯處理
• 資料庫遷移：了解 Prisma Migrate 以便演進您的資料庫結構
• 效能最佳化：發現查詢最佳化技巧
• 建構完整應用程式：查看我們的框架指南，將 Prisma ORM 整合至 Next.js、Express 等框架
• 加入社群：在 Discord 上與其他開發者交流

更多資訊

• PlanetScale 資料庫連接器
• Prisma Config 參考
• 資料庫內省
• PlanetScale 分支工作流程