適用於 PostgreSQL 的受信任語言延伸模組的函數參考

檢視下列有關適用於 PostgreSQL 的受信任語言延伸模組中提供之函數的參考文件。使用這些函數來安裝、註冊、更新和管理您的 TLE 延伸模組，亦即您使用受信任語言延伸模組開發套件所開發的 PostgreSQL 延伸模組。

pgtle.available_extensions

pgtle.available_extensions 函數是一個設定-傳回函數。它會傳回資料庫中所有可用的 TLE 延伸模組。每一傳回的列都包含單一 TLE 延伸模組的相關資訊。

函數原型

pgtle.available_extensions()

角色

無。

引數

無。

輸出

使用範例

SELECT * FROM pgtle.available_extensions();

pgtle.available_extension_versions

available_extension_versions 函數是一個設定-傳回函數。其會傳回一份清單，列出所有可用的 TLE 延伸模組及其版本。每一列都包含指定 TLE 延伸模組之特定版本的相關資訊，包括其是否需要特定角色。

函數原型

pgtle.available_extension_versions()

角色

無。

引數

無。

輸出

如需輸出值的詳細資訊，請參閱 PostgreSQL 文件中的將相關物件封裝為延伸模組 > 延伸模組檔案。

使用範例

SELECT * FROM pgtle.available_extension_versions();

pgtle.extension_update_paths

extension_update_paths 函數是一個設定-傳回函數。其會傳回一份清單，列出 TLE 延伸模組的所有可能更新路徑。每一列都包含該 TLE 延伸模組的可用升級或降級。

函數原型

pgtle.extension_update_paths(name)

角色

無。

引數

name – 要從中取得升級路徑的 TLE 延伸模組名稱。

輸出

使用範例

SELECT * FROM pgtle.extension_update_paths('your-TLE');

pgtle.install_extension

install_extension 函數可讓您在資料庫中安裝構成 TLE 延伸模組的成品，然後您可以使用 CREATE EXTENSION 命令來建立它。

函數原型

pgtle.install_extension(name text, version text, description text, ext text, requires text[] DEFAULT NULL::text[])

角色

無。

引數

其中許多引數與延伸模組控制檔中包含的引數相同，用於在 PostgreSQL 執行個體的檔案系統上安裝 PostgreSQL 延伸模組。如需詳細資訊，請參閱 PostgreSQL 文件中將相關物件封裝為延伸模組中的延伸模組檔案。

輸出

此函數會在成功時傳回 OK，以及在發生錯誤時傳回 NULL。

使用範例

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

引數

輸出

無。

使用範例

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 會將指定的內部 PostgreSQL 功能新增至 pgtle.feature_info 資料表。PostgreSQL 掛鉤是內部 PostgreSQL 功能的範例。受信任語言延伸模組開發套件支援使用 PostgreSQL 掛鉤。目前，此函數支援下列功能。

函數原型

pgtle.register_feature(proc regproc, feature pg_tle_feature)

角色

pgtle_admin

引數

輸出

無。

使用範例

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

pgtle.register_feature_if_not_exists

pgtle.register_feature_if_not_exists 函數會將指定的 PostgreSQL 功能新增至 pgtle.feature_info 資料表，並識別 TLE 延伸模組或其他使用該功能的程序或函數。如需掛鉤和受信任語言延伸模組的詳細資訊，請參閱 搭配您的延伸模組使用 PostgreSQL 掛鉤。

函數原型

pgtle.register_feature_if_not_exists(proc regproc, feature pg_tle_feature)

角色

pgtle_admin

引數

輸出

在針對指定的延伸模組註冊功能之後傳回 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

引數

輸出

使用範例

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

引數

輸出

無。

使用範例

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

引數

輸出

無。

使用範例

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

引數

輸出

在解除安裝指定的延伸模組之後，uninstall_extension_if_exists 函數會傳回 true。如果指定的延伸模組不存在，函數會傳回 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

引數

輸出

無。

使用範例

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

引數

輸出

使用範例

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

引數

輸出

無。

使用範例

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

pgtle.unregister_feature_if_exists

unregister_feature 函數會提供一種方法，來刪除已註冊為使用 pg_tle 功能 (例如掛鉤) 的函數。如需詳細資訊，請參閱 搭配您的延伸模組使用 PostgreSQL 掛鉤。在成功取消註冊功能之後傳回 true。如果功能未註冊，則會傳回 false。

如需為 TLE 延伸模組註冊 pg_tle 功能的相關資訊，請參閱 pgtle.register_feature。

函數原型

pgtle.unregister_feature_if_exists('proc regproc', 'feature pg_tle_features')

角色

pgtle_admin

引數

輸出

傳回 true 或 false，如下所示。

使用範例

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