跳至主要内容

PostgreSQL 扩展

此页面介绍了 PostgreSQL 扩展，并描述了如何在 Prisma 模式中表示扩展，如何在数据库中内省现有扩展，以及如何使用 Prisma Migrate 将扩展的更改应用到数据库。

警告

仅在 Prisma 4.5.0 及更高版本中，PostgreSQL 连接器的预览功能才支持在模式中声明 PostgreSQL 扩展。

什么是 PostgreSQL 扩展？​

PostgreSQL 允许您通过安装和激活称为扩展的软件包来扩展数据库功能。例如，citext 扩展添加了一种不区分大小写的字符串数据类型。某些扩展（例如 citext）由 PostgreSQL 直接提供，而其他扩展则由外部开发。有关扩展的更多信息，请参阅PostgreSQL 文档。

要使用扩展，必须首先在数据库服务器的本地文件系统上安装它。然后，您需要激活扩展，这将运行一个添加新功能的脚本文件。

信息

请注意，PostgreSQL 的文档使用术语“安装”来指代我们所说的激活扩展。我们在这里使用了不同的术语，以明确这两个步骤是不同的。

Prisma 的 postgresqlExtensions 预览功能允许您在 Prisma 模式中表示 PostgreSQL 扩展。请注意，特定扩展可能会添加 Prisma 目前不支持的功能。例如，扩展可能会添加 Prisma 不支持的类型或索引。此功能必须逐案实施，并且此预览功能不提供此功能。

如何启用 postgresqlExtensions 预览功能​

在 Prisma 模式中表示 PostgreSQL 扩展目前是一项预览功能。要启用 postgresqlExtensions 预览功能，您需要将 postgresqlExtensions 功能标志添加到 Prisma 模式中 generator 块的 previewFeatures 字段

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

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

如何在 Prisma 模式中表示 PostgreSQL 扩展​

要在 Prisma 模式中表示 PostgreSQL 扩展，请将 extensions 字段添加到 schema.prisma 文件的 datasource 块中，并使用您需要的扩展数组。例如，以下模式列出了 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：激活扩展对象所在的模式的名称。如果未指定此参数，则使用当前默认的对象创建模式。
  • version：要激活的扩展的版本。如果未指定此参数，则使用扩展控制文件中给出的值。
  • map：扩展的数据库名称。如果未指定此参数，则 Prisma 模式中扩展的名称必须与数据库名称匹配。

在上面的示例中，hstore 扩展使用 myHstoreSchema 模式，并且 postgis 扩展使用扩展的 2.1 版本激活。

当您要激活的 PostgreSQL 扩展的名称在 Prisma 模式中不是有效标识符时，map 参数很有用。例如，uuid-ossp PostgreSQL 扩展名称是无效的标识符，因为它包含连字符。在以下示例中，扩展映射到 Prisma 模式中的有效名称 uuidOssp

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

如何内省 PostgreSQL 扩展​

要内省当前在您的数据库中激活的 PostgreSQL 扩展并将相关扩展添加到您的 Prisma 模式中，请运行 npx prisma db pull。

许多 PostgreSQL 扩展与 Prisma 模式无关。例如，某些扩展旨在用于不更改模式的数据库管理任务。如果包含所有这些扩展，则扩展列表将非常长。为避免这种情况，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 模式中
  • 重新内省时，行为取决于扩展是否在白名单上。
    • 白名单上的扩展
      • 如果它们在数据库中但在 Prisma 模式中不存在，则添加到您的 Prisma 模式中
      • 如果它们在 Prisma 模式和数据库中都存在，则保留在您的 Prisma 模式中
      • 如果它们在 Prisma 模式中但在数据库中不存在，则删除来自您的 Prisma 模式
    • 不在白名单上的扩展
      • 如果它们在 Prisma 模式和数据库中都存在，则保留在您的 Prisma 模式中
      • 如果它们在 Prisma 模式中但在数据库中不存在，则删除来自您的 Prisma 模式

当您内省时，version 参数不会添加到 Prisma 模式中。

如何迁移 PostgreSQL 扩展​

您可以更新 Prisma 模式中的 PostgreSQL 扩展列表，并使用Prisma Migrate将更改应用到您的数据库。

这与迁移 Prisma 模式（例如模型或字段）的其他元素的方式类似。但是，存在以下差异

  • 如果从模式中删除扩展，但它仍在数据库中激活，则 Prisma Migrate 不会将其从数据库中停用。
  • 如果向模式中添加新的扩展，则只有在数据库中不存在时才会激活它，因为扩展可能已经手动创建。
  • 如果您从扩展定义中删除了version或schema参数，它不会对后续迁移中的数据库中的扩展产生任何影响。