將 Prisma ORM 加入現有的 PostgreSQL 專案

PostgreSQL 是一款廣受歡迎的開源關聯式資料庫，以其可靠性、強大的功能與高效能而聞名。在本指南中，您將學習如何將 Prisma ORM 加入現有的 TypeScript 專案、連接至 PostgreSQL、內省（Introspect）現有的資料庫結構，並開始使用具備型別安全的 Prisma Client 進行查詢。

先決條件

您需要

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

1. 設定 Prisma ORM

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

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

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

• prisma - 用於執行 prisma init、prisma db pull 和 prisma generate 等指令的 Prisma CLI
• @prisma/client - 用於查詢資料庫的 Prisma Client 函式庫
• @prisma/adapter-pg - 將 Prisma Client 連接至資料庫的 node-postgres 驅動程式轉接器
• pg - node-postgres 資料庫驅動程式
• @types/pg - node-postgres 的 TypeScript 型別定義
• dotenv - 從您的 .env 檔案載入環境變數

2. 初始化 Prisma ORM

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

npx prisma init --datasource-provider postgresql --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 = "postgresql"
}

3. 連接您的資料庫

使用您的 PostgreSQL 連接 URL 更新 .env 檔案

.env

DATABASE_URL="postgresql://user:password@localhost:5432/mydb?schema=public"

PostgreSQL 的連接 URL 格式如下所示

postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA

4. 內省您的資料庫

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

npx prisma db pull

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

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

5. 建立資料庫基準（Baseline）

若要對現有資料庫使用 Prisma Migrate，您需要建立資料庫基準（Baseline）。

首先，建立一個 migrations 目錄

mkdir -p prisma/migrations/0_init

接著，使用 prisma migrate diff 產生遷移檔案

npx prisma migrate diff --from-empty --to-schema prisma/schema.prisma --script > prisma/migrations/0_init/migration.sql

檢查產生的遷移檔案，確保其與您的資料庫結構相符。

然後，將此遷移標記為已套用

npx prisma migrate resolve --applied 0_init

現在您已為目前的資料庫結構建立了基準。

6. 產生 Prisma ORM 型別

根據內省後的 Schema 產生 Prisma Client

npx prisma generate

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

7. 實例化 Prisma Client

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

lib/prisma.ts

import "dotenv/config";
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from '../generated/prisma/client'

const connectionString = `${process.env.DATABASE_URL}`

const adapter = new PrismaPg({ connectionString })
const prisma = new PrismaClient({ adapter })

export { prisma }

8. 查詢您的資料庫

現在您可以使用 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

9. 演進您的 Schema

若要變更資料庫結構：

9.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[]
}

9.2. 建立並套用遷移：

npx prisma migrate dev --name your_migration_name

此指令將：

• 建立新的 SQL 遷移檔案
• 將遷移套用至您的資料庫
• 重新產生 Prisma Client

10. 使用 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 上與其他開發者交流

更多資訊

• PostgreSQL 資料庫連接器
• Prisma Config 參考
• 資料庫內省
• Prisma Migrate