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

# 使用 PL/Rust 以 Rust 語言撰寫 PostgreSQL 函數
<a name="PostgreSQL.Concepts.General.Using.PL_Rust"></a>

PL/Rust 是 PostgreSQL 的受信任 Rust 語言延伸模組。您可以將其用於預存程序、函數，以及可從 SQL 呼叫的其他程序性程式碼。下列版本提供 PL/Rust 語言延伸模組：
+ RDS for PostgreSQL 17.1 和更高的第 17 版
+ RDS for PostgreSQL 16.1 和更高的第 16 版
+ RDS for PostgreSQL 15.2-R2 及更高的 15 版本
+ RDS for PostgreSQL 14.9 及更高的 14 版本
+ RDS for PostgreSQL 13.12 及更高的 13 版本

如需詳細資訊，請參閱 GitHub 上的 [PL/Rust](https://github.com/tcdi/plrust#readme)。

**Topics**
+ [設定 PL/Rust](#PL_Rust-setting-up)
+ [使用 PL/Rust 建立函數](#PL_Rust-create-function)
+ [使用套件搭配 PL/Rust](#PL_Rust-crates)
+ [PL/Rust 限制](#PL_Rust-limitations)

## 設定 PL/Rust
<a name="PL_Rust-setting-up"></a>

若要在資料庫執行個體上安裝 plrust 延伸模組，請將 plrust 新增至與資料庫執行個體相關聯之資料庫參數群組中的 `shared_preload_libraries` 參數。安裝 plrust 延伸模組後，您可以建立函數。

若要修改 `shared_preload_libraries` 參數，您的資料庫執行個體必須與自訂參數群組相關聯。如需建立自訂資料庫參數群組的相關資訊，請參閱 [Amazon RDS 的參數群組](USER_WorkingWithParamGroups.md)。

您可以使用 AWS 管理主控台 或 安裝 plrust 擴充功能 AWS CLI。

下列步驟假設您的資料庫執行個體與自訂資料庫參數群組相關聯。

### 主控台
<a name="PL_Rust-setting-up.CON"></a>

**在 `shared_preload_libraries` 參數中安裝 plrust 延伸模組**

使用屬於 `rds_superuser` 群組 (角色) 成員的帳戶完成下列步驟。

1. 登入 AWS 管理主控台 ，並在 [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/)：// 開啟 Amazon RDS 主控台。

1. 在導覽窗格中，選擇 **Databases** (資料庫)。

1. 選擇資料庫執行個體的名稱以顯示其詳細資訊。

1. 開啟資料庫執行個體的**組態**索引標籤，然後尋找資料庫執行個體參數群組連結。

1. 選擇連結以開啟與資料庫執行個體相關聯的自訂參數。

1. 在 **Parameters** (參數) 搜尋欄位中，輸入 `shared_pre` 以尋找 **`shared_preload_libraries`** 參數。

1. 選擇 **Edit parameters** (編輯參數) 以存取屬性值。

1. 在**值**欄位中，將 plrust 新增至清單。使用逗號區隔值清單中的項目。

1. 重新啟動資料庫執行個體，以便您對 `shared_preload_libraries` 參數的變更生效。初始重新啟動可能需要額外的時間才能完成。

1. 當執行個體可用時，請驗證 plrust 是否已初始化。使用 `psql` 連線至資料庫執行個體，然後執行下列命令。

   ```
   SHOW shared_preload_libraries;
   ```

   您的輸出應該類似以下內容：

   ```
   shared_preload_libraries 
   --------------------------
   rdsutils,plrust
   (1 row)
   ```

### AWS CLI
<a name="PL_Rust-setting-up-CLI"></a>

**在 shared\$1preload\$1libraries 參數中安裝 plrust 延伸模組**

使用屬於 `rds_superuser` 群組 (角色) 成員的帳戶完成下列步驟。

1. 使用 [modify-db-parameter-group](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-parameter-group.html) AWS CLI 命令將 plrust 新增至 `shared_preload_libraries` 參數。

   ```
   aws rds modify-db-parameter-group \
      --db-parameter-group-name custom-param-group-name \
      --parameters "ParameterName=shared_preload_libraries,ParameterValue=plrust,ApplyMethod=pending-reboot" \
      --region aws-region
   ```

1. 使用 [reboot-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/reboot-db-instance) AWS CLI 命令重新啟動資料庫執行個體並初始化 plrust 程式庫。初始重新啟動可能需要額外的時間才能完成。

   ```
   aws rds reboot-db-instance \
       --db-instance-identifier your-instance \
       --region aws-region
   ```

1. 當執行個體可用時，您可以驗證 plrust 是否已初始化。使用 `psql` 連線至資料庫執行個體，然後執行下列命令。

   ```
   SHOW shared_preload_libraries;
   ```

   您的輸出應該類似以下內容：

   ```
   shared_preload_libraries
   --------------------------
   rdsutils,plrust
   (1 row)
   ```

## 使用 PL/Rust 建立函數
<a name="PL_Rust-create-function"></a>

PL/Rust 會將函數編譯為動態程式庫、載入它，然後執行它。

以下 Rust 函數會從陣列中篩選出倍數。

```
postgres=> CREATE LANGUAGE plrust;
CREATE EXTENSION
```

```
CREATE OR REPLACE FUNCTION filter_multiples(a BIGINT[], multiple BIGINT) RETURNS BIGINT[]
    IMMUTABLE STRICT
    LANGUAGE PLRUST AS
$$
    Ok(Some(a.into_iter().filter(|x| x.unwrap() % multiple != 0).collect()))
$$;
        
WITH gen_values AS (
SELECT ARRAY(SELECT * FROM generate_series(1,100)) as arr)
SELECT filter_multiples(arr, 3)
from gen_values;
```

## 使用套件搭配 PL/Rust
<a name="PL_Rust-crates"></a>

在 RDS for PostgreSQL 16.3-R2 和更高版本、15.7-R2 和更高的第 15 版、14.12-R2 和更高的第 14 版，以及 13.15-R2 和更高的第 13 版中，PL/Rust 支援額外的壓縮容器格式：
+ `url` 
+ `regex` 
+ `serde` 
+ `serde_json` 

在 RDS for PostgreSQL 15.5-R2 和更高版本、14.10-R2 和更高的第 14 版、13.13-R2 和更高的第 13 版中，PL/Rust 支援兩個額外的壓縮容器格式：
+ `croaring-rs` 
+ `num-bigint` 

從 Amazon RDS for PostgreSQL 15.4、14.9 及 13.12 版開始，PL/Rust 支援下列壓縮容器格式：
+ `aes` 
+ `ctr` 
+ `rand` 

這些套件僅支援預設功能。新的 RDS for PostgreSQL 版本可能包含更新的套件版本，而且可能不再支援較舊的套件版本。

請遵循執行主要版本升級的最佳實務來進行測試，了解您的 PL/Rust 函數是否與新的主要版本相容。如需詳細資訊，請參閱部落格 [Best practices for upgrading Amazon RDS to major and minor versions of PostgreSQL](https://aws.amazon.com/blogs/database/best-practices-for-upgrading-amazon-rds-to-major-and-minor-versions-of-postgresql/) (將 Amazon RDS 升級至 PostgreSQL 的主要和次要版本的最佳實務)，以及《Amazon RDS 使用者指南》中的[升級 Amazon RDS 的 PostgreSQL 資料庫引擎](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.PostgreSQL.html)。

[使用相依性](https://tcdi.github.io/plrust/use-plrust.html#use-dependencies)中提供了建立 PL/Rust 函數時使用相依性的範例。

## PL/Rust 限制
<a name="PL_Rust-limitations"></a>

根據預設，資料庫使用者無法使用 PL/Rust。若要提供 PL/Rust 的存取權，請以具有 rds\$1superuser 權限的使用者身分連線，然後執行下列命令：

```
postgres=> GRANT USAGE ON LANGUAGE PLRUST TO user;
```