# 适用于 PostgreSQL 的可信语言扩展的函数参考查看以下有关适用于 PostgreSQL 的可信语言扩展中提供的函数的参考文档。使用这些函数安装、注册、更新和管理您的 *TLE 扩展*，即您使用可信语言扩展开发套件开发的 PostgreSQL 扩展。 **Topics** + [pgtle.available\$1extensions](#pgtle.available_extensions) + [pgtle.available\$1extension\$1versions](#pgtle.available_extension_versions) + [pgtle.extension\$1update\$1paths](#pgtle.extension_update_paths) + [pgtle.install\$1extension](#pgtle.install_extension) + [pgtle.install\$1update\$1path](#pgtle.install_update_path) + [pgtle.register\$1feature](#pgtle.register_feature) + [pgtle.register\$1feature\$1if\$1not\$1exists](#pgtle.register_feature_if_not_exists) + [pgtle.set\$1default\$1version](#pgtle.set_default_version) + [pgtle.uninstall\$1extension(name)](#pgtle.uninstall_extension-name) + [pgtle.uninstall\$1extension(name, version)](#pgtle.uninstall_extension-name-version) + [pgtle.uninstall\$1extension\$1if\$1exists](#pgtle.uninstall_extension_if_exists) + [pgtle.uninstall\$1update\$1path](#pgtle.uninstall_update_path) + [pgtle.uninstall\$1update\$1path\$1if\$1exists](#pgtle.uninstall_update_path_if_exists) + [pgtle.unregister\$1feature](#pgtle.unregister_feature) + [pgtle.unregister\$1feature\$1if\$1exists](#pgtle.unregister_feature_if_exists) ## pgtle.available\$1extensions `pgtle.available_extensions` 函数是一个集合返回函数。它返回数据库中所有可用的 TLE 扩展。返回的每一行都包含有关单个 TLE 扩展的信息。 ### 函数原型 ``` pgtle.available_extensions() ``` ### 角色无。 ### 参数无。 ### 输出 + `name` – TLE 扩展的名称。 + `default_version` – 在未指定版本的情况下调用 `CREATE EXTENSION` 时要使用的 TLE 扩展的版本。 + `description` – 有关 TLE 扩展的更详细描述。 ### 用法示例 ``` SELECT * FROM pgtle.available_extensions(); ``` ## pgtle.available\$1extension\$1versions `available_extension_versions` 函数是一个集合返回函数。它返回所有可用 TLE 扩展及其版本的列表。每行都包含有关给定 TLE 扩展的特定版本的信息，包括它是否需要特定角色。 ### 函数原型 ``` pgtle.available_extension_versions() ``` ### 角色无。 ### 参数无。 ### 输出 + `name` – TLE 扩展的名称。 + `version` – TLE 扩展的版本。 + `superuser` – 对于您的 TLE 扩展，此值始终为 `false`。创建 TLE 扩展或更新 TLE 扩展所需的权限与在给定数据库中创建其他对象所需的权限相同。 + `trusted` – 对于您的 TLE 扩展，此值始终为 `false`。 + `relocatable` – 对于您的 TLE 扩展，此值始终为 `false`。 + `schema` – 指定安装 TLE 扩展的模式的名称。 + `requires` – 包含此 TLE 扩展所需的其他扩展的名称的数组。 + `description` – TLE 扩展的详细描述。有关输出值的更多信息，请参阅 PostgreSQL 文档中的[将相关对象打包为扩展 > 扩展文件](https://www.postgresql.org/docs/current/extend-extensions.html#id-1.8.3.20.11)。 ### 用法示例 ``` SELECT * FROM pgtle.available_extension_versions(); ``` ## pgtle.extension\$1update\$1paths `extension_update_paths` 函数是一个集合返回函数。它返回 TLE 扩展的所有可能更新路径的列表。每行都包含该 TLE 扩展的可用升级或降级。 ### 函数原型 ``` pgtle.extension_update_paths(name) ``` ### 角色无。 ### 参数 `name` – 从中获取升级路径的 TLE 扩展的名称。 ### 输出 + `source` – 更新的源版本。 + `target` – 更新的目标版本。 + `path` – 用于将 TLE 扩展从 `source` 版本更新到 `target` 版本的升级路径，例如 `0.1--0.2`。 ### 用法示例 ``` SELECT * FROM pgtle.extension_update_paths('your-TLE'); ``` ## pgtle.install\$1extension `install_extension` 函数允许您在数据库中安装构成 TLE 扩展的构件，之后可以使用 `CREATE EXTENSION` 命令创建 TLE 扩展。 ### 函数原型 ``` pgtle.install_extension(name text, version text, description text, ext text, requires text[] DEFAULT NULL::text[]) ``` ### 角色无。 ### 参数 + `name` – TLE 扩展的名称。调用 `CREATE EXTENSION` 时使用此值。 + `version` – TLE 扩展的版本。 + `description` – 有关 TLE 扩展的详细描述。此描述显示在 `pgtle.available_extensions()` 的 `comment` 字段中。 + `ext` – TLE 扩展的内容。此值包含诸如函数之类的对象。 + `requires` – 一个可选参数，用于指定此 TLE 扩展的依赖项。`pg_tle` 扩展会自动添加为依赖项。其中许多参数与扩展控制文件中包含的参数相同，用于在 PostgreSQL 实例的文件系统上安装 PostgreSQL 扩展。有关更多信息，请参阅 PostgreSQL 文档的[将相关对象打包为扩展](https://www.postgresql.org/docs/current/extend-extensions.html)中的[扩展文件](http://www.postgresql.org/docs/current/extend-extensions.html#id-1.8.3.20.11)。 ### 输出此函数在成功时返回 `OK`，在出现错误时返回 `NULL`。 + `OK` – TLE 扩展已成功安装在数据库中。 + `NULL` – TLE 扩展未成功安装在数据库中。 ### 用法示例 ``` SELECT pgtle.install_extension( 'pg_tle_test', '0.1', 'My first pg_tle extension', $_pgtle_$ CREATE FUNCTION my_test() RETURNS INT AS $$ SELECT 42; $$ LANGUAGE SQL IMMUTABLE; $_pgtle_$ ); ``` ## pgtle.install\$1update\$1path `install_update_path` 函数提供 TLE 扩展的两个不同版本之间的更新路径。此功能允许您的 TLE 扩展的用户使用 `ALTER EXTENSION ... UPDATE` 语法更新其版本。 ### 函数原型 ``` pgtle.install_update_path(name text, fromvers text, tovers text, ext text) ``` ### 角色 `pgtle_admin` ### 参数 + `name` – TLE 扩展的名称。调用 `CREATE EXTENSION` 时使用此值。 + `fromvers` – 用于升级的 TLE 扩展的源版本。 + `tovers` – 用于升级的 TLE 扩展的目标版本。 + `ext` – 更新的内容。此值包含诸如函数之类的对象。 ### 输出无。 ### 用法示例 ``` SELECT pgtle.install_update_path('pg_tle_test', '0.1', '0.2', $_pgtle_$ CREATE OR REPLACE FUNCTION my_test() RETURNS INT AS $$ SELECT 21; $$ LANGUAGE SQL IMMUTABLE; $_pgtle_$ ); ``` ## pgtle.register\$1feature `register_feature` 函数向 `pgtle.feature_info` 表中添加了指定的内部 PostgreSQL 功能。PostgreSQL 挂钩是 PostgreSQL 内部功能的一个示例。可信语言扩展开发套件支持使用 PostgreSQL 挂钩。目前，此函数支持以下功能。 + `passcheck` – 将密码检查挂钩注册到自定义 PostgreSQL 的密码检查行为的过程或函数。 ### 函数原型 ``` pgtle.register_feature(proc regproc, feature pg_tle_feature) ``` ### 角色 `pgtle_admin` ### 参数 + `proc` – 用于该功能的存储过程或函数的名称。 + `feature` – 要注册到该函数的 `pg_tle` 功能（例如 `passcheck`）的名称。 ### 输出无。 ### 用法示例 ``` SELECT pgtle.register_feature('pw_hook', 'passcheck'); ``` ## pgtle.register\$1feature\$1if\$1not\$1exists `pgtle.register_feature_if_not_exists` 函数将指定的 PostgreSQL 功能添加到 `pgtle.feature_info` 表中，并标识使用该功能的 TLE 扩展或其他过程或函数。有关挂钩和可信语言扩展的更多信息，请参阅 [在您的 TLE 扩展中使用 PostgreSQL 挂钩](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md)。 ### 函数原型 ``` pgtle.register_feature_if_not_exists(proc regproc, feature pg_tle_feature) ``` ### 角色 `pgtle_admin` ### 参数 + `proc` – 包含用作 TLE 扩展的功能的逻辑（代码）的存储过程或函数的名称。例如，`pw_hook` 代码。 + `feature` – 要为 TLE 函数注册的 PostgreSQL 功能的名称。目前，唯一可用的功能是 `passcheck` 挂钩。有关更多信息，请参阅 [密码检查挂钩（passcheck）](PostgreSQL_trusted_language_extension-hooks-reference.md#passcheck_hook)。 ### 输出为指定的扩展注册该功能后返回 `true`。如果该功能已经注册，则返回 `false`。 ### 用法示例 ``` SELECT pgtle.register_feature_if_not_exists('pw_hook', 'passcheck'); ``` ## pgtle.set\$1default\$1version `set_default_version` 函数可让您指定 TLE 扩展的 `default_version`。您可以使用此函数定义升级路径，并将该版本指定为 TLE 扩展的缺省版本。当数据库用户在 `CREATE EXTENSION` 和 `ALTER EXTENSION ... UPDATE` 命令中指定您的 TLE 扩展时，将在数据库中为该用户创建该版本的 TLE 扩展。成功时，此函数返回 `true`。如果在 `name` 参数中指定的 TLE 扩展不存在，此函数将返回错误。同样，如果 TLE 扩展的 `version` 不存在，它会返回错误。 ### 函数原型 ``` pgtle.set_default_version(name text, version text) ``` ### 角色 `pgtle_admin` ### 参数 + `name` – TLE 扩展的名称。调用 `CREATE EXTENSION` 时使用此值。 + `version` – 用于设置缺省设置的 TLE 扩展版本。 ### 输出 + `true` – 成功设置缺省版本时，此函数返回 `true`。 + `ERROR` – 如果具有指定名称或版本的 TLE 扩展不存在，则返回错误消息。 ### 用法示例 ``` SELECT * FROM pgtle.set_default_version('my-extension', '1.1'); ``` ## pgtle.uninstall\$1extension(name) `uninstall_extension` 函数从数据库中删除 TLE 扩展的所有版本。此函数可防止 `CREATE EXTENSION` 的将来调用安装 TLE 扩展。如果数据库中不存在 TLE 扩展，则会引发错误。 `uninstall_extension` 函数不会删除数据库中当前处于活动状态的 TLE 扩展。要删除当前处于活动状态的 TLE 扩展，您需要显式调用 `DROP EXTENSION` 以将其删除。 ### 函数原型 ``` pgtle.uninstall_extension(extname text) ``` ### 角色 `pgtle_admin` ### 参数 + `extname` – 要卸载的 TLE 扩展的名称。此名称与用于 `CREATE EXTENSION` 的名称相同，旨在加载 TLE 扩展以便在给定数据库中使用。 ### 输出无。 ### 用法示例 ``` SELECT * FROM pgtle.uninstall_extension('pg_tle_test'); ``` ## pgtle.uninstall\$1extension(name, version) `uninstall_extension(name, version)` 函数从数据库中删除指定版本的 TLE 扩展。此功能可防止 `CREATE EXTENSION` 和 `ALTER EXTENSION` 将 TLE 扩展安装或更新到指定版本。此函数还删除指定版本的 TLE 扩展的所有更新路径。如果 TLE 扩展当前在数据库中处于活动状态，则此函数不会将其卸载。必须显式调用 `DROP EXTENSION` 才能删除 TLE 扩展。要卸载 TLE 扩展的所有版本，请参阅 [pgtle.uninstall\$1extension(name)](#pgtle.uninstall_extension-name)。 ### 函数原型 ``` pgtle.uninstall_extension(extname text, version text) ``` ### 角色 `pgtle_admin` ### 参数 + `extname` – TLE 扩展的名称。调用 `CREATE EXTENSION` 时使用此值。 + `version` – 要从数据库中卸载的 TLE 扩展的版本。 ### 输出无。 ### 用法示例 ``` SELECT * FROM pgtle.uninstall_extension('pg_tle_test', '0.2'); ``` ## pgtle.uninstall\$1extension\$1if\$1exists `uninstall_extension_if_exists` 函数从给定的数据库中删除 TLE 扩展的所有版本。如果 TLE 扩展不存在，则该函数会静默返回（不会引发任何错误消息）。如果指定的扩展当前在数据库中处于活动状态，则此函数不会将其删除。必须先显式调用 `DROP EXTENSION` 以删除 TLE 扩展，然后才能使用此函数卸载其构件。 ### 函数原型 ``` pgtle.uninstall_extension_if_exists(extname text) ``` ### 角色 `pgtle_admin` ### 参数 + `extname` – TLE 扩展的名称。调用 `CREATE EXTENSION` 时使用此值。 ### 输出在卸载指定扩展后，`uninstall_extension_if_exists` 函数返回 `true`。如果指定的扩展不存在，则此函数将返回 `false`。 + `true` – 卸载 TLE 扩展后返回 `true`。 + `false` – 当数据库中不存在 TLE 扩展时返回 `false`。 ### 用法示例 ``` SELECT * FROM pgtle.uninstall_extension_if_exists('pg_tle_test'); ``` ## pgtle.uninstall\$1update\$1path `uninstall_update_path` 函数从 TLE 扩展中删除特定的更新路径。这可以防止 `ALTER EXTENSION ... UPDATE TO` 将其用作更新路径。如果 TLE 扩展当前正由此更新路径上的其中一个版本使用，则该扩展保留在数据库中。如果指定的更新路径不存在，则此函数会引发错误。 ### 函数原型 ``` pgtle.uninstall_update_path(extname text, fromvers text, tovers text) ``` ### 角色 `pgtle_admin` ### 参数 + `extname` – TLE 扩展的名称。调用 `CREATE EXTENSION` 时使用此值。 + `fromvers` – 更新路径上使用的 TLE 扩展的源版本。 + `tovers` – 更新路径上使用的 TLE 扩展的目标版本。 ### 输出无。 ### 用法示例 ``` SELECT * FROM pgtle.uninstall_update_path('pg_tle_test', '0.1', '0.2'); ``` ## pgtle.uninstall\$1update\$1path\$1if\$1exists `uninstall_update_path_if_exists` 函数与 `uninstall_update_path` 类似，它从 TLE 扩展中删除指定的更新路径。但是，如果更新路径不存在，则此函数不会引发错误消息。相反，该函数返回 `false`。 ### 函数原型 ``` pgtle.uninstall_update_path_if_exists(extname text, fromvers text, tovers text) ``` ### 角色 `pgtle_admin` ### 参数 + `extname` – TLE 扩展的名称。调用 `CREATE EXTENSION` 时使用此值。 + `fromvers` – 更新路径上使用的 TLE 扩展的源版本。 + `tovers` – 更新路径上使用的 TLE 扩展的目标版本。 ### 输出 + `true` – 该函数已成功更新 TLE 扩展的路径。 + `false` – 该函数无法更新 TLE 扩展的路径。 ### 用法示例 ``` SELECT * FROM pgtle.uninstall_update_path_if_exists('pg_tle_test', '0.1', '0.2'); ``` ## pgtle.unregister\$1feature `unregister_feature` 函数提供了一种方法，用于删除注册为使用 `pg_tle` 功能（如挂钩）的函数。有关注册功能的信息，请参阅 [pgtle.register\$1feature](#pgtle.register_feature)。 ### 函数原型 ``` pgtle.unregister_feature(proc regproc, feature pg_tle_features) ``` ### 角色 `pgtle_admin` ### 参数 + `proc` – 要向 `pg_tle` 功能注册的存储函数的名称。 + `feature` – 要向函数注册的 `pg_tle` 功能的名称。例如，`passcheck` 是一项可以注册以供您开发的可信语言扩展使用的功能。有关更多信息，请参阅 [密码检查挂钩（passcheck）](PostgreSQL_trusted_language_extension-hooks-reference.md#passcheck_hook)。 ### 输出无。 ### 用法示例 ``` SELECT * FROM pgtle.unregister_feature('pw_hook', 'passcheck'); ``` ## pgtle.unregister\$1feature\$1if\$1exists `unregister_feature` 函数提供了一种方法，用于删除注册为使用 `pg_tle` 功能（如挂钩）的函数。有关更多信息，请参阅 [在您的 TLE 扩展中使用 PostgreSQL 挂钩](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md)。成功取消注册该功能后，返回 `true`。如果未注册该功能，则返回 `false`。有关为 TLE 扩展注册 `pg_tle` 功能的信息，请参阅 [pgtle.register\$1feature](#pgtle.register_feature)。 ### 函数原型 ``` pgtle.unregister_feature_if_exists('proc regproc', 'feature pg_tle_features') ``` ### 角色 `pgtle_admin` ### 参数 + `proc` – 为包含 `pg_tle` 功能而注册的存储函数的名称。 + `feature` – 向可信语言扩展注册的 `pg_tle` 功能的名称。 ### 输出返回 `true` 或 `false`，如下所示。 + `true` – 该函数已成功将该功能从扩展中取消注册。 + `false` – 该函数无法从 TLE 扩展中取消注册该功能。 ### 用法示例 ``` SELECT * FROM pgtle.unregister_feature_if_exists('pw_hook', 'passcheck'); ```