跳到主要內容

快速入門

Prisma Postgres

在本快速入門指南中，您將學習如何在純 TypeScript 專案中，從頭開始使用 Prisma ORM 和 Prisma Postgres 資料庫。它涵蓋以下工作流程

先決條件​

要成功完成本教學課程，您需要

  • a(PDP) 帳戶
  • Node.js 安裝在您的機器上（請參閱系統需求以了解官方支援的版本）

1. 在 Platform Console 中設定 Prisma Postgres 資料庫​

請按照以下步驟建立您的 Prisma Postgres 資料庫

  1. 登入並開啟 Console。
  2. 在您選擇的工作區中，按一下 New project 按鈕。
  3. 在 Name 欄位中輸入專案名稱，例如 hello-ppg。
  4. 在 Prisma Postgres 區段中，按一下 Get started 按鈕。
  5. 在 Region 下拉式選單中，選取最接近您目前位置的區域，例如 美國東部 (維吉尼亞北部)。
  6. 按一下 Create project 按鈕。

此時，您將被重新導向至 Database 頁面，您需要在該頁面等待幾秒鐘，直到資料庫的狀態從 PROVISIONING 變更為 CONNECTED。

一旦綠色的 CONNECTED 標籤出現，您的資料庫即可使用！

2. 下載範例並安裝相依性​

複製 Console 中顯示的 try-prisma 命令，將其貼到您的終端機並執行。

作為參考，以下是命令的外觀

npx try-prisma@latest \
  --template databases/prisma-postgres \
  --name hello-prisma \
  --install npm

一旦 try-prisma 命令終止，請導覽至專案目錄

cd hello-prisma

3. 設定資料庫連線 URL​

資料庫連線和 Pulse API 金鑰透過 .env 檔案中的環境變數進行設定。

首先，將現有的 .env.example 檔案重新命名為 .env

mv .env.example .env

然後，在 Platform console 中的專案環境中，在 Set up database access 區段中找到您的資料庫憑證，複製 DATABASE_URL 環境變數並將其貼到 .env 檔案中。

作為參考，檔案現在應如下所示

DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=ey...."
PULSE_API_KEY=""

暫時不用擔心 PULSE_API_KEY 環境變數，您稍後會設定它。

4. 建立資料庫表格（透過 schema 遷移）​

接下來，您需要在資料庫中建立表格。您可以透過使用 Prisma CLI 的以下命令建立並執行 schema 遷移來完成此操作

npx prisma migrate dev --name init

這會將您的 Prisma schema 中定義的 User 和 Post 模型對應到您的資料庫。您也可以檢閱已執行的 SQL 遷移，並在新建立的 prisma/migrations 目錄中建立表格。

5. 使用 Prisma ORM 執行查詢​

src/queries.ts 腳本包含許多 CRUD 查詢，這些查詢將在您的資料庫中寫入和讀取資料。您可以透過在終端機中執行以下命令來執行它

npm run queries

一旦腳本完成，您可以檢查終端機中的日誌，或使用 Prisma Studio 來探索在資料庫中建立的記錄

npx prisma studio

6. 使用 Prisma Accelerate 探索快取​

src/caching.ts 腳本包含一個範例查詢，該查詢使用 Stale-While-Revalidate (SWR) 和 Time-To-Live (TTL) 來使用 Prisma Accelerate 快取資料庫查詢。您可以如下執行它

npm run caching

請注意執行查詢所花費的時間，例如

The query took 2009.2467149999998ms.

現在，再次執行腳本

npm run caching

您會注意到這次查詢所花費的時間會短很多，例如

The query took 300.5655280000001ms.

7. 使用 Prisma Pulse 觀察資料庫中的即時事件​

src/realtime.ts 腳本包含一個示範，用於透過 Prisma Pulse 從資料庫接收即時變更事件。

在您可以執行它之前，您需要在 Console 中啟用 Prisma Postgres 的即時功能

  1. 重新開啟您的專案在.
  2. 在側邊欄中選取 Pulse 標籤。
  3. 找到並按一下 Enable Pulse 按鈕。
  4. 在 Add Pulse to your application 區段中，按一下 Generate API key 按鈕。
  5. 複製 PULSE_API_KEY 環境變數並將其貼到您的 .env 檔案中。

作為參考，您的 .env 檔案現在應如下所示

DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=ey...."
PULSE_API_KEY="ey..."

您現在可以如下啟動腳本

npm run realtime

腳本現在建立了一個 串流，每當在 User 表格上發生寫入操作（即建立、更新或刪除）時，它將接收資料庫事件並將其列印到主控台。

要測試串流，您可以開啟 Prisma Studio

npx prisma studio

... 並對 User 表格進行變更，例如建立新記錄。一旦您儲存變更，您應該會在終端機中看到類似以下的輸出

Received an event: {
  action: 'create',
  created: { id: 3, email: 'burk@prisma.io', name: 'Nikolas' },
  id: '01JAFNSZHQRDTW773BCAA9G7FJ'
}

8. 後續步驟​

在本快速入門指南中，您學習了如何在純 TypeScript 專案中開始使用 Prisma ORM。請隨意自行探索更多 Prisma Client API，例如，在 findMany 查詢中包含篩選、排序和分頁選項，或探索更多操作，例如 update 和 delete 查詢。

在 Prisma Studio 中探索資料​

Prisma ORM 隨附內建 GUI，用於檢視和編輯資料庫中的資料。您可以使用以下命令開啟它

npx prisma studio

使用 Prisma Postgres，您也可以直接在透過選取專案中的 Studio 標籤來使用 Prisma Studio。

使用 Next.js 建立完整堆疊應用程式​

了解如何在完整堆疊應用程式中使用 Prisma Postgres

探索隨時可執行的 Prisma ORM 範例​

查看 GitHub 上的 prisma-examples 儲存庫，以了解 Prisma ORM 如何與您最喜歡的程式庫一起使用。該儲存庫包含 Express、NestJS、GraphQL 的範例，以及 Next.js 和 Vue.js 的完整堆疊範例，以及更多內容。

這些範例預設使用 SQLite，但您可以按照專案 README 中的指示，在幾個簡單的步驟中切換到 Prisma Postgres。s

加入 Prisma 社群 💚​

Prisma 擁有龐大的開發人員社群。在 Discord 上加入我們，或使用 GitHub Discussions 提出問題。