适用于 PostgreSQL 的可信语言扩展的函数参考 - Amazon Aurora
pgtle.available_extensionspgtle.available_extension_versionspgtle.extension_update_pathspgtle.install_extensionpgtle.install_update_pathpgtle.register_featurepgtle.register_feature_if_not_existspgtle.set_default_versionpgtle.uninstall_extensionpgtle.uninstall_extensionpgtle.uninstall_extension_if_existspgtle.uninstall_update_pathpgtle.uninstall_update_path_if_existspgtle.unregister_featurepgtle.unregister_feature_if_exists
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

适用于 PostgreSQL 的可信语言扩展的函数参考

查看以下有关适用于 PostgreSQL 的可信语言扩展中提供的函数的参考文档。使用这些函数安装、注册、更新和管理您的 TLE 扩展，即您使用可信语言扩展开发套件开发的 PostgreSQL 扩展。

pgtle.available_extensions

pgtle.available_extensions 函数是一个集合返回函数。它返回数据库中所有可用的 TLE 扩展。返回的每一行都包含有关单个 TLE 扩展的信息。

函数原型

pgtle.available_extensions()

角色

无。

参数

无。

输出

  • name – TLE 扩展的名称。

  • default_version – 在未指定版本的情况下调用 CREATE EXTENSION 时要使用的 TLE 扩展的版本。

  • description – 有关 TLE 扩展的更详细描述。

用法示例

SELECT * FROM pgtle.available_extensions();

pgtle.available_extension_versions

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 文档中的将相关对象打包为扩展 > 扩展文件。

用法示例

SELECT * FROM pgtle.available_extension_versions();

pgtle.extension_update_paths

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_extension

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 文档的将相关对象打包为扩展中的扩展文件。

输出

此函数在成功时返回 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_update_path

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_feature

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_feature_if_not_exists

pgtle.register_feature_if_not_exists 函数将指定的 PostgreSQL 功能添加到 pgtle.feature_info 表中，并标识使用该功能的 TLE 扩展或其他过程或函数。有关挂钩和可信语言扩展的更多信息，请参阅 在您的 TLE 扩展中使用 PostgreSQL 挂钩。

函数原型

pgtle.register_feature_if_not_exists(proc regproc, feature pg_tle_feature)

角色

pgtle_admin

参数

  • proc – 包含用作 TLE 扩展的功能的逻辑（代码）的存储过程或函数的名称。例如，pw_hook 代码。

  • feature – 要为 TLE 函数注册的 PostgreSQL 功能的名称。目前，唯一可用的功能是 passcheck 挂钩。有关更多信息，请参阅 密码检查挂钩（passcheck）。

输出

为指定的扩展注册该功能后返回 true。如果该功能已经注册，则返回 false。

用法示例

SELECT pgtle.register_feature_if_not_exists('pw_hook', 'passcheck');

pgtle.set_default_version

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_extension(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_extension(name, version)

uninstall_extension(name, version) 函数从数据库中删除指定版本的 TLE 扩展。此功能可防止 CREATE EXTENSION 和 ALTER EXTENSION 将 TLE 扩展安装或更新到指定版本。此函数还删除指定版本的 TLE 扩展的所有更新路径。如果 TLE 扩展当前在数据库中处于活动状态，则此函数不会将其卸载。必须显式调用 DROP EXTENSION 才能删除 TLE 扩展。要卸载 TLE 扩展的所有版本，请参阅 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_extension_if_exists

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_update_path

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_update_path_if_exists

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_feature

unregister_feature 函数提供了一种方法，用于删除注册为使用 pg_tle 功能（如挂钩）的函数。有关注册功能的信息，请参阅 pgtle.register_feature。

函数原型

pgtle.unregister_feature(proc regproc, feature pg_tle_features)

角色

pgtle_admin

参数

  • proc – 要向 pg_tle 功能注册的存储函数的名称。

  • feature – 要向函数注册的 pg_tle 功能的名称。例如，passcheck 是一项可以注册以供您开发的可信语言扩展使用的功能。有关更多信息，请参阅 密码检查挂钩（passcheck）。

输出

无。

用法示例

SELECT * FROM pgtle.unregister_feature('pw_hook', 'passcheck');

pgtle.unregister_feature_if_exists

unregister_feature 函数提供了一种方法，用于删除注册为使用 pg_tle 功能（如挂钩）的函数。有关更多信息，请参阅 在您的 TLE 扩展中使用 PostgreSQL 挂钩。成功取消注册该功能后，返回 true。如果未注册该功能，则返回 false。

有关为 TLE 扩展注册 pg_tle 功能的信息，请参阅 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');