跳到主要內容

Prisma Pulse 入門指南

先決條件​

資訊

Prisma Pulse 目前支援 PostgreSQL。我們很想知道您希望接下來支援哪些資料庫。

若要開始使用 Pulse，您需要準備以下項目

1. 在平台主控台中啟用 Pulse​

1.1. 選擇您要啟用 Pulse 的環境​

開啟，導覽至您選擇的工作區，然後選取專案並選擇您要在其中啟用 Pulse 的環境。

如果您在工作區中還沒有專案，您可以建立一個新的專案。

1.2. 啟用 Pulse​

在您選擇的專案環境中，按一下 啟用 Pulse 按鈕。

1.3. 設定 Pulse​

Pulse 的 設定 畫面要求您

  1. 提供您的 資料庫連線字串
  2. 選取應託管 Pulse 的 區域
  3. 如果您的資料庫使用 IP 許可清單，請啟用 靜態 IP 。深入瞭解如何為 Pulse 啟用靜態 IP，請按一下此處。
  4. 決定是否要使用 資料庫複寫 的 自動設定 (僅適用於付費方案)
  5. 確保 事件持久性 已啟用，以便將交付保證與 .stream() 搭配使用 (或者如果您想使用 .subscribe() 取得完全暫時性事件而沒有交付保證，則停用它)

完成後，按一下畫面底部的 啟用 Pulse 按鈕。這將測試與您資料庫的連線能力。

1.4. 產生 API 金鑰​

資訊

如果您目前環境已經有 API 金鑰，您可以略過此步驟，並使用現有的 API 金鑰來使用 Prisma Pulse。

您可以按一下 產生 API 金鑰 按鈕來產生 API 金鑰。將 API 金鑰儲存在安全的位置，或將其新增至您專案的 .env 檔案

.env
PULSE_API_KEY="your_secure_pulse_api_key"

之後您將無法再次存取相同的 API 金鑰。

2. 將 Pulse 新增至您的應用程式​

啟用 Pulse 後，繼續執行這些步驟，將 Pulse 整合到您的應用程式中。您也可以利用我們在 GitHub 上的範例儲存庫 作為參考指南。

2.1. 安裝 Pulse Client 擴充功能​

資訊

Pulse 需要 Prisma Client 版本 4.16.1 或更高版本，以及 @prisma/extension-pulse 版本 1.1.0 或更高版本。

安裝 Pulse 擴充功能

npm install @prisma/extension-pulse@latest

2.2. 使用 Pulse 擴充功能擴充您的 Prisma Client 執行個體​

新增以下內容，以使用 Prisma Pulse 擴充功能擴充您現有的 Prisma Client 執行個體

import { PrismaClient } from '@prisma/client'
import { withPulse } from '@prisma/extension-pulse'

const prisma = new PrismaClient().$extends(
  withPulse({ apiKey: process.env.PULSE_API_KEY })
)

執行階段特定匯入​

如果您在 tsconfig.json 檔案中使用 "moduleResolution":"bundler"，且您的 Pulse 擴充功能版本為 1.2.0 或更高版本，請根據您的執行階段匯入 Pulse 擴充功能

import { withPulse } from '@prisma/extension-pulse/node';
警告

使用正確的執行階段特定匯入可防止下列錯誤

Cannot find module '@prisma/extension-pulse' or its corresponding type declarations.

2.3. 建立您的第一個 Pulse 串流​

套用 Pulse 擴充功能後，您可以在 Prisma Schema 中定義的任何模型上使用 Pulse 的 .stream() 方法，以串流資料變更事件。

在以下範例中，假設您的 Prisma schema 具有 User 模型。為 User 模型建立串流，以監聽該資料表上的任何變更事件

import { PrismaClient } from '@prisma/client'
import { withPulse } from '@prisma/extension-pulse'

const prisma = new PrismaClient().$extends(
  withPulse({ apiKey: process.env.PULSE_API_KEY })
)

async function main() {
  const stream = await prisma.user.stream()

  for await (const event of stream) {
    console.log('just received an event:', event)
  }
}

main()

3. 測試您的串流​

執行上述程式碼片段後，您可以透過在資料庫中建立、更新或刪除 User 記錄來測試串流。

您可以使用 Prisma Studio (執行 npx prisma studio) 或使用您選擇的任何其他資料庫用戶端 (例如 Postico 或 psql)。

如果一切正常，您應該會在終端機中看到事件記錄，您可以在其中看到上面的程式碼片段。 🎉

後續步驟​

您可以嘗試在您的 Pulse 串流上使用更多篩選器，例如

僅串流 create 事件:

const stream = await prisma.user.stream({
  create: { },
})

僅串流 update 事件:

const stream = await prisma.user.stream({
  update: { },
})

僅串流 delete 事件:

const stream = await prisma.user.stream({
  delete: { },
})

Pulse 提供比這些更精細的篩選器。您可以在 API 參考中探索這些篩選器。

需要協助嗎？​

在我們的 Discord 的 #help-and-questions 頻道中與我們聯絡，或與我們的社群交流，以瞭解其他人如何使用 Pulse。