PostgreSQL 扩展

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

¥This page introduces PostgreSQL extensions and describes how to represent extensions in your Prisma schema, how to introspect existing extensions in your database, and how to apply changes to your extensions to your database with Prisma Migrate.

warning

仅在 Prisma 版本 4.5.0 及更高版本中，PostgreSQL 连接器预览版支持在架构中声明 PostgreSQL 扩展。

¥Support for declaring PostgreSQL extensions in your schema is available in preview for the PostgreSQL connector only in Prisma versions 4.5.0 and later.

什么是 PostgreSQL 扩展？

¥What are PostgreSQL extensions?

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

¥PostgreSQL allows you to extend your database functionality by installing and activating packages known as extensions. For example, the citext extension adds a case-insensitive string data type. Some extensions, such as citext, are supplied directly by PostgreSQL, while other extensions are developed externally. For more information on extensions, see the PostgreSQL documentation.

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

¥To use an extension, it must first be installed on the local file system of your database server. You then need to activate the extension, which runs a script file that adds the new functionality.

info

请注意，PostgreSQL 的文档使用术语 'install' 来指代我们所说的激活扩展。我们在这里使用单独的术语来明确这是两个不同的步骤。

¥Note that PostgreSQL's documentation uses the term 'install' to refer to what we call activating an extension. We have used separate terms here to make it clear that these are two different steps.

Prisma 的 postgresqlExtensions 预览功能允许你在 Prisma 模式中表示 PostgreSQL 扩展。请注意，特定扩展可能会添加 Prisma 当前不支持的功能。例如，扩展可能会添加 Prisma 不支持的类型或索引。此功能必须根据具体情况来实现，并且此预览功能不提供此功能。

¥Prisma's postgresqlExtensions preview feature allows you to represent PostgreSQL extensions in your Prisma schema. Note that specific extensions may add functionality that is not currently supported by Prisma. For example, an extension may add a type or index that is not supported by Prisma. This functionality must be implemented on a case-by-case basis and is not provided by this preview feature.

如何启用 `postgresqlExtensions` 预览功能

¥How to enable the postgresqlExtensions preview feature

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

¥Representing PostgreSQL extensions in your Prisma Schema is currently a preview feature. To enable the postgresqlExtensions preview feature, you will need to add the postgresqlExtensions feature flag to the previewFeatures field of the generator block in your Prisma schema:

schema.prisma

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

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

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

¥How to represent PostgreSQL extensions in your Prisma schema

要在 Prisma 架构中表示 PostgreSQL 扩展，请将 extensions 字段添加到 schema.prisma 文件的 datasource 块中，并包含所需扩展的数组。例如，以下架构列出了 hstore、pg_trgm 和 postgis 扩展：

¥To represent PostgreSQL extensions in your Prisma schema, add the extensions field to the datasource block of your schema.prisma file with an array of the extensions that you require. For example, the following schema lists the hstore, pg_trgm and postgis extensions:

schema.prisma

datasource db {
  provider   = "postgresql"
  url        = env("DATABASE_URL")
  extensions = [hstore(schema: "myHstoreSchema"), pg_trgm, postgis(version: "2.1")]
}

Prisma 架构中的每个扩展名称都可以采用以下可选参数：

¥Each extension name in the Prisma schema can take the following optional arguments:

schema：要在其中激活扩展对象的架构的名称。如果未指定此参数，则使用当前默认的对象创建模式。

¥schema: the name of the schema in which to activate the extension's objects. If this argument is not specified, the current default object creation schema is used.
version：要激活的扩展的版本。如果未指定此参数，则使用扩展控制文件中给定的值。

¥version: the version of the extension to activate. If this argument is not specified, the value given in the extension's control file is used.
map：扩展的数据库名称。如果未指定此参数，Prisma 架构中的扩展名称必须与数据库名称匹配。

¥map: the database name of the extension. If this argument is not specified, the name of the extension in the Prisma schema must match the database name.

在上面的示例中，hstore 扩展使用 myHstoreSchema 架构，postgis 扩展是使用该扩展的 2.1 版本激活的。

¥In the example above, the hstore extension uses the myHstoreSchema schema, and the postgis extension is activated with version 2.1 of the extension.

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

¥The map argument is useful when the PostgreSQL extension that you want to activate has a name that is not a valid identifier in the Prisma schema. For example, the uuid-ossp PostgreSQL extension name is an invalid identifier because it contains a hyphen. In the following example, the extension is mapped to the valid name uuidOssp in the Prisma schema:

schema.prisma

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

如何内省 PostgreSQL 扩展

¥How to introspect PostgreSQL extensions

要在数据库中当前激活 introspect PostgreSQL 扩展并将相关扩展添加到 Prisma 架构中，请运行 npx prisma db pull。

¥To introspect PostgreSQL extensions currently activated in your database and add relevant extensions to your Prisma schema, run npx prisma db pull.

许多 PostgreSQL 扩展与 Prisma 模式无关。例如，某些扩展适用于不更改架构的数据库管理任务。如果包含所有这些扩展，则扩展列表将会很长。为了避免这种情况，Prisma 维护了一个已知相关扩展的白名单。当前的许可名单如下：

¥Many PostgreSQL extensions are not relevant to the Prisma schema. For example, some extensions are intended for database administration tasks that do not change the schema. If all these extensions were included, the list of extensions would be very long. To avoid this, Prisma maintains an allowlist of known relevant extensions. The current allowlist is the following:

citext：提供不区分大小写的字符串类型，citext

¥citext: provides a case-insensitive character string type, citext
pgcrypto：提供加密函数，如 gen_random_uuid()，以生成通用唯一标识符 (UUID v4)

¥pgcrypto: provides cryptographic functions, like gen_random_uuid(), to generate universally unique identifiers (UUIDs v4)
uuid-ossp：提供诸如 uuid_generate_v4() 之类的函数来生成通用唯一标识符 (UUID v4)

¥uuid-ossp: provides functions, like uuid_generate_v4(), to generate universally unique identifiers (UUIDs v4)
postgis：添加 GIS（地理信息系统）支持

¥postgis: adds GIS (Geographic Information Systems) support

注意：从 PostgreSQL v13 开始，gen_random_uuid() 可以在没有扩展的情况下使用来生成通用唯一标识符 (UUID v4)。

¥Note: Since PostgreSQL v13, gen_random_uuid() can be used without an extension to generate universally unique identifiers (UUIDs v4).

扩展自省如下：

¥Extensions are introspected as follows:

第一次内省时，允许列表中的所有数据库扩展都会添加到你的 Prisma 架构中

¥The first time you introspect, all database extensions that are on the allowlist are added to your Prisma schema
当你重新自省时，行为取决于扩展程序是否位于允许列表中。

¥When you re-introspect, the behavior depends on whether the extension is on the allowlist or not.
- 允许名单上的扩展：
  
  ¥Extensions on the allowlist:
  - 如果它们位于数据库中但不在 Prisma 架构中，则会添加到你的 Prisma 架构中
    
    ¥are added to your Prisma schema if they are in the database but not in the Prisma schema
  - 如果它们位于 Prisma 架构和数据库中，则保留在你的 Prisma 架构中
    
    ¥are kept in your Prisma schema if they are in the Prisma schema and in the database
  - 如果它们位于 Prisma 架构中但不在数据库中，则从你的 Prisma 架构中删除
    
    ¥are removed from your Prisma schema if they are in the Prisma schema but not the database
- 不在允许列表中的扩展程序：
  
  ¥Extensions not on the allowlist:
  - 如果它们位于 Prisma 架构和数据库中，则保留在你的 Prisma 架构中
    
    ¥are kept in your Prisma schema if they are in the Prisma schema and in the database
  - 如果它们位于 Prisma 架构中但不在数据库中，则从你的 Prisma 架构中删除
    
    ¥are removed from your Prisma schema if they are in the Prisma schema but not the database

当你内省时，version 参数不会添加到 Prisma 架构中。

¥The version argument will not be added to the Prisma schema when you introspect.

如何迁移 PostgreSQL 扩展

¥How to migrate PostgreSQL extensions

你可以更新 Prisma 架构中的 PostgreSQL 扩展列表，并使用 Prisma 迁移将更改应用到你的数据库。

¥You can update your list of PostgreSQL extensions in your Prisma schema and apply the changes to your database with Prisma Migrate.

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

¥This works in a similar way to migration of other elements of your Prisma schema, such as models or fields. However, there are the following differences:

如果你从架构中删除扩展，但它仍然在数据库上激活，Prisma Migrate 不会从数据库中停用它。

¥If you remove an extension from your schema but it is still activated on your database, Prisma Migrate will not deactivate it from the database.
如果将新扩展添加到架构中，则仅当数据库中尚不存在该扩展时才会激活该扩展，因为该扩展可能已手动创建。

¥If you add a new extension to your schema, it will only be activated if it does not already exist in the database, because the extension may already have been created manually.
如果从扩展定义中删除 version 或 schema 参数，则对后续迁移中数据库中的扩展没有影响。

¥If you remove the version or schema arguments from the extension definition, it has no effect to the extensions in the database in the following migrations.

什么是 PostgreSQL 扩展？​

如何启用 postgresqlExtensions 预览功能​

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

如何内省 PostgreSQL 扩展​

如何迁移 PostgreSQL 扩展​

什么是 PostgreSQL 扩展？

如何启用 `postgresqlExtensions` 预览功能

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

如何内省 PostgreSQL 扩展

如何迁移 PostgreSQL 扩展