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 Schema 中的 PostgreSQL 扩展列表，并使用 Prisma Migrate 将更改应用于数据库。

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

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

什么是 PostgreSQL 扩展？​

如何启用 postgresqlExtensions 预览功能​

如何在 Prisma Schema 中表示 PostgreSQL 扩展​

如何内省 PostgreSQL 扩展​

如何迁移 PostgreSQL 扩展​

什么是 PostgreSQL 扩展？

如何启用 `postgresqlExtensions` 预览功能

如何在 Prisma Schema 中表示 PostgreSQL 扩展

如何内省 PostgreSQL 扩展

如何迁移 PostgreSQL 扩展