跳到主要內容

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()，用於生成全域性唯一識別符號 (UUIDs v4)
  • uuid-ossp：提供函式，例如 uuid_generate_v4()，用於生成全域性唯一識別符號 (UUIDs v4)
  • postgis：新增 GIS (地理資訊系統) 支援

注意：從 PostgreSQL v13 開始，無需擴充套件即可使用 gen_random_uuid() 生成全域性唯一識別符號 (UUIDs 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 schema 中的 PostgreSQL 擴充套件列表，並使用 Prisma Migrate 將更改應用到資料庫。

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

  • 如果你從 schema 中移除一個擴充套件，但它仍在資料庫中啟用，Prisma Migrate 不會從資料庫中停用它。
  • 如果你向 schema 新增一個新擴充套件，只有當它在資料庫中尚不存在時才會被啟用，因為該擴充套件可能已手動建立。
  • 如果你從擴充套件定義中移除 version 或 schema 引數，則在後續遷移中不會影響資料庫中的擴充套件。
© . This site is unofficial and not affiliated with Prisma Data, Inc.