如何使用 Prisma ORM 的型別系統

本指南介紹了 Prisma ORM 的型別系統，並解釋瞭如何內省資料庫中現有的原生型別，以及在使用 Prisma Migrate 或 db push 對資料庫應用模式更改時如何使用型別。

Prisma ORM 的型別系統如何工作？

Prisma ORM 使用型別來定義欄位可以包含的資料種類。為了方便上手，Prisma ORM 提供了一些核心的標量型別，這些型別應涵蓋大多數預設用例。例如，以下部落格文章模型

schema.prisma

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

model Post {
  id        Int      @id
  title     String
  createdAt DateTime
}

Post 模型的 title 欄位使用 String 標量型別，而 createdAt 欄位使用 DateTime 標量型別。

資料庫也有自己的型別系統，它定義了列可以儲存的值的型別。大多數資料庫提供了大量的資料型別，以實現對列可以儲存的內容的精細控制。例如，資料庫可能內建支援多種大小的整數，或支援 XML 資料。這些型別的名稱在不同的資料庫之間有所不同。例如，在 PostgreSQL 中，布林值的列型別是 boolean，而在 MySQL 中，通常使用 tinyint(1) 型別。

在上面的部落格文章示例中，我們使用的是 PostgreSQL 聯結器。這在 Prisma 模式的 datasource 塊中指定。

預設型別對映

為了讓您能夠開始使用我們的核心標量型別，Prisma ORM 提供了 預設型別對映，將每個標量型別對映到底層資料庫中的預設型別。例如

預設情況下，Prisma ORM 的 String 型別被對映到 PostgreSQL 的 text 型別和 MySQL 的 varchar 型別
預設情況下，Prisma ORM 的 DateTime 型別被對映到 PostgreSQL 的 timestamp(3) 型別和 SQL Server 的 datetime2 型別

請參閱 Prisma ORM 的資料庫聯結器頁面，以瞭解給定資料庫的預設型別對映。例如，此表提供了 PostgreSQL 的預設型別對映。
要檢視特定 Prisma ORM 型別在所有資料庫中的預設型別對映，請參閱 Prisma 模式參考的模型欄位標量型別部分。例如，此表提供了 Float 標量型別的預設型別對映。

原生型別對映

有時您可能需要使用更具體的資料庫型別，而該型別不是 Prisma ORM 型別的預設型別對映之一。為此，Prisma ORM 提供了原生型別屬性來細化核心標量型別。例如，在上面 Post 模型的 createdAt 欄位中，您可能希望在底層 PostgreSQL 資料庫中使用僅包含日期的列，透過使用 date 型別而不是 timestamp(3) 的預設型別對映。為此，請在 createdAt 欄位中新增 @db.Date 原生型別屬性

schema.prisma

model Post {
  id        Int      @id
  title     String
  createdAt DateTime @db.Date
}

原生型別對映允許您表達資料庫中的所有型別。但是，如果 Prisma ORM 的預設值滿足您的需求，則無需使用它們。這使得常見用例的 Prisma 模式更短、更易讀。

如何內省資料庫型別

當您內省現有資料庫時，Prisma ORM 將獲取每個表列的資料庫型別，並使用相應的模型欄位的正確 Prisma ORM 型別在您的 Prisma 模式中表示它。如果資料庫型別不是該 Prisma ORM 標量型別的預設資料庫型別，Prisma ORM 還會新增一個原生型別屬性。

例如，以 PostgreSQL 資料庫中的 User 表為例，其中包含

一個數據型別為 serial 的 id 列
一個數據型別為 text 的 name 列
一個數據型別為 boolean 的 isActive 列

您可以使用以下 SQL 命令建立它

CREATE TABLE "public"."User" (
  id serial PRIMARY KEY NOT NULL,
  name text NOT NULL,
  "isActive" boolean NOT NULL
);

從您的專案根目錄執行以下命令來內省您的資料庫

npx prisma db pull

您將獲得以下 Prisma 模式

schema.prisma

model User {
  id       Int     @id @default(autoincrement())
  name     String
  isActive Boolean
}

資料庫中的 id、name 和 isActive 列分別對映到 Int、String 和 Boolean Prisma ORM 型別。這些資料庫型別是這些 Prisma ORM 型別的預設資料庫型別，因此 Prisma ORM 不會新增任何原生型別屬性。

現在，透過執行以下 SQL 命令，向資料庫新增一個數據型別為 date 的 createdAt 列

ALTER TABLE "public"."User"
ADD COLUMN "createdAt" date NOT NULL;

再次內省您的資料庫

npx prisma db pull

您的 Prisma 模式現在包含新的 createdAt 欄位，其 Prisma ORM 型別為 DateTime。createdAt 欄位還具有 @db.Date 原生型別屬性，因為 PostgreSQL 的 date 不是 DateTime 型別的預設型別

schema.prisma

model User {
  id        Int      @id @default(autoincrement())
  name      String
  isActive  Boolean
  createdAt DateTime @db.Date
}

在對資料庫應用模式更改時如何使用型別

當您使用 Prisma Migrate 或 db push 對資料庫應用模式更改時，Prisma ORM 將使用每個欄位的 Prisma ORM 標量型別及其任何原生屬性來確定資料庫中相應列的正確資料庫型別。

例如，建立一個包含以下 Post 模型的 Prisma 模式

schema.prisma

model Post {
  id        Int      @id
  title     String
  createdAt DateTime
  updatedAt DateTime @db.Date
}

此 Post 模型包含

一個 Prisma ORM 型別為 Int 的 id 欄位
一個 Prisma ORM 型別為 String 的 title 欄位
一個 Prisma ORM 型別為 DateTime 的 createdAt 欄位
一個 Prisma ORM 型別為 DateTime 且帶有 @db.Date 原生型別屬性的 updatedAt 欄位

現在，從您的專案根目錄執行以下命令，將這些更改應用到一個空的 PostgreSQL 資料庫

npx prisma db push

您將看到資料庫中有一個新建立的 Post 表，其中包含

一個數據庫型別為 integer 的 id 列
一個數據庫型別為 text 的 title 列
一個數據庫型別為 timestamp(3) 的 createdAt 列
一個數據庫型別為 date 的 updatedAt 列

請注意，@db.Date 原生型別屬性將 updatedAt 列的資料庫型別修改為 date，而不是預設的 timestamp(3)。

Prisma ORM 的型別系統如何工作？​

預設型別對映​

原生型別對映​

如何內省資料庫型別​

在對資料庫應用模式更改時如何使用型別​

更多關於使用 Prisma ORM 型別系統​

Prisma ORM 的型別系統如何工作？

預設型別對映

原生型別對映

如何內省資料庫型別

在對資料庫應用模式更改時如何使用型別

更多關於使用 Prisma ORM 型別系統