跳到主要內容

如何搭配多個資料庫結構描述使用 Prisma ORM

警告

目前 PostgreSQL、CockroachDB 和 SQL Server 連接器支援多個資料庫結構描述。

許多資料庫供應商允許您將資料庫表格組織成已命名的群組。您可以使用此功能讓資料模型的邏輯結構更容易理解，或避免表格之間的命名衝突。

在 PostgreSQL、CockroachDB 和 SQL Server 中，這些群組稱為結構描述。我們將它們稱為資料庫結構描述，以區別於 Prisma ORM 自身的結構描述。

本指南說明如何

  • 在您的 Prisma 結構描述中包含多個資料庫結構描述
  • 使用 Prisma Migrate 和 db push 將您的結構描述變更套用至資料庫
  • 內省具有多個資料庫結構描述的現有資料庫
  • 使用 Prisma Client 跨多個資料庫結構描述查詢

如何啟用 multiSchema 預覽功能​

多結構描述支援目前為預覽版。若要啟用 multiSchema 預覽功能，請將 multiSchema 功能旗標新增至 Prisma Schema 中 generator 區塊的 previewFeatures 欄位

schema.prisma
generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["multiSchema"]
}

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

如何在您的 Prisma 結構描述中包含多個資料庫結構描述​

若要在您的 Prisma 結構描述檔案中使用多個資料庫結構描述，請在 datasource 區塊的 schemas 欄位中新增資料庫結構描述的名稱到陣列中。以下範例新增了 "base" 和 "transactional" 結構描述

schema.prisma
generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["multiSchema"]
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
  schemas  = ["base", "transactional"]
}

您不需要變更連線字串。連線字串的 schema 值是 Prisma Client 連線並用於原始查詢的預設資料庫結構描述。所有其他 Prisma Client 查詢都使用您正在查詢的模型或列舉的結構描述。

若要指定模型或列舉屬於特定的資料庫結構描述，請新增 @@schema 屬性，並將資料庫結構描述的名稱作為參數。在以下範例中，User 模型是 "base" 結構描述的一部分，而 Order 模型和 Size 列舉是 "transactional" 結構描述的一部分

schema.prisma
model User {
  id     Int     @id
  orders Order[]

  @@schema("base")
}

model Order {
  id      Int  @id
  user    User @relation(fields: [id], references: [id])
  user_id Int

  @@schema("transactional")
}

enum Size {
  Small
  Medium
  Large

  @@schema("transactional")
}

不同資料庫結構描述中具有相同名稱的表格​

如果您在不同的資料庫結構描述中有名稱相同的表格，您需要將表格名稱映射到 Prisma 結構描述中唯一的模型名稱。這可以避免在 Prisma Client 中查詢模型時發生名稱衝突。

例如，考慮一種情況，其中 base 資料庫結構描述中的 config 表格與 users 資料庫結構描述中的 config 表格名稱相同。為了避免名稱衝突，請在您的 Prisma 結構描述中為模型提供唯一的名稱 (BaseConfig 和 UserConfig)，並使用 @@map 屬性將每個模型映射到對應的表格名稱

schema.prisma
model BaseConfig {
  id Int @id

  @@map("config")
  @@schema("base")
}

model UserConfig {
  id Int @id

  @@map("config")
  @@schema("users")
}

如何使用 Prisma Migrate 和 db push 套用您的結構描述變更​

您可以使用 Prisma Migrate 或 db push 將變更套用至具有多個資料庫結構描述的 Prisma 結構描述。

例如，將 Profile 模型新增至上方部落格文章模型的 base 結構描述

schema.prisma
model User {
  id      Int      @id
  orders  Order[]
  profile Profile?

  @@schema("base")
}

model Profile {
  id     Int    @id @default(autoincrement())
  bio    String
  user   User   @relation(fields: [userId], references: [id])
  userId Int    @unique

  @@schema("base")
}

model Order {
  id      Int  @id
  user    User @relation(fields: [id], references: [id])
  user_id Int

  @@schema("transactional")
}

enum Size {
  Small
  Medium
  Large

  @@schema("transactional")
}

然後，您可以將此結構描述變更套用至您的資料庫。例如，您可以使用 migrate dev 建立遷移並套用您的結構描述變更

npx prisma migrate dev --name add_profile

請注意，如果您將模型或列舉從一個結構描述移動到另一個結構描述，Prisma ORM 會從來源結構描述中刪除該模型或列舉，並在目標結構描述中建立一個新的模型或列舉。

如何內省具有多個資料庫結構描述的現有資料庫​

您可以使用 db pull，以與內省具有單一資料庫結構描述的資料庫相同的方式，內省具有多個資料庫結構描述的現有資料庫

npx prisma db pull

這會更新您的 Prisma 結構描述，以符合資料庫的目前狀態。

如果您在不同的資料庫結構描述中有名稱相同的表格，Prisma ORM 會顯示驗證錯誤，指出衝突。若要修正此問題，請使用 @map 屬性重新命名內省的模型。

如何使用 Prisma Client 跨多個資料庫結構描述查詢​

您可以在多個資料庫結構描述中查詢模型，而無需變更您的 Prisma Client 查詢語法。例如，以下查詢使用上述 Prisma 結構描述，尋找給定使用者的所有訂單

const orders = await prisma.order.findMany({
  where: {
    user: {
      id: 1,
    },
  },
})

深入了解 multiSchema 預覽功能​

若要深入了解 multiSchema 預覽功能的未來計畫，或提供意見回饋，請參閱我們的 Github 議題。