本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用適用於 PostgreSQL 的受信任語言延伸模組
PostgreSQL 的受信任語言延伸模組是用於建置 PostgreSQL 延伸模組的開放原始碼開發套件。它可讓您建置高效能 PostgreSQL 延伸模組，並在 RDS for PostgreSQL 資料庫執行個體上安全地執行它們 透過使用適用於 PostgreSQL 的受信任語言延伸模組 (TLE)，您可以建立 PostgreSQL 延伸模組，遵循記載的方法來擴充 PostgreSQL 功能。如需詳細資訊，請參閱 PostgreSQL 文件中的[將相關物件封裝為延伸模組](https://www.postgresql.org/docs/current/extend-extensions.html)。
TLE 的一個主要優點，就是您可以在未於 PostgreSQL 執行個體之下提供檔案系統存取權的環境中使用它。先前，安裝新的延伸模組需要存取檔案系統。TLE 移除了此條件約束。它提供一個開發環境，可讓您針對任何 PostgreSQL 資料庫 (包括在 RDS for PostgreSQL 資料庫執行個體上執行的資料庫) 建立新的延伸模組。
TLE 的設計旨在防止存取對您使用 TLE 建立的延伸模組而言不安全的資源。其執行時間環境會限制任何延伸模組瑕疵對單一資料庫連線的影響。TLE 還可讓資料庫管理員對可以安裝延伸模組的人員進行精細控制，並提供用於執行延伸模組的許可模型。
下列 RDS for PostgreSQL 版本支援 TLE：
+ 18.1 版和更新的 18 版
+ 17.1 版和更新的 17 版
+ 16.1 版和更新的 16 版
+ 15.2 版和更新的第 15 版
+ 14.5 版和更新的第 14 版
+ 13.12 版和更新的第 13 版
受信任語言延伸模組開發環境和執行時間會封裝成 `pg_tle` PostgreSQL 延伸模組 1.0.1 版。它支援以 JavaScript、Perl、Tcl、PL/PGSQL 和 SQL 建立延伸模組。您可以採取您安裝其他 PostgreSQL 延伸模組的同一方式，在 RDS for PostgreSQL 資料庫執行個體中安裝 `pg_tle` 延伸模組。在設定了 `pg_tle` 之後，開發人員可以使用它，建立新的 PostgreSQL 延伸模組，稱為 *TLE 延伸模組*。
在下列主題中，您可以找到如何設定受信任語言延伸模組，以及如何開始建立您自己的 TLE 延伸模組的相關資訊。
**Topics**
+ [術語](PostgreSQL_trusted_language_extension-terminology.md)
+ [使用適用於 PostgreSQL 的受信任語言延伸模組的需求](PostgreSQL_trusted_language_extension-requirements.md)
+ [在您的 RDS for PostgreSQL 資料庫執行個體中設定受信任語言延伸模組](PostgreSQL_trusted_language_extension-setting-up.md)
+ [適用於 PostgreSQL 的受信任語言延伸模組概觀](PostgreSQL_trusted_language_extension.overview.md)
+ [針對 RDS for PostgreSQL 建立 TLE 延伸模組](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md)
+ [從資料庫中捨棄您的 TLE 延伸模組](PostgreSQL_trusted_language_extension-creating-TLE-extensions.dropping-TLEs.md)
+ [解除安裝適用於 PostgreSQL 的受信任語言延伸模組](PostgreSQL_trusted_language_extension-uninstalling-pg_tle-devkit.md)
+ [搭配您的延伸模組使用 PostgreSQL 掛鉤](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md)
+ [在 TLE 中使用自訂資料類型](PostgreSQL_trusted_language_extension-custom-data-type.md)
+ [適用於 PostgreSQL 的受信任語言延伸模組的函數參考](PostgreSQL_trusted_language_extension-functions-reference.md)
+ [適用於 PostgreSQL 的受信任語言延伸模組的掛鉤參考](PostgreSQL_trusted_language_extension-hooks-reference.md)
# 術語
為了協助您更好地了解受信任語言延伸模組，請檢視下列詞彙表以取得本主題中使用的術語。
**適用於 PostgreSQL 的受信任語言延伸模組**
*適用於 PostgreSQL 的受信任語言延伸模組*是封裝為 `pg_tle` 延伸模組之開放原始碼開發套件的正式名稱。它可以在任何 PostgreSQL 系統上使用。如需詳細資訊，請參閱 GitHub 上的 [aws/pg\$1tle](https://github.com/aws/pg_tle)。
**受信任語言延伸模組**
*受信任語言延伸模組*是適用於 PostgreSQL 的受信任語言延伸模組的簡稱。此簡稱及其縮寫 (TLE) 也會在本文件中使用。
**受信任語言**
*受信任語言*是具有特定安全性屬性的程式設計或指令碼語言。例如，受信任語言通常會限制對檔案系統的存取，而且也會限制使用指定的聯網屬性。TLE 開發套件專為支援受信任語言而設計。PostgreSQL 支援數種不同的語言，這些語言用來建立受信任或不受信任的延伸模組。如需範例，請參閱 PostgreSQL 文件中的[受信任和不受信任的 PL/Perl](https://www.postgresql.org/docs/current/plperl-trusted.html)。當您使用受信任語言延伸模組建立延伸模組時，延伸模組本質上會使用受信任語言機制。
**TLE 延伸模組**
*TLE 延伸模組*是已使用受信任語言延伸模組 (TLE) 開發套件所建立的 PostgreSQL 延伸模組。
# 使用適用於 PostgreSQL 的受信任語言延伸模組的需求
以下是設定和使用 TLE 開發套件時的需求。
+ ** RDS for PostgreSQL 版本** - 僅在 RDS for PostgreSQL 13.12 版和更新的第 13 版、14.5 版和更新的第 14 版，以及 15.2 版及更新版本上支援受信任語言延伸模組。
+ 如果您需要升級 RDS for PostgreSQL 執行個體， 請參閱 [RDS for PostgreSQL 資料庫引擎的升級](USER_UpgradeDBInstance.PostgreSQL.md)。
+ 如果您還沒有執行 PostgreSQL 的 Amazon RDS 資料庫執行個體，則可以建立一個。如需詳細資訊，請參閱 RDS for PostgreSQL 資料庫執行個體，請參閱 [建立並連線至 PostgreSQL 資料庫執行個體](CHAP_GettingStarted.CreatingConnecting.PostgreSQL.md)。
+ **需要 `rds_superuser` 權限** - 若要設定 `pg_tle` 延伸模組，您的資料庫使用者角色必須具有 `rds_superuser` 角色的許可。根據預設，會將此角色授予建立 的 `postgres` 使用者。RDS for PostgreSQL 資料庫執行個體。
+ **需要自訂資料庫參數群組** – 您的 RDS for PostgreSQL 資料庫執行個體必須搭配自訂資料庫參數群組進行設定。
+ 如果您的 RDS for PostgreSQL 資料庫執行個體未搭配自訂資料庫參數群組進行設定，您應該建立一個，並將其與 RDS for PostgreSQL 資料庫執行個體建立關聯。如需步驟的簡短摘要，請參閱 [建立並套用自訂資料庫參數群組](#PostgreSQL_trusted_language_extension-requirements-create-custom-params)。
+ 如果您的 RDS for PostgreSQL 資料庫執行個體已使用自訂資料庫參數群組進行設定，您可以設定受信任語言延伸模組。如需詳細資訊，請參閱[在您的 RDS for PostgreSQL 資料庫執行個體中設定受信任語言延伸模組](PostgreSQL_trusted_language_extension-setting-up.md)。
## 建立並套用自訂資料庫參數群組
請使用下列步驟建立自訂資料庫參數群組，並設定您的 RDS for PostgreSQL 資料庫執行個體來使用該群組。
### 主控台
**建立自訂資料庫參數群組，並將其與 RDS for PostgreSQL 資料庫執行個體搭配使用**
1. 登入 AWS 管理主控台 ，並在 [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/)：// 開啟 Amazon RDS 主控台。
1. 從 Amazon RDS 功能表中，選擇 Parameter groups (參數群組)。
1. 選擇 **Create parameter group (建立參數群組)**。
1. 在 **Parameter group details** (參數群組詳細資訊) 頁面中，輸入下列資訊：
+ 針對 **Parameter group family** (參數群組系列)，選擇 postgres14。。
+ 針對 **Type** (類型)，選擇 DB Parameter Group (資料庫參數群組)。
+ 針對 **Group name** (群組名稱)，在操作內容中給與您的參數群組一個有意義的名稱。
+ 針對 **Description** (描述)，輸入有用的描述，以便您團隊中的其他成員可以輕鬆找到它。
1. 選擇**建立**。您的自訂資料庫參數群組是在 AWS 區域中建立。您現在可以遵循下列步驟修改 RDS for PostgreSQL 資料庫執行個體以使用它。
1. 從 Amazon RDS 功能表中選擇 **Databases** (資料庫)。
1. 從列出的 RDS for PostgreSQL 資料庫執行個體中選擇您想要哪一個與 TLE 搭配使用，然後選擇 **Modify** (修改)。
1. 在 Modify DB instance settings (修改資料庫執行個體設定) 頁面中，於 Additional configuration (其他組態) 區段中尋找 **Database options** (資料庫選項)，然後從選取器中選擇您的自訂資料庫參數群組。
1. 選擇 **Continue** (繼續) 以儲存變更。
1. 選擇 **Apply immediately** (立即套用)，以便您可以繼續設定 RDS for PostgreSQL 資料庫執行個體以使用 TLE。
若要繼續針對受信任語言延伸模組設定您的系統，請參閱 [在您的 RDS for PostgreSQL 資料庫執行個體中設定受信任語言延伸模組](PostgreSQL_trusted_language_extension-setting-up.md)。
如需深入了解如何使用資料庫參數群組，請參閱 [Amazon RDS 資料庫執行個體的資料庫參數群組](USER_WorkingWithDBInstanceParamGroups.md)。
### AWS CLI
您可以避免在使用 CLI 命令時指定 `--region` 引數，方法是使用您的預設 AWS 區域來設定您的 AWS CLI 。如需詳細資訊，請參閱《AWS Command Line Interface 使用者指南》**中的[組態基礎概念](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config)。
**建立自訂資料庫參數群組，並將其與 RDS for PostgreSQL 資料庫執行個體搭配使用**
1. 使用 [create-db-parameter-group](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-parameter-group.html) AWS CLI 命令，根據 postgres14 為您的 建立自訂資料庫參數群組 AWS 區域。
對於 Linux、macOS 或 Unix：
```
aws rds create-db-parameter-group \
--region aws-region \
--db-parameter-group-name custom-params-for-pg-tle \
--db-parameter-group-family postgres14 \
--description "My custom DB parameter group for Trusted Language Extensions"
```
在 Windows 中：
```
aws rds create-db-parameter-group ^
--region aws-region ^
--db-parameter-group-name custom-params-for-pg-tle ^
--db-parameter-group-family postgres14 ^
--description "My custom DB parameter group for Trusted Language Extensions"
```
您的自訂資料庫參數群組可在 AWS 區域中使用，因此您可以修改 RDS for PostgreSQL 資料庫叢集以使用它。
1. 使用 [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html) AWS CLI 命令，將您的自訂資料庫參數群組套用至 您的 RDS for PostgreSQL 資料庫執行個體。此命令會立即重新啟動作用中執行個體。
對於 Linux、macOS 或 Unix：
```
aws rds modify-db-instance \
--region aws-region \
--db-instance-identifier your-instance-name \
--db-parameter-group-name custom-params-for-pg-tle \
--apply-immediately
```
在 Windows 中：
```
aws rds modify-db-instance ^
--region aws-region ^
--db-instance-identifier your-instance-name ^
--db-parameter-group-name custom-params-for-pg-tle ^
--apply-immediately
```
若要繼續針對受信任語言延伸模組設定您的系統，請參閱 [在您的 RDS for PostgreSQL 資料庫執行個體中設定受信任語言延伸模組](PostgreSQL_trusted_language_extension-setting-up.md)。
如需更多詳細資訊，請參閱 [Amazon RDS 的參數群組](USER_WorkingWithParamGroups.md)。
# 在您的 RDS for PostgreSQL 資料庫執行個體中設定受信任語言延伸模組
下列步驟假設您的 RDS for PostgreSQL 資料庫執行個體與自訂資料庫參數群組相關聯。您可以針對這些步驟使用 AWS 管理主控台 或 AWS CLI。
當您在 RDS for PostgreSQL 資料庫執行個體中設定受信任語言延伸模組時，可以將其安裝在特定資料庫中，供具有該資料庫許可的資料庫使用者使用。
## 主控台
**設定受信任語言延伸模組**
使用屬於 `rds_superuser` 群組 (角色) 成員的帳戶執行下列步驟。
1. 登入 AWS 管理主控台，開啟位於 [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/) 的 Amazon RDS 主控台。
1. 在導覽窗格中，選擇您的 RDS for PostgreSQL 資料庫執行個體。
1. 針對您的 開啟 **Configuration** (組態) 索引標籤。RDS for PostgreSQL 資料庫執行個體。在執行個體詳細資訊之間，尋找 **Parameter group** (參數群組) 連結。
1. 選擇連結以開啟與 相關聯的自訂參數。RDS for PostgreSQL 資料庫執行個體。
1. 在 **Parameters** (參數) 搜尋欄位中，輸入 `shared_pre` 以尋找 `shared_preload_libraries` 參數。
1. 選擇 **Edit parameters** (編輯參數) 以存取屬性值。
1. 在 **Values** (值) 欄位中，將 `pg_tle` 新增至清單。使用逗號區隔值清單中的項目。
![\[已新增 pg_tle 之 shared_preload_libraries 參數的影像。\]](http://docs.aws.amazon.com/zh_tw/AmazonRDS/latest/UserGuide/images/apg_rpg_shared_preload_pg_tle.png)
1. 重新啟動 RDS for PostgreSQL 資料庫執行個體，以便您對 `shared_preload_libraries` 參數所做的變更生效。
1. 當執行個體可用時，請驗證 `pg_tle` 是否已初始化。使用 `psql` 連線至 RDS for PostgreSQL 資料庫執行個體，然後執行下列命令。
```
SHOW shared_preload_libraries;
shared_preload_libraries
--------------------------
rdsutils,pg_tle
(1 row)
```
1. 在初始化 `pg_tle` 延伸模組之後，您現在可以建立延伸模組。
```
CREATE EXTENSION pg_tle;
```
您可以使用下列 `psql` 中繼命令，驗證是否已安裝延伸模組。
```
labdb=> \dx
List of installed extensions
Name | Version | Schema | Description
---------+---------+------------+--------------------------------------------
pg_tle | 1.0.1 | pgtle | Trusted-Language Extensions for PostgreSQL
plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language
```
1. 在設定時，將 `pgtle_admin` 角色授予您已針對 RDS for PostgreSQL 資料庫執行個體建立的主要使用者名稱。如果您接受預設值，其為 `postgres`。
```
labdb=> GRANT pgtle_admin TO postgres;
GRANT ROLE
```
您可以使用 `psql` 中繼命令來驗證授予是否已發生，如下列範例所示。只有 `pgtle_admin` 和 `postgres` 角色會顯示在輸出中。如需詳細資訊，請參閱 [了解 rds\$1superuser 角色](Appendix.PostgreSQL.CommonDBATasks.Roles.rds_superuser.md)。
```
labdb=> \du
List of roles
Role name | Attributes | Member of
-----------------+---------------------------------+-----------------------------------
pgtle_admin | Cannot login | {}
postgres | Create role, Create DB +| {rds_superuser,pgtle_admin}
| Password valid until infinity |...
```
1. 使用 `\q` 中繼命令關閉 `psql` 工作階段。
```
\q
```
若要開始建立 TLE 延伸模組，請參閱 [範例：使用 SQL 建立受信任語言延伸模組](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md#PostgreSQL_trusted_language_extension-simple-example)。
## AWS CLI
您可以避免在使用 CLI 命令時指定 `--region` 引數，方法是使用您的預設 AWS 區域來設定您的 AWS CLI。如需詳細資訊，請參閱《AWS Command Line Interface 使用者指南》**中的[組態基礎概念](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config)。
**設定受信任語言延伸模組**
1. 使用 [modify-db-parameter-group](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-parameter-group.html) AWS CLI 命令，將 `pg_tle` 新增至 `shared_preload_libraries` 參數。
```
aws rds modify-db-parameter-group \
--db-parameter-group-name custom-param-group-name \
--parameters "ParameterName=shared_preload_libraries,ParameterValue=pg_tle,ApplyMethod=pending-reboot" \
--region aws-region
```
1. 使用 [reboot-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/reboot-db-instance) AWS CLI 命令重新啟動 RDS for PostgreSQL 資料庫執行個體，並初始化 `pg_tle` 程式庫。
```
aws rds reboot-db-instance \
--db-instance-identifier your-instance \
--region aws-region
```
1. 當執行個體可用時，您可以驗證 `pg_tle` 是否已初始化。使用 `psql` 連線至 RDS for PostgreSQL 資料庫執行個體，然後執行下列命令。
```
SHOW shared_preload_libraries;
shared_preload_libraries
--------------------------
rdsutils,pg_tle
(1 row)
```
在初始化 `pg_tle` 之後，您現在可以建立延伸模組。
```
CREATE EXTENSION pg_tle;
```
1. 在設定時，將 `pgtle_admin` 角色授予您已針對 RDS for PostgreSQL 資料庫執行個體建立的主要使用者名稱。如果您接受預設值，其為 `postgres`。
```
GRANT pgtle_admin TO postgres;
GRANT ROLE
```
1. 關閉 `psql` 工作階段，如下所示。
```
labdb=> \q
```
若要開始建立 TLE 延伸模組，請參閱 [範例：使用 SQL 建立受信任語言延伸模組](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md#PostgreSQL_trusted_language_extension-simple-example)。
# 適用於 PostgreSQL 的受信任語言延伸模組概觀
適用於 PostgreSQL 的受信任語言延伸模組是一種 PostgreSQL 延伸模組，而您使用您設定其他 PostgreSQL 延伸模組的同一方式，將其安裝在 RDS for PostgreSQLR 資料庫執行個體中。在 pgAdmin 用戶端工具中範例資料庫的下列影像中，您可以檢視構成 `pg_tle` 延伸模組的一些元件。
![\[此圖顯示構成 TLE 開發套件的一些元件。\]](http://docs.aws.amazon.com/zh_tw/AmazonRDS/latest/UserGuide/images/apg-pg_tle-installed-view-in-pgAdmin.png)
您可以查看下列詳細資訊。
1. 適用於 PostgreSQL 的受信任語言延伸模組 (TLE) 開發套件會封裝為 `pg_tle` 延伸模組。因此，`pg_tle` 會新增至其安裝所在資料庫的可用延伸模組。
1. TLE 有其自己的結構描述 (`pgtle`)。此結構描述包含協助程式函數 (3)，用於安裝和管理您建立的延伸模組。
1. TLE 提供了十幾個協助程式函數，用於安裝、註冊和管理您的延伸模組。若要進一步了解這些函數，請參閱[適用於 PostgreSQL 的受信任語言延伸模組的函數參考](PostgreSQL_trusted_language_extension-functions-reference.md)。
`pg_tle` 延伸套件的其他元件包含下列項目：
+ **`pgtle_admin` 角色** – 安裝 `pg_tle` 延伸模組時會建立 `pgtle_admin` 角色。此角色具有特殊權限，且應如此對待。強烈建議您在將 `pgtle_admin` 角色授予資料庫使用者時遵循*最低權限*原則。換句話說，只將 `pgtle_admin` 角色授予資料庫使用者，允許其建立、安裝和管理新的 TLE 延伸模組，例如 `postgres`。
+ **`pgtle.feature_info` 資料表** – `pgtle.feature_info` 資料表是受保護的資料表，其中包含 TLE、掛鉤，以及其使用的自訂預存程序和函數的相關資訊。如果具有 `pgtle_admin` 權限，則您可以使用下列受信任語言延伸模組函數，在資料表中新增和更新該資訊。
+ [pgtle.register\$1feature](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.register_feature)
+ [pgtle.register\$1feature\$1if\$1not\$1exists](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.register_feature_if_not_exists)
+ [pgtle.unregister\$1feature](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.unregister_feature)
+ [pgtle.unregister\$1feature\$1if\$1exists](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.unregister_feature_if_exists)
# 針對 RDS for PostgreSQL 建立 TLE 延伸模組
您可以在任何已安裝延伸模組的 RDS for PostgreSQL 資料庫執行個體中安裝使用 TLE 建立的任何 `pg_tle` 延伸模組。`pg_tle` 延伸模組的範圍會限定在其安裝所在的 PostgreSQL 資料庫。您使用 TLE 建立的延伸模組，其範圍會限定在相同的資料庫。
使用各種 `pgtle` 函數來安裝構成 TLE 延伸模組的程式碼。下列受信任語言延伸模組函數全都需要 `pgtle_admin` 角色。
+ [pgtle.install\$1extension](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.install_extension)
+ [pgtle.install\$1update\$1path](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.install_update_path)
+ [pgtle.register\$1feature](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.register_feature)
+ [pgtle.register\$1feature\$1if\$1not\$1exists](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.register_feature_if_not_exists)
+ [pgtle.set\$1default\$1version](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.set_default_version)
+ [pgtle.uninstall\$1extension(name)](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.uninstall_extension-name)
+ [pgtle.uninstall\$1extension(name, version)](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.uninstall_extension-name-version)
+ [pgtle.uninstall\$1extension\$1if\$1exists](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.uninstall_extension_if_exists)
+ [pgtle.uninstall\$1update\$1path](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.uninstall_update_path)
+ [pgtle.uninstall\$1update\$1path\$1if\$1exists](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.uninstall_update_path_if_exists)
+ [pgtle.unregister\$1feature](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.unregister_feature)
+ [pgtle.unregister\$1feature\$1if\$1exists](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.unregister_feature_if_exists)
## 範例：使用 SQL 建立受信任語言延伸模組
下列範例說明如何建立名為 `pg_distance` 的 TLE 延伸模組，其中包含一些 SQL 函數，用於使用不同的公式計算距離。在清單中，您可以找到用於計算曼哈頓距離的函數，以及計算歐幾里得距離的函數。如需這些公式之間差異的詳細資訊，請參閱 Wikipedia 中的[出租車幾何](https://en.wikipedia.org/wiki/Taxicab_geometry)和[歐幾里得幾何](https://en.wikipedia.org/wiki/Euclidean_geometry)。
如果您已按照[在您的 RDS for PostgreSQL 資料庫執行個體中設定受信任語言延伸模組](PostgreSQL_trusted_language_extension-setting-up.md)中所述設定 `pg_tle` 延伸模組，則可以在自己的 RDS for PostgreSQL 資料庫執行個體中使用此範例。
**注意**
您必須具有 `pgtle_admin` 角色的權限才能遵循此程序。
**建立範例 TLE 延伸模組**
下列步驟會使用名為 `labdb` 的範例資料庫。此資料庫是由 `postgres` 主要使用者所擁有。`postgres` 角色也具有 `pgtle_admin` 角色的權限。
1. 使用 `psql` 連線到 RDS for PostgreSQL 資料庫執行個體。
```
psql --host=db-instance-123456789012.aws-region.rds.amazonaws.com
--port=5432 --username=postgres --password --dbname=labdb
```
1. 複製下列程式碼並將其貼入 `psql` 工作階段主控台中，來建立名為 `pg_distance` 的 TLE 延伸模組。
```
SELECT pgtle.install_extension
(
'pg_distance',
'0.1',
'Distance functions for two points',
$_pg_tle_$
CREATE FUNCTION dist(x1 float8, y1 float8, x2 float8, y2 float8, norm int)
RETURNS float8
AS $$
SELECT (abs(x2 - x1) ^ norm + abs(y2 - y1) ^ norm) ^ (1::float8 / norm);
$$ LANGUAGE SQL;
CREATE FUNCTION manhattan_dist(x1 float8, y1 float8, x2 float8, y2 float8)
RETURNS float8
AS $$
SELECT dist(x1, y1, x2, y2, 1);
$$ LANGUAGE SQL;
CREATE FUNCTION euclidean_dist(x1 float8, y1 float8, x2 float8, y2 float8)
RETURNS float8
AS $$
SELECT dist(x1, y1, x2, y2, 2);
$$ LANGUAGE SQL;
$_pg_tle_$
);
```
您會看到如下輸出。
```
install_extension
---------------
t
(1 row)
```
構成 `pg_distance` 延伸模組的成品現在已安裝在您的資料庫中。這些成品包括延伸模組的控制檔和程式碼，這些是必須存在的項目，如此才能使用 `CREATE EXTENSION` 命令建立延伸模組。換句話說，您仍然需要建立延伸模組，以使其函數可供資料庫使用者使用。
1. 若要建立延伸模組，請使用 `CREATE EXTENSION` 命令，如您對任何其他延伸模組所做一樣。與其他延伸模組一樣，資料庫使用者需要在資料庫中具有 `CREATE` 權限。
```
CREATE EXTENSION pg_distance;
```
1. 若要測試 `pg_distance` TLE 延伸模組，您可以使用它，計算四點之間的[曼哈頓距離](https://en.wikipedia.org/wiki/Taxicab_geometry)。
```
labdb=> SELECT manhattan_dist(1, 1, 5, 5);
8
```
若要計算同一組點之間的[歐幾里得距離](https://en.wikipedia.org/wiki/Euclidean_geometry)，您可以使用下列命令。
```
labdb=> SELECT euclidean_dist(1, 1, 5, 5);
5.656854249492381
```
`pg_distance` 延伸模組會在資料庫中載入函數，並使其可供具有資料庫權限的任何使用者使用。
## 修改 TLE 延伸模組
若要改善此 TLE 延伸模組中封裝之函數的查詢效能，請將下列兩個 PostgreSQL 屬性新增至其規格。
+ `IMMUTABLE` – `IMMUTABLE` 屬性確保查詢最佳化工具可以使用最佳化來改善查詢回應時間。如需詳細資訊，請參閱 PostgreSQL 文件中的[函數波動類別](https://www.postgresql.org/docs/current/xfunc-volatility.html)。
+ `PARALLEL SAFE` – `PARALLEL SAFE` 屬性是允許 PostgreSQL 以平行模式執行函數的另一個屬性。如需詳細資訊，請參閱 PostgreSQL 文件中的 [CREATE FUNCTION](https://www.postgresql.org/docs/current/sql-createfunction.html)。
在下列範例中，您可以看到如何使用 `pgtle.install_update_path` 函數將這些屬性新增到每個函數，以建立 `pg_distance` TLE 延伸模組的版本 `0.2`。如需此函數狀態的詳細資訊，請參閱 [pgtle.install\$1update\$1path](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.install_update_path)。您必須具有 `pgtle_admin` 角色才能執行此任務。
**更新現有 TLE 延伸模組並指定預設版本**
1. 使用 `psql` 或其他用戶端工具 (例如 pgAdmin)，連線至 RDS for PostgreSQL 資料庫執行個體。
```
psql --host=db-instance-123456789012.aws-region.rds.amazonaws.com
--port=5432 --username=postgres --password --dbname=labdb
```
1. 複製下列程式碼並將其貼入 `psql` 工作階段主控台中，來修改現有的 TLE 延伸模組。
```
SELECT pgtle.install_update_path
(
'pg_distance',
'0.1',
'0.2',
$_pg_tle_$
CREATE OR REPLACE FUNCTION dist(x1 float8, y1 float8, x2 float8, y2 float8, norm int)
RETURNS float8
AS $$
SELECT (abs(x2 - x1) ^ norm + abs(y2 - y1) ^ norm) ^ (1::float8 / norm);
$$ LANGUAGE SQL IMMUTABLE PARALLEL SAFE;
CREATE OR REPLACE FUNCTION manhattan_dist(x1 float8, y1 float8, x2 float8, y2 float8)
RETURNS float8
AS $$
SELECT dist(x1, y1, x2, y2, 1);
$$ LANGUAGE SQL IMMUTABLE PARALLEL SAFE;
CREATE OR REPLACE FUNCTION euclidean_dist(x1 float8, y1 float8, x2 float8, y2 float8)
RETURNS float8
AS $$
SELECT dist(x1, y1, x2, y2, 2);
$$ LANGUAGE SQL IMMUTABLE PARALLEL SAFE;
$_pg_tle_$
);
```
您會看到如下回應：
```
install_update_path
---------------------
t
(1 row)
```
您可以將此版本的延伸模組設為預設版本，這樣資料庫使用者就不必在資料庫中建立或更新延伸模組時指定版本。
1. 若要指定 TLE 延伸模組的修改版本 (版本 0.2) 為預設版本，請使用 `pgtle.set_default_version` 函數，如下列範例所示。
```
SELECT pgtle.set_default_version('pg_distance', '0.2');
```
如需此函數狀態的詳細資訊，請參閱 [pgtle.set\$1default\$1version](PostgreSQL_trusted_language_extension-functions-reference.md#pgtle.set_default_version)。
1. 在程式碼就位之後，您可以使用 `ALTER EXTENSION ... UPDATE` 命令，以尋常方式更新已安裝的 TLE 延伸模組，如這裡所示：
```
ALTER EXTENSION pg_distance UPDATE;
```
# 從資料庫中捨棄您的 TLE 延伸模組
您可以採取您對其他 PostgreSQL 延伸模組所用的同一方式，使用 `DROP EXTENSION` 命令來捨棄 TLE 延伸模組。捨棄延伸模組並不會移除構成延伸模組的安裝檔案，因而允許使用者重新建立延伸模組。若要移除延伸模組及其安裝檔案，請執行下列兩步驟程序。
**捨棄 TLE 延伸模組並移除其安裝檔案**
1. 使用 `psql` 或其他用戶端工具，連線至 RDS for PostgreSQL 資料庫執行個體。
```
psql --host=.111122223333.aws-region.rds.amazonaws.com --port=5432 --username=postgres --password --dbname=dbname
```
1. 捨棄延伸模組，如同您對任何 PostgreSQL 延伸模組所做一般。
```
DROP EXTENSION your-TLE-extension
```
例如，如果您如[範例：使用 SQL 建立受信任語言延伸模組](PostgreSQL_trusted_language_extension-creating-TLE-extensions.md#PostgreSQL_trusted_language_extension-simple-example)所述建立 `pg_distance` 延伸模組，則可以捨棄延伸模組，如下所示。
```
DROP EXTENSION pg_distance;
```
您會看到輸出，確認已捨棄延伸模組，如下所示。
```
DROP EXTENSION
```
此時，延伸模組在資料庫中不再處於作用中狀態。不過，其安裝檔案和控制檔案仍然可在資料庫中使用，因此資料庫使用者可以再次建立延伸模組 (如果想要的話)。
+ 如果想要延伸模組檔案保持不變，以便資料庫使用者可以建立您的 TLE 延伸模組，您可以在此停止。
+ 如果想要移除所有構成延伸模組的檔案，請繼續下一個步驟。
1. 若要移除延伸模組的所有安裝檔案，請使用 `pgtle.uninstall_extension` 函數。此函數會移除延伸模組的所有程式碼和控制檔。
```
SELECT pgtle.uninstall_extension('your-tle-extension-name');
```
例如，若要移除所有 `pg_distance` 安裝檔案，請使用下列命令。
```
SELECT pgtle.uninstall_extension('pg_distance');
uninstall_extension
---------------------
t
(1 row)
```
# 解除安裝適用於 PostgreSQL 的受信任語言延伸模組
如果您再也不要使用 TLE 建立自己的 TLE 延伸模組，則可以捨棄 `pg_tle` 延伸模組並移除所有成品。此動作包括捨棄資料庫中的任何 TLE 延伸模組，以及捨棄 `pgtle` 結構描述。
**從資料庫中捨棄 `pg_tle` 延伸模組及其結構描述**
1. 使用 `psql` 或其他用戶端工具，連線至 RDS for PostgreSQL 資料庫執行個體。
```
psql --host=.111122223333.aws-region.rds.amazonaws.com --port=5432 --username=postgres --password --dbname=dbname
```
1. 從資料庫中捨棄 `pg_tle` 延伸模組。如果您自己的 TLE 延伸模組仍在資料庫中執行，您也需要捨棄這些延伸模組。若要這樣做，您可以使用 `CASCADE` 關鍵字，如下所示。
```
DROP EXTENSION pg_tle CASCADE;
```
如果 `pg_tle` 延伸模組在資料庫中仍未作用中，則您不需要使用 `CASCADE` 關鍵字。
1. 捨棄 `pgtle` 結構描述。此動作會移除資料庫中的所有管理函數。
```
DROP SCHEMA pgtle CASCADE;
```
此命令會在程序完成時傳回下列內容。
```
DROP SCHEMA
```
`pg_tle` 延伸模組、其結構描述和函數，以及所有成品都會遭到移除。若要使用 TLE 建立新的延伸模組，請再次完成設定程序。如需更多詳細資訊，請參閱 [在您的 RDS for PostgreSQL 資料庫執行個體中設定受信任語言延伸模組](PostgreSQL_trusted_language_extension-setting-up.md)。
# 搭配您的延伸模組使用 PostgreSQL 掛鉤
*掛鉤*是 PostgreSQL 中提供的回呼機制，允許開發人員在一般資料庫操作期間呼叫自訂函數或其他常式。TLE 開發套件支援 PostgreSQL 掛鉤，以便您可以在執行時整合自訂函數與 PostgreSQL 行為。例如，您可以使用掛鉤，將身分驗證程序與您自己的自訂程式碼建立關聯，或因應您的特定需求修改查詢規劃和執行程序。
您的 TLE 延伸模組可以使用掛鉤。如果掛鉤在範圍內是全域的，則其在所有資料庫之中都適用。因此，如果您的 TLE 延伸模組使用全域掛鉤，則您需要在使用者可以存取的所有資料庫中建立 TLE 延伸模組。
當使用 `pg_tle` 延伸模組來建置您自己的受信任語言延伸模組時，您可以使用 SQL API 中可用的掛鉤來建置延伸模組的函數。您應該使用 `pg_tle` 註冊任何掛鉤。對於某些掛鉤，您可能還需要設定各種組態參數。例如，`passcode` 檢查掛鉤可以設為開啟、關閉或需要。如需可用 `pg_tle` 掛鉤之特定需求的詳細資訊，請參閱 [適用於 PostgreSQL 的受信任語言延伸模組的掛鉤參考](PostgreSQL_trusted_language_extension-hooks-reference.md)。
## 範例：建立使用 PostgreSQL 掛鉤的延伸模組
本節中討論的範例使用 PostgreSQL 掛鉤，來檢查在特定 SQL 操作期間提供的密碼，並防止資料庫使用者將其密碼設為 `password_check.bad_passwords` 資料表中包含的任何密碼。該資料表包含前十大最常用但容易破解的密碼選擇。
若要在您的 RDS for PostgreSQL 資料庫執行個體中設定此範例，您必須已安裝受信任語言延伸模組。如需詳細資訊，請參閱 [在您的 RDS for PostgreSQL 資料庫執行個體中設定受信任語言延伸模組](PostgreSQL_trusted_language_extension-setting-up.md)。
**設定密碼檢查掛鉤範例**
1. 使用 `psql` 連線到 RDS for PostgreSQL 資料庫執行個體。
```
psql --host=db-instance-123456789012.aws-region.rds.amazonaws.com
--port=5432 --username=postgres --password --dbname=labdb
```
1. 從 [密碼檢查掛鉤程式碼清單](#PostgreSQL_trusted_language_extension-example-hook_code_listing) 中複製程式碼，並將其貼入您的資料庫中。
```
SELECT pgtle.install_extension (
'my_password_check_rules',
'1.0',
'Do not let users use the 10 most commonly used passwords',
$_pgtle_$
CREATE SCHEMA password_check;
REVOKE ALL ON SCHEMA password_check FROM PUBLIC;
GRANT USAGE ON SCHEMA password_check TO PUBLIC;
CREATE TABLE password_check.bad_passwords (plaintext) AS
VALUES
('123456'),
('password'),
('12345678'),
('qwerty'),
('123456789'),
('12345'),
('1234'),
('111111'),
('1234567'),
('dragon');
CREATE UNIQUE INDEX ON password_check.bad_passwords (plaintext);
CREATE FUNCTION password_check.passcheck_hook(username text, password text, password_type pgtle.password_types, valid_until timestamptz, valid_null boolean)
RETURNS void AS $$
DECLARE
invalid bool := false;
BEGIN
IF password_type = 'PASSWORD_TYPE_MD5' THEN
SELECT EXISTS(
SELECT 1
FROM password_check.bad_passwords bp
WHERE ('md5' || md5(bp.plaintext || username)) = password
) INTO invalid;
IF invalid THEN
RAISE EXCEPTION 'Cannot use passwords from the common password dictionary';
END IF;
ELSIF password_type = 'PASSWORD_TYPE_PLAINTEXT' THEN
SELECT EXISTS(
SELECT 1
FROM password_check.bad_passwords bp
WHERE bp.plaintext = password
) INTO invalid;
IF invalid THEN
RAISE EXCEPTION 'Cannot use passwords from the common password dictionary';
END IF;
END IF;
END
$$ LANGUAGE plpgsql SECURITY DEFINER;
GRANT EXECUTE ON FUNCTION password_check.passcheck_hook TO PUBLIC;
SELECT pgtle.register_feature('password_check.passcheck_hook', 'passcheck');
$_pgtle_$
);
```
將延伸模組載入資料庫後，您會看到如下輸出。
```
install_extension
-------------------
t
(1 row)
```
1. 在仍然連線到資料庫時，您現在可以建立延伸模組。
```
CREATE EXTENSION my_password_check_rules;
```
1. 您可以使用下列 `psql` 中繼命令，確認已在資料庫中建立延伸模組。
```
\dx
List of installed extensions
Name | Version | Schema | Description
-------------------------+---------+------------+-------------------------------------------------------------
my_password_check_rules | 1.0 | public | Prevent use of any of the top-ten most common bad passwords
pg_tle | 1.0.1 | pgtle | Trusted-Language Extensions for PostgreSQL
plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language
(3 rows)
```
1. 開啟另一個要使用 AWS CLI 的終端機工作階段。您需要修改自訂資料庫參數群組，以開啟密碼檢查掛鉤。若要這麼做，請使用 [modify-db-parameter-group](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-parameter-group.html) 命令，如下列範例所示。
```
aws rds modify-db-parameter-group \
--region aws-region \
--db-parameter-group-name your-custom-parameter-group \
--parameters "ParameterName=pgtle.enable_password_check,ParameterValue=on,ApplyMethod=immediate"
```
在成功開啟參數時，您會看到如下輸出。
```
(
"DBParameterGroupName": "docs-lab-parameters-for-tle"
}
```
可能需要幾分鐘，對參數群組設定所做的變更才會生效。不過，此參數是動態參數，因此您不需要重新啟動 RDS for PostgreSQL 資料庫執行個體，設定即可生效。
1. 開啟 `psql` 工作階段並查詢資料庫，以驗證密碼檢查掛鉤是否已開啟。
```
labdb=> SHOW pgtle.enable_password_check;
pgtle.enable_password_check
-----------------------------
on
(1 row)
```
密碼檢查掛鉤現在處於作用中狀態。您可以建立新角色並使用其中一個錯誤密碼來對它進行測試，如下列範例所示。
```
CREATE ROLE test_role PASSWORD 'password';
ERROR: Cannot use passwords from the common password dictionary
CONTEXT: PL/pgSQL function password_check.passcheck_hook(text,text,pgtle.password_types,timestamp with time zone,boolean) line 21 at RAISE
SQL statement "SELECT password_check.passcheck_hook(
$1::pg_catalog.text,
$2::pg_catalog.text,
$3::pgtle.password_types,
$4::pg_catalog.timestamptz,
$5::pg_catalog.bool)"
```
為了方便閱讀，輸出已經過格式化處理。
下列範例顯示 `pgsql` 互動式中繼命令 `\password` 行為也受密碼檢查掛鉤的影響。
```
postgres=> SET password_encryption TO 'md5';
SET
postgres=> \password
Enter new password for user "postgres":*****
Enter it again:*****
ERROR: Cannot use passwords from the common password dictionary
CONTEXT: PL/pgSQL function password_check.passcheck_hook(text,text,pgtle.password_types,timestamp with time zone,boolean) line 12 at RAISE
SQL statement "SELECT password_check.passcheck_hook($1::pg_catalog.text, $2::pg_catalog.text, $3::pgtle.password_types, $4::pg_catalog.timestamptz, $5::pg_catalog.bool)"
```
如果需要，您可以捨棄此 TLE 延伸模組並解除安裝其來源檔案。如需更多詳細資訊，請參閱 [從資料庫中捨棄您的 TLE 延伸模組從資料庫中捨棄您的 TLE 延伸模組](PostgreSQL_trusted_language_extension-creating-TLE-extensions.dropping-TLEs.md)。
### 密碼檢查掛鉤程式碼清單
此處顯示的範例程式碼定義了 `my_password_check_rules` TLE 延伸模組的規格。當您複製此程式碼並將其貼入資料庫中時，`my_password_check_rules` 延伸模組的程式碼會載入至資料庫，而且 `password_check` 掛鉤會進行註冊以供該延伸模組使用。
```
SELECT pgtle.install_extension (
'my_password_check_rules',
'1.0',
'Do not let users use the 10 most commonly used passwords',
$_pgtle_$
CREATE SCHEMA password_check;
REVOKE ALL ON SCHEMA password_check FROM PUBLIC;
GRANT USAGE ON SCHEMA password_check TO PUBLIC;
CREATE TABLE password_check.bad_passwords (plaintext) AS
VALUES
('123456'),
('password'),
('12345678'),
('qwerty'),
('123456789'),
('12345'),
('1234'),
('111111'),
('1234567'),
('dragon');
CREATE UNIQUE INDEX ON password_check.bad_passwords (plaintext);
CREATE FUNCTION password_check.passcheck_hook(username text, password text, password_type pgtle.password_types, valid_until timestamptz, valid_null boolean)
RETURNS void AS $$
DECLARE
invalid bool := false;
BEGIN
IF password_type = 'PASSWORD_TYPE_MD5' THEN
SELECT EXISTS(
SELECT 1
FROM password_check.bad_passwords bp
WHERE ('md5' || md5(bp.plaintext || username)) = password
) INTO invalid;
IF invalid THEN
RAISE EXCEPTION 'Cannot use passwords from the common password dictionary';
END IF;
ELSIF password_type = 'PASSWORD_TYPE_PLAINTEXT' THEN
SELECT EXISTS(
SELECT 1
FROM password_check.bad_passwords bp
WHERE bp.plaintext = password
) INTO invalid;
IF invalid THEN
RAISE EXCEPTION 'Cannot use passwords from the common password dictionary';
END IF;
END IF;
END
$$ LANGUAGE plpgsql SECURITY DEFINER;
GRANT EXECUTE ON FUNCTION password_check.passcheck_hook TO PUBLIC;
SELECT pgtle.register_feature('password_check.passcheck_hook', 'passcheck');
$_pgtle_$
);
```
# 在 TLE 中使用自訂資料類型
PostgreSQL 支援註冊新基底類型 (也稱為純量類型) 的命令，以便有效處理資料庫中複雜的資料結構。基底類型可讓您自訂在內部儲存資料的方式，以及如何將資料與外部文字表示法相互轉換。這些自訂資料類型在擴充 PostgreSQL 以支援功能定義域時很實用，因為這些定義域的內建類型 (如數字或文字) 無法提供足夠的搜尋語意。
RDS for PostgreSQL 可讓您在信任的語言延伸模組中建立自訂資料類型，並定義功能來支援這些新資料類型的 SQL 和索引操作。以下版本提供自訂資料類型：
+ RDS for PostgreSQL 15.4 及更高的 15 版
+ RDS for PostgreSQL 14.9 及更高的 14 版
+ RDS for PostgreSQL 13.12 及更高的 13 版
如需詳細資訊，請參閱[信任的語言基底類型](https://github.com/aws/pg_tle/blob/main/docs/09_datatypes.md)。
# 適用於 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');
```
# 適用於 PostgreSQL 的受信任語言延伸模組的掛鉤參考
適用於 PostgreSQL 的受信任語言延伸模組支援 PostgreSQL 掛鉤。*掛鉤*是開發人員可用於擴充 PostgreSQL 核心功能的內部回呼機制。透過使用掛鉤，開發人員可以實作自己的函數或程序，以在各種資料庫操作期間使用，從而以某種方式修改 PostgreSQL 的行為。例如，您可以使用 `passcheck` 掛鉤，來自訂 PostgreSQL 在為使用者 (角色) 建立或變更密碼時如何處理所提供的密碼。
檢視下列文件，以了解 TLE 延伸模組可用的 passcheck 勾點。若要進一步了解可用的勾點，包括用戶端驗證勾點，請參閱[受信任語言延伸模組勾點](https://github.com/aws/pg_tle/blob/main/docs/04_hooks.md)。
## 密碼檢查掛鉤 (passcheck)
`passcheck` 掛鉤用來針對下列 SQL 命令和 `psql` 中繼命令自訂密碼檢查過程中的 PostgreSQL 行為。
+ `CREATE ROLE username ...PASSWORD` – 如需詳細資訊，請參閱 PostgreSQL 文件中的 [CREATE ROLE](https://www.postgresql.org/docs/current/sql-createrole.html)。
+ `ALTER ROLE username...PASSWORD` – 如需詳細資訊，請參閱 PostgreSQL 文件中的 [ALTER ROLE](https://www.postgresql.org/docs/current/sql-alterrole.html)。
+ `\password username` – 此互動式 `psql` 中繼命令透過在透明地使用 `ALTER ROLE ... PASSWORD` 語法之前對密碼進行雜湊處理，來安全地變更所指定使用者的密碼。中繼命令是 `ALTER ROLE ... PASSWORD` 命令的安全包裝函式，因此掛鉤適用於 `psql` 中繼命令的行為。
如需範例，請參閱 [密碼檢查掛鉤程式碼清單](PostgreSQL_trusted_language_extension.overview.tles-and-hooks.md#PostgreSQL_trusted_language_extension-example-hook_code_listing)。
**Contents**
+ [函數原型](#passcheck_hook-prototype)
+ [引數](#passcheck_hook-arguments)
+ [Configuration](#passcheck_hook-configuration)
+ [使用須知](#passcheck_hook-usage)
### 函數原型
```
passcheck_hook(username text, password text, password_type pgtle.password_types, valid_until timestamptz, valid_null boolean)
```
### 引數
`passcheck` 掛鉤函數採用下列引數：
+ `username` – 設定密碼之角色 (使用者名稱) 的名稱 (以文字形式表示)。
+ `password` – 純文字或雜湊密碼。輸入的密碼應符合 `password_type` 中指定的類型。
+ `password_type` – 指定密碼的 `pgtle.password_type` 格式。此 格式可以是下列其中一個選項：
+ `PASSWORD_TYPE_PLAINTEXT` – 純文字密碼。
+ `PASSWORD_TYPE_MD5` – 使用 MD5 (訊息摘要 5) 演算法進行雜湊處理的密碼。
+ `PASSWORD_TYPE_SCRAM_SHA_256` – 使用 SCRAM-SHA-256 演算法進行雜湊處理的密碼。
+ `valid_until` – 指定密碼變成無效的時間。此為選用引數。如果使用此引數，請將時間指定為 `timestamptz` 值。
+ `valid_null` – 如果將此布林值設為 `true`，則 `valid_until` 選項會設為 `NULL`。
### Configuration
此函數 `pgtle.enable_password_check` 可控制 passcheck 掛鉤是否作用中。passcheck 掛鉤有三種可能的設定。
+ `off` – 關閉 `passcheck` 密碼檢查掛鉤。這是預設值。
+ `on` – 開啟 `passcode` 密碼檢查掛鉤，以便針對資料表檢查密碼。
+ `require` – 需要定義密碼檢查掛鉤。
### 使用須知
若要開啟或關閉 `passcheck` 掛鉤，您需要針對 RDS for PostgreSQL 資料庫執行個體修改自訂資料庫參數群組。
對於 Linux、macOS 或 Unix：
```
aws rds modify-db-parameter-group \
--region aws-region \
--db-parameter-group-name your-custom-parameter-group \
--parameters "ParameterName=pgtle.enable_password_check,ParameterValue=on,ApplyMethod=immediate"
```
在 Windows 中：
```
aws rds modify-db-parameter-group ^
--region aws-region ^
--db-parameter-group-name your-custom-parameter-group ^
--parameters "ParameterName=pgtle.enable_password_check,ParameterValue=on,ApplyMethod=immediate"
```