新資料模型語法：更強大的結構描述控制 & 更簡化的遷移

⚠️ 本文已過時，因為它與現已棄用的 Prisma 1 相關。若要深入瞭解最新版本的 Prisma，請閱讀文件。 ⚠️

在過去幾個月中，我們與社群合作定義了適用於 Prisma 的改進資料模型規格。這個新版本稱為 datamodel v1.1，並已於今日的穩定版本中推出。請在此處查看文件here。

從今天起，Prisma 的公開Demo 伺服器將使用新的資料模型語法。請查看文件或此教學影片，以瞭解如何升級您現有的專案。

---

更彈性的資料建模方法

資料模型是每個 Prisma 專案的基礎。它作為底層資料庫結構描述的基礎。

目前的資料模型對於資料庫佈局有其武斷之處，例如關係、資料表/資料行或系統欄位的命名。新的資料模型語法解除了許多限制，讓開發人員對其結構描述有更多控制權。

更強大的資料庫佈局控制

以下是新的資料模型語法啟用的一些功能

• 指定關係應使用關係表還是外鍵
• 模型/欄位名稱可以與底層資料表/資料行的名稱不同
• 使用任何欄位作為 id 欄位，並「自備 ID」
• 使用任何欄位作為 createdAt 或 updatedAt 欄位

更簡單的遷移 & 改進的內省

在先前的 Prisma 版本中，開發人員必須決定是否應由 Prisma 為他們執行資料庫遷移，方法是在 PRISMA_CONFIG 中設定 migrations 旗標。

migrations 旗標已在最新 Prisma 版本中移除，這表示開發人員現在隨時可以手動遷移資料庫或使用 Prisma 進行遷移。

我們也對現有資料庫的內省投入了大量心力，為使用 Prisma 搭配舊版資料庫或需要在某些時候執行手動遷移的開發人員，啟用順暢的工作流程。

---

改進的資料模型語法有哪些新功能？

將模型和欄位名稱對應至底層資料表和資料行

使用舊的資料模型語法，資料表和資料行的命名總是完全依照資料模型中的模型和欄位。使用新的 @db 指令，您可以控制底層資料庫中應呼叫哪些資料表和資料行

在本例中，底層資料表將稱為 user，而資料行將稱為 full_name。

決定關係在資料庫結構描述中的表示方式

舊的資料模型對於資料庫結構描述中的關係有其武斷之處：它們總是以關係表表示。

一方面，這使得輕鬆將任何現有關係遷移至多對多關係成為可能，而無需額外工作。但是，這種彈性可能會產生效能損失，因為查詢關係表的成本通常更高。

雖然 1:1 和 1:n 關係現在可以透過外鍵表示，但 m:n 關係仍將以關係表表示。

使用新的資料模型，開發人員可以完全控制在底層資料庫中表示關係。有兩個選項

• 透過內嵌參考 (即外鍵) 表示關係
• 透過關係表表示關係

以下是兩個關係的範例 (一個是內嵌，另一個使用關係表)

在內嵌關係的情況下，@relation(link: INLINE) 指令的放置位置決定了外鍵儲存在關係的哪一端，在本例中，外鍵儲存在 User 資料表中。

使用任何欄位作為 id、createdAt 或 updatedAt

使用舊的資料模型，如果開發人員想要自動產生唯一 ID 或追蹤記錄的建立/上次更新時間，則必須使用保留欄位。

使用新的 @id、@createdAt 和 @updatedAt 指令，現在可以將此功能新增至模型的任何欄位

更彈性的 ID

目前的資料模型總是使用 CUID 來產生和儲存資料庫記錄的全域唯一 ID。datamodel v1.1 現在讓維護自訂 ID 以及使用其他 ID 類型 (例如整數、序列或 UUID) 成為可能。

---

開始使用新的資料模型語法

我們準備了兩個簡短的教學課程，供您探索新的資料模型

• 選項 A：升級舊的 Prisma 專案至新的資料模型語法
• 選項 B：從頭開始使用新的資料模型語法

如需更廣泛的教學課程和開始使用現有資料庫的說明，請造訪文件。

先決條件：安裝最新的 Prisma CLI

若要安裝最新版本的 Prisma CLI，請執行

以 Docker 執行 Prisma 時，您需要將其 Docker 映像升級至 1.31。

選項 A：從舊的 Prisma 版本升級

升級現有的 Prisma 專案時，您可以簡單地執行 prisma introspect 以使用新的語法產生資料模型。以下章節和本影片中描述了確切的流程，並附有範例

1. 舊的資料模型設定

假設您已經有一個執行中的 Prisma 專案，其使用 (舊的) 資料模型。

2. 升級您的 Prisma 伺服器

在用於部署 Prisma 伺服器的 Docker Compose 檔案中，請確定 prismagraphql/prisma 映像使用最新的 1.31 Prisma 版本。例如

現在升級執行中的 Prisma 伺服器

3. 透過內省產生新的資料模型

如果您現在執行 prisma deploy，您的 Prisma CLI 將擲回錯誤，因為您嘗試將舊語法中的資料模型部署至更新的 Prisma 伺服器。

修正這些錯誤的最簡單方法是透過內省產生以新語法撰寫的資料模型。在 prisma.yml 所在的目錄內執行下列命令

這會內省您的資料庫，並產生另一個使用新語法的資料模型，稱為 datamodel-TIMESTAMP.prisma (例如 datamodel-1554394432089.prisma)。針對上述範例，將產生下列資料模型

4. 部署新的資料模型

最後一個步驟是刪除舊的 datamodel.prisma 檔案，並將您產生的資料模型重新命名為 datamodel.prisma (以便 prisma.yml 中的 datamodel 屬性指向使用新語法的產生檔案)。

完成後，您可以執行

5. 最佳化您的資料庫結構描述

由於內省並未變更您的資料庫佈局，因此所有關係仍以關係表表示。如果您想瞭解如何遷移舊的 1:1 和 1:n 關係以使用外鍵，請查看此處的文件here。

選項 B：從頭開始

在瞭解如何升級現有的 Prisma 專案之後，我們現在將引導您完成一個從頭開始的簡單設定。

1. 建立新的 Prisma 專案

讓我們從設定新的 Prisma 專案開始

在互動式精靈中，選取下列項目

1. 選取建立新的資料庫
2. 選取PostgreSQL (或 MySQL，如果您偏好)
3. 選取您偏好語言的用戶端 (選用，因為我們不會使用用戶端)

在透過 Docker 啟動 Prisma 伺服器和資料庫之前，請為您的資料庫啟用連接埠對應。這稍後將允許您使用本機資料庫用戶端 (例如 Postico 或 TablePlus) 連線至資料庫。

在產生的 docker-compose.yml 中，取消註解資料庫 Docker 映像設定中的下列幾行

2. 定義資料模型

讓我們定義一個利用新的 Prisma 功能的資料模型。開啟 datamodel.prisma 並將內容取代為下列內容

以下是有關此資料模型定義的一些重要資訊

• 每個模型都對應至一個資料表，該資料表的命名方式與模型相同，但使用 @db 指令將其改為小寫。
• 有下列關係
  • 1:1 User 和 Profile 之間
  • 1:n User 和 Post 之間
  • n:m Post 和 Category 之間
• User 和 Profile 之間的 1:1 關係在 User 模型上以 @relation(link: INLINE) 註解。這表示如果存在關係，資料庫中的 user 記錄會參考 profile 記錄 (因為 profile 欄位並非必要，因此關係可能只是 NULL)。INLINE 的替代方案是 TABLE，在這種情況下，Prisma 將透過專用的關係表追蹤關係。
• User 和 Post 之間的 1:n 關係透過 post 資料表的 author 資料行，以內嵌方式追蹤關係，亦即 @relation(link: INLINE) 指令是在 Post 模型的 author 欄位上推斷的。
• Post 和 Category 之間的 n:m 關係透過稱為 PostToCategory 的專用關係表追蹤。此關係表是資料模型的一部分，並以 @relationTable 指令註解。
• 每個模型都有一個以 @id 指令註解的 id 欄位。
• 針對 User 模型，資料庫會透過以 @createdAt 指令註解的欄位，自動追蹤記錄的建立時間。
• 針對 Post 模型，資料庫會透過以 @createdAt 和 @updatedAt 指令註解的欄位，自動追蹤記錄的建立時間和更新時間。

3. 部署資料模型

在下一個步驟中，Prisma 會將此資料模型對應至底層資料庫

4. 在 Prisma Admin 中檢視和編輯資料

從這裡開始，如果您想以程式設計方式存取資料庫中的資料，可以使用 Prisma 用戶端。在下文中，我們將重點說明如何使用 Prisma Admin 與資料互動。

請造訪文件，以瞭解如何使用 TablePlus 連線至資料庫並探索底層資料庫結構描述。

若要在 Prisma Admin 中存取您的資料，您需要導覽至 Prisma 專案的管理端點：https://127.0.0.1:4466/_admin

---

分享您的意見反應和想法

雖然新的資料模型語法已經納入我們社群要求的許多功能，但我們仍然看到進一步改進它的機會。例如，資料模型尚未提供多欄索引和多型關係。

我們目前正在開發一種新的資料塑模語言，它將是目前使用的 SDL 的變體。

我們很想聽聽您對新資料模型的看法。請透過在意見反應儲存庫中開啟問題來分享您的意見反應，或加入 Spectrum 上的對話。