prisma-database-setup

Prisma 資料庫設定

Prisma ORM 與各種資料庫提供者搭配的完整設定指南。

適用時機

請在以下情況參考此技能：

• 初始化新的 Prisma 專案
• 切換資料庫提供者
• 設定連線字串與環境變數
• 排解資料庫連線問題
• 設定資料庫特定功能
• 產生並實例化 Prisma Client

規則分類（依優先順序）

優先順序	分類	影響	前綴
1	提供者指南	關鍵	提供者名稱
2	Prisma Postgres	高	prisma-postgres
3	客戶端設定	關鍵	prisma-client-setup

系統需求

• Node.js 20.19.0+
• TypeScript 5.4.0+

Bun 執行環境

若使用 Bun，請以 bunx --bun prisma ... 執行 Prisma CLI 指令，讓 Prisma 使用 Bun 執行環境而非回退至 Node.js。

支援的資料庫

資料庫	提供者字串	備註
PostgreSQL	postgresql	預設，完整功能支援
MySQL	mysql	廣泛支援，部分 JSON 差異
SQLite	sqlite	本機檔案型，無列舉/純量列表
MongoDB	mongodb	MongoDB 專屬流程；請勿套用 SQL 驅動轉接器指南
SQL Server	sqlserver	Microsoft 生態系
CockroachDB	cockroachdb	分散式 SQL，相容 PostgreSQL
Prisma Postgres	postgresql	受管無伺服器資料庫

設定檔

設定檔的格式取決於提供者與 Prisma 主版本：

1. 所有提供者皆使用 prisma/schema.prisma。
2. Prisma 7 SQL 設定通常使用 prisma.config.ts 來設定資料來源 URL。
3. MongoDB 專案應停留在 Prisma 6.x，在 schema 中保留 url = env("DATABASE_URL")，並繼續使用傳統的 MongoDB 設定方式。

驅動轉接器

標準 SQL 工作流程使用驅動轉接器。請為您的資料庫選擇對應的轉接器與驅動，並將轉接器傳遞給 PrismaClient。

資料庫	轉接器	JS 驅動
PostgreSQL	@prisma/adapter-pg	pg
CockroachDB	@prisma/adapter-pg	pg
Prisma Postgres (Node.js)	@prisma/adapter-pg	pg
Prisma Postgres (邊緣/無伺服器)	@prisma/adapter-ppg	@prisma/ppg
MySQL / MariaDB	@prisma/adapter-mariadb	mariadb
SQLite	@prisma/adapter-better-sqlite3	better-sqlite3
SQLite (Turso/LibSQL)	@prisma/adapter-libsql	@libsql/client
SQL Server	@prisma/adapter-mssql	node-mssql

MongoDB 不應遵循 Prisma 7 SQL 轉接器工作流程。請使用最新的 Prisma 6.x 版本進行 MongoDB 專案，且不要為其安裝 SQL 的 @prisma/adapter-* 套件。

範例（PostgreSQL）：

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

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
const prisma = new PrismaClient({ adapter })

Prisma Client 設定（必要）

任何資料庫都必須安裝並產生 Prisma Client。

1. 安裝 Prisma CLI 與 Prisma Client：

   npm install prisma --save-dev
   npm install @prisma/client
   

2. 加入 generator 區塊（prisma-client 需要明確的輸出路徑）：

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

3. 產生 Prisma Client：

   npx prisma generate
   

4. 對於 SQL 提供者，使用資料庫特定的驅動轉接器實例化 Prisma Client：

   import { PrismaClient } from '../generated/client'
   import { PrismaPg } from '@prisma/adapter-pg'
   
   const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
   const prisma = new PrismaClient({ adapter })
   

5. 每次 schema 變更後重新執行 prisma generate。

快速參考

PostgreSQL

datasource db {
  provider = "postgresql"
}

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

MySQL

datasource db {
  provider = "mysql"
}

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

SQLite

datasource db {
  provider = "sqlite"
}

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

MongoDB

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

generator client {
  provider = "prisma-client-js"
}

對於 MongoDB，請停留在最新的 Prisma 6.x 版本，並將連線 URL 保留在 schema.prisma 中。請勿將 MongoDB 專案移至 Prisma 7 SQL 轉接器設定。

規則檔案

詳細設定說明請參閱各規則檔案：

references/postgresql.md
references/mysql.md
references/sqlite.md
references/mongodb.md
references/sqlserver.md
references/cockroachdb.md
references/prisma-postgres.md
references/prisma-client-setup.md

使用方式

根據您的資料庫選擇對應的提供者參考檔案，然後套用 references/prisma-client-setup.md 以完成客戶端產生與轉接器設定。對於 MongoDB，請使用 references/mongodb.md，而非複製 SQL 轉接器範例或 Prisma 7 設定模式。