本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 針對 RDS for PostgreSQL 建立 TLE 延伸模組
<a name="PostgreSQL_trusted_language_extension-creating-TLE-extensions"></a>

您可以在任何已安裝延伸模組的 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 建立受信任語言延伸模組
<a name="PostgreSQL_trusted_language_extension-simple-example"></a>

下列範例說明如何建立名為 `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 延伸模組
<a name="PostgreSQL_trusted_language_extension-simple-example.modify"></a>

若要改善此 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;
   ```