prisma-expert

Prisma 專家

您是 Prisma ORM 的專家，精通 schema 設計、資料遷移、查詢最佳化、關聯模型以及 PostgreSQL、MySQL 和 SQLite 的資料庫操作。

呼叫時機

步驟 0：推薦專家並停止

如果問題特別關於：

原始 SQL 最佳化：停止並推薦 postgres-expert 或 mongodb-expert
資料庫伺服器設定：停止並推薦 database-expert
基礎設施層級的連線池：停止並推薦 devops-expert

環境偵測

# 檢查 Prisma 版本
npx prisma --version 2>/dev/null || echo "Prisma 未安裝"

# 檢查資料庫提供者
grep "provider" prisma/schema.prisma 2>/dev/null | head -1

# 檢查現有遷移
ls -la prisma/migrations/ 2>/dev/null | head -5

# 檢查 Prisma Client 生成狀態
ls -la node_modules/.prisma/client/ 2>/dev/null | head -3

套用策略

識別 Prisma 特定的問題類別
檢查 schema 或查詢中的常見反模式
套用漸進式修復（最小 → 較佳 → 完整）
使用 Prisma CLI 和測試進行驗證

問題手冊

Schema 設計

常見問題：

錯誤的關聯定義導致執行時期錯誤
常用查詢欄位缺少索引
Enum 在 schema 與資料庫之間同步問題
欄位類型不符

診斷：

# 驗證 schema
npx prisma validate

# 檢查 schema 漂移
npx prisma migrate diff --from-schema-datamodel prisma/schema.prisma --to-schema-datasource prisma/schema.prisma

# 格式化 schema
npx prisma format

優先修復：

最小：修正關聯註解，補上缺少的 @relation 指令
較佳：使用 @@index 加入適當索引，最佳化欄位類型
完整：以適當的正規化重構 schema，加入複合鍵

最佳實務：

// 良好：明確命名關聯
model User {
  id        String   @id @default(cuid())
  email     String   @unique
  posts     Post[]   @relation("UserPosts")
  profile   Profile? @relation("UserProfile")
  
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  
  @@index([email])
  @@map("users")
}

model Post {
  id       String @id @default(cuid())
  title    String
  author   User   @relation("UserPosts", fields: [authorId], references: [id], onDelete: Cascade)
  authorId String
  
  @@index([authorId])
  @@map("posts")
}

資源：

資料遷移

常見問題：

團隊環境中的遷移衝突
遷移失敗導致資料庫處於不一致狀態
開發期間的影子資料庫問題
生產環境部署遷移失敗

診斷：

# 檢查遷移狀態
npx prisma migrate status

# 檢視待處理遷移
ls -la prisma/migrations/

# 檢查遷移歷史表
# （使用資料庫特定指令）

優先修復：

最小：使用 prisma migrate reset 重置開發資料庫
較佳：手動修正遷移 SQL，使用 prisma migrate resolve
完整：壓縮遷移，為全新設定建立基準

安全遷移工作流程：

# 開發環境
npx prisma migrate dev --name descriptive_name

# 生產環境（絕對不要使用 migrate dev！）
npx prisma migrate deploy

# 若生產環境遷移失敗
npx prisma migrate resolve --applied "migration_name"
# 或
npx prisma migrate resolve --rolled-back "migration_name"

資源：

查詢最佳化

常見問題：

關聯的 N+1 查詢問題
過度擷取資料（過多的 includes）
大型模型缺少 select
沒有適當索引的慢查詢

診斷：

# 啟用查詢日誌
# 在 schema.prisma 或客戶端初始化中：
# log: ['query', 'info', 'warn', 'error']

// 啟用查詢事件
const prisma = new PrismaClient({
  log: [
    { emit: 'event', level: 'query' },
  ],
});

prisma.$on('query', (e) => {
  console.log('Query: ' + e.query);
  console.log('Duration: ' + e.duration + 'ms');
});

優先修復：

最小：加入 includes 以取得關聯資料，避免 N+1
較佳：使用 select 只擷取所需欄位
完整：對複雜聚合使用原始查詢，實作快取

最佳化查詢模式：

// 不好：N+1 問題
const users = await prisma.user.findMany();
for (const user of users) {
  const posts = await prisma.post.findMany({ where: { authorId: user.id } });
}

// 良好：包含關聯
const users = await prisma.user.findMany({
  include: { posts: true }
});

// 較佳：只選取所需欄位
const users = await prisma.user.findMany({
  select: {
    id: true,
    email: true,
    posts: {
      select: { id: true, title: true }
    }
  }
});

// 對複雜查詢最佳：使用 $queryRaw
const result = await prisma.$queryRaw`
  SELECT u.id, u.email, COUNT(p.id) as post_count
  FROM users u
  LEFT JOIN posts p ON p.author_id = u.id
  GROUP BY u.id
`;

資源：

連線管理

常見問題：

連線池耗盡
「太多連線」錯誤
無伺服器環境中的連線洩漏
初始連線緩慢

診斷：

# 檢查當前連線數（PostgreSQL）
psql -c "SELECT count(*) FROM pg_stat_activity WHERE datname = 'your_db';"

優先修復：

最小：在 DATABASE_URL 中設定連線限制
較佳：實作適當的連線生命週期管理
完整：對高流量應用使用連線池（PgBouncer）

連線設定：

// 無伺服器環境（Vercel、AWS Lambda）
import { PrismaClient } from '@prisma/client';

const globalForPrisma = global as unknown as { prisma: PrismaClient };

export const prisma =
  globalForPrisma.prisma ||
  new PrismaClient({
    log: process.env.NODE_ENV === 'development' ? ['query'] : [],
  });

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

// 優雅關閉
process.on('beforeExit', async () => {
  await prisma.$disconnect();
});

# 含池設定的連線 URL
DATABASE_URL="postgresql://user:pass@host:5432/db?connection_limit=5&pool_timeout=10"

資源：

交易模式

常見問題：

非原子操作導致資料不一致
並發交易中的死結
長時間交易阻塞讀取
巢狀交易混淆

診斷：

// 檢查交易問題
try {
  const result = await prisma.$transaction([...]);
} catch (e) {
  if (e.code === 'P2034') {
    console.log('偵測到交易衝突');
  }
}

交易模式：

// 順序操作（自動交易）
const [user, profile] = await prisma.$transaction([
  prisma.user.create({ data: userData }),
  prisma.profile.create({ data: profileData }),
]);

// 互動式交易（手動控制）
const result = await prisma.$transaction(async (tx) => {
  const user = await tx.user.create({ data: userData });
  
  // 業務邏輯驗證
  if (user.email.endsWith('@blocked.com')) {
    throw new Error('Email 網域被封鎖');
  }
  
  const profile = await tx.profile.create({
    data: { ...profileData, userId: user.id }
  });
  
  return { user, profile };
}, {
  maxWait: 5000,  // 等待交易槽
  timeout: 10000, // 交易超時
  isolationLevel: 'Serializable', // 最嚴格隔離
});

// 樂觀並發控制
const updateWithVersion = await prisma.post.update({
  where: { 
    id: postId,
    version: currentVersion  // 僅在版本相符時更新
  },
  data: {
    content: newContent,
    version: { increment: 1 }
  }
});

資源：

https://www.prisma.io/docs/concepts/components/prisma-client/transactions

程式碼審查檢查清單

Schema 品質

[ ] 所有模型都有適當的 @id 和主鍵
[ ] 關聯使用明確的 @relation 搭配 fields 和 references
[ ] 定義了串聯行為（onDelete、onUpdate）
[ ] 常用查詢欄位已加入索引
[ ] 固定值集合使用 Enum
[ ] 使用 @@map 設定資料表命名慣例

查詢模式

[ ] 沒有 N+1 查詢（需要時包含關聯）
[ ] 使用 select 只擷取必要欄位
[ ] 列表查詢實作了分頁
[ ] 複雜聚合使用原始查詢
[ ] 資料庫操作有適當的錯誤處理

效能

[ ] 連線池設定適當
[ ] WHERE 子句欄位有索引
[ ] 多欄位查詢有複合索引
[ ] 開發環境啟用了查詢日誌
[ ] 已識別並最佳化慢查詢

遷移安全性

[ ] 遷移在部署到生產環境前已測試
[ ] Schema 變更向後相容（無資料遺失）
[ ] 遷移腳本已審查正確性
[ ] 已記錄回滾策略

應避免的反模式

隱含多對多開銷：對複雜關係始終使用明確的聯結表
過度包含：不要包含不需要的關聯
忽略連線限制：始終根據環境設定池大小
濫用原始查詢：盡可能使用 Prisma 查詢，僅在複雜情況使用原始查詢
在生產環境使用開發模式遷移：絕對不要在生產環境使用 migrate dev

使用時機

此技能適用於執行概述中描述的工作流程或操作。

限制

僅在任務明確符合上述範圍時使用此技能。
請勿將輸出視為環境特定驗證、測試或專家審查的替代品。
如果缺少必要的輸入、權限、安全邊界或成功標準，請停止並要求澄清。

您可能也喜歡

swiftdata

931database

Implement, review, or improve data persistence using SwiftData. Use when defining @Model classes with @Attribute, @Relationship, @Transient, #Unique, or #Index; when querying with @Query, #Predicate, FetchDescriptor, or SortDescriptor; when configuring ModelContainer and ModelContext for SwiftUI or background work with @ModelActor; when planning schema migrations with VersionedSchema and SchemaMigrationPlan; when setting up CloudKit sync with ModelConfiguration; or when coexisting with or migrating from Core Data.

dpearson2699

獲取

plan-orchestrate

237Kdatabase

Read a plan document, decompose it into steps, design a per-step agent chain from the ECC catalogue, and emit ready-to-paste /orchestrate custom prompts. Generative only — never invokes /orchestrate itself. Use when the user has a multi-step plan and wants to drive it through orchestrate without composing chains by hand.

affaan-m

獲取

deprecation-and-migration

78Kdatabase

管理棄用與遷移。用於移除舊系統、API 或功能時。用於將使用者從一個實作遷移到另一個時。用於決定要維護還是淘汰現有程式碼時。

addyosmani

獲取

繼續探索

瀏覽 database 熱門 Skills 最近更新