跳到主要内容

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 参数，则在后续迁移中不会影响数据库中的扩展。
© . All rights reserved.