本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 適用於 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 延伸模組或更新它所需的許可，與在指定資料庫中建立其他物件所需的許可相同。 + `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` 命令來建立它。 ### 函數原型 ``` 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` 會將指定的內部 PostgreSQL 功能新增至 `pgtle.feature_info` 資料表。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 延伸模組或其他使用該功能的程序或函數。如需掛鉤和受信任語言延伸模組的詳細資訊，請參閱 [搭配您的延伸模組使用 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` 功能 (例如掛鉤) 的函數。如需詳細資訊，請參閱 [搭配您的延伸模組使用 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'); ```