跳到主要內容

PostgreSQL 擴充功能

本頁面介紹 PostgreSQL 擴充功能，並描述如何在您的 Prisma schema 中表示擴充功能、如何內省資料庫中現有的擴充功能，以及如何使用 Prisma Migrate 將擴充功能的變更套用至資料庫。

警告

僅限於 Prisma 4.5.0 及更高版本中的 PostgreSQL 連接器，才提供在 schema 中宣告 PostgreSQL 擴充功能的預覽功能。

什麼是 PostgreSQL 擴充功能？​

PostgreSQL 允許您透過安裝和啟用稱為擴充功能的套件來擴展資料庫功能。 例如，citext 擴充功能新增了區分大小寫的字串資料類型。 有些擴充功能 (例如 citext) 由 PostgreSQL 直接提供，而其他擴充功能則由外部開發。 有關擴充功能的更多資訊，請參閱 PostgreSQL 文件。

若要使用擴充功能，必須先將其安裝在資料庫伺服器的本機檔案系統上。 然後您需要啟用擴充功能，這會執行指令檔，以新增新功能。

資訊

請注意，PostgreSQL 的文件使用「安裝」一詞來指稱我們所稱的啟用擴充功能。 我們在此處使用不同的術語，以清楚表明這是兩個不同的步驟。

Prisma 的 postgresqlExtensions 預覽功能允許您在 Prisma schema 中表示 PostgreSQL 擴充功能。 請注意，特定的擴充功能可能會新增 Prisma 目前不支援的功能。 例如，擴充功能可能會新增 Prisma 不支援的類型或索引。 此功能必須根據個案情況實作，並且此預覽功能不提供。

如何啟用 postgresqlExtensions 預覽功能​

在您的 Prisma Schema 中表示 PostgreSQL 擴充功能目前是預覽功能。 若要啟用 postgresqlExtensions 預覽功能，您需要將 postgresqlExtensions 功能旗標新增至 Prisma schema 中 generator 區塊的 previewFeatures 欄位

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

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

如何在您的 Prisma schema 中表示 PostgreSQL 擴充功能​

若要在您的 Prisma schema 中表示 PostgreSQL 擴充功能，請將 extensions 欄位新增至 schema.prisma 檔案的 datasource 區塊，並包含您需要的擴充功能陣列。 例如，以下 schema 列出了 hstore、pg_trgm 和 postgis 擴充功能

schema.prisma
datasource db {
  provider   = "postgresql"
  url        = env("DATABASE_URL")
  extensions = [hstore(schema: "myHstoreSchema"), pg_trgm, postgis(version: "2.1")]
}

Prisma schema 中的每個擴充功能名稱都可以採用以下選用引數

  • schema：要在其中啟用擴充功能物件的 schema 名稱。 如果未指定此引數，則會使用目前的預設物件建立 schema。
  • version：要啟用的擴充功能版本。 如果未指定此引數，則會使用擴充功能控制檔案中給定的值。
  • map：擴充功能的資料庫名稱。 如果未指定此引數，則 Prisma schema 中的擴充功能名稱必須與資料庫名稱相符。

在上面的範例中，hstore 擴充功能使用 myHstoreSchema schema，而 postgis 擴充功能則以擴充功能版本 2.1 啟用。

當您想要啟用的 PostgreSQL 擴充功能名稱在 Prisma schema 中不是有效的識別碼時，map 引數會很有用。 例如，uuid-ossp PostgreSQL 擴充功能名稱是無效的識別碼，因為它包含連字號。 在以下範例中，擴充功能在 Prisma schema 中對應到有效的名稱 uuidOssp

schema.prisma
datasource db {
  provider   = "postgresql"
  url        = env("DATABASE_URL")
  extensions = [uuidOssp(map: "uuid-ossp")]
}

如何內省 PostgreSQL 擴充功能​

若要內省目前在資料庫中啟用的 PostgreSQL 擴充功能，並將相關擴充功能新增至您的 Prisma schema，請執行 npx prisma db pull。

許多 PostgreSQL 擴充功能與 Prisma schema 無關。 例如，有些擴充功能旨在用於資料庫管理工作，而不會變更 schema。 如果包含所有這些擴充功能，則擴充功能清單會非常長。 為了避免這種情況，Prisma 維護了一份已知相關擴充功能的允許清單。 目前的允許清單如下：

  • citext：提供區分大小寫的字元串類型 citext
  • pgcrypto：提供加密功能，例如 gen_random_uuid()，以產生通用唯一識別碼 (UUID v4)
  • uuid-ossp：提供功能，例如 uuid_generate_v4()，以產生通用唯一識別碼 (UUID v4)
  • postgis：新增 GIS（地理資訊系統）支援

注意：自 PostgreSQL v13 起，gen_random_uuid() 可以直接使用，無需擴充功能即可產生通用唯一識別碼 (UUID v4)。

擴充功能內省方式如下

  • 第一次內省時，允許清單上的所有資料庫擴充功能都會新增至您的 Prisma schema
  • 當您重新內省時，行為取決於擴充功能是否在允許清單上。
    • 允許清單上的擴充功能
      • 如果擴充功能在資料庫中但不在 Prisma schema 中，則會將其新增至您的 Prisma schema
      • 如果擴充功能在 Prisma schema 和資料庫中，則會將其保留在您的 Prisma schema 中
      • 如果擴充功能在 Prisma schema 中但不在資料庫中，則會從您的 Prisma schema 中移除
    • 不在允許清單上的擴充功能
      • 如果擴充功能在 Prisma schema 和資料庫中，則會將其保留在您的 Prisma schema 中
      • 如果擴充功能在 Prisma schema 中但不在資料庫中，則會從您的 Prisma schema 中移除

當您內省時，version 引數將不會新增至 Prisma schema。

如何遷移 PostgreSQL 擴充功能​

您可以使用 Prisma Migrate 更新 Prisma schema 中的 PostgreSQL 擴充功能清單，並將變更套用至資料庫。

這與遷移 Prisma schema 的其他元素（例如模型或欄位）的方式類似。 但是，有以下差異：

  • 如果您從 schema 中移除擴充功能，但該擴充功能仍在您的資料庫中啟用，Prisma Migrate 不會從資料庫中停用它。
  • 如果您將新的擴充功能新增至您的 schema，則只有在資料庫中尚不存在該擴充功能時才會啟用它，因為該擴充功能可能已經手動建立。
  • 如果您從擴充功能定義中移除 version 或 schema 引數，則對後續遷移中的資料庫擴充功能沒有影響。