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 参数，则对后续迁移中的数据库扩展没有影响。

什么是 PostgreSQL 扩展？​

如何启用 postgresqlExtensions 预览功能​

如何在您的 Prisma schema 中表示 PostgreSQL 扩展​

如何内省 PostgreSQL 扩展​

如何迁移 PostgreSQL 扩展​

什么是 PostgreSQL 扩展？

如何启用 `postgresqlExtensions` 预览功能

如何在您的 Prisma schema 中表示 PostgreSQL 扩展

如何内省 PostgreSQL 扩展

如何迁移 PostgreSQL 扩展