# 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>

DB インスタンスに plrust 拡張機能をインストールするには、DBインスタンスに関連付けられた DB パラメータグループの `shared_preload_libraries` パラメータに plrust を追加します。plrust 拡張機能をインストールすると、関数を作成できます。

`shared_preload_libraries` パラメータを変更するには、DB インスタンスをカスタムパラメータグループに関連付ける必要があります。カスタム DB パラメータグループの作成については、「[Amazon RDS のパラメータグループ](USER_WorkingWithParamGroups.md)」を参照してください。

plust 拡張機能は、AWS マネジメントコンソール または AWS CLI を使用してインストールできます。

以下のステップでは、DB インスタンスがカスタム DB パラメータグループに関連付けられていることを前提としています。

### コンソール
<a name="PL_Rust-setting-up.CON"></a>

**plust 拡張機能を `shared_preload_libraries` パラメータにインストールする**

`rds_superuser` グループ (ロール) のメンバーであるアカウントを使用して、次のステップを完了します。

1. AWS マネジメントコンソール にサインインし、Amazon RDS コンソール ([https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/)) を開きます。

1. ナビゲーションペインで、**データベース** を選択します。

1. DB インスタンスの名前を選択して、その詳細を表示します。

1. DB インスタンスの **[設定]** タブを開き、DB インスタンスパラメータグループのリンクを探します。

1. リンクを選択して、DB クラスターに関連付けられたカスタムパラメータを開きます。

1. **[パラメータ]** 検索フィールドに、`shared_pre` を入力して **`shared_preload_libraries`** パラメータを検索します。

1. プロパティ値にアクセスするには、**[Edit parameters]** (パラメータの編集) を選択します。

1. **[値]** フィールドのリストに plrust を追加します。値のリスト内の項目を区切るにはカンマを使用します。

1. DB インスタンスを再起動して、`shared_preload_libraries` パラメータの変更を有効にします。最初の再起動が完了するまでにさらに時間がかかる場合があります。

1. インスタンスが使用可能になったら、plrust が初期化されていることを確認します。`psql` を使用して DB インスタンスに接続し、次のコマンドを実行します。

   ```
   SHOW shared_preload_libraries;
   ```

   出力は以下のようになります。

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

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

**shared\$1preload\$1libraries パラメータに pltrust 拡張機能をインストールする**

`rds_superuser` グループ (ロール) のメンバーであるアカウントを使用して、次のステップを完了します。

1. `shared_preload_libraries` パラメータに plrust を追加するには、[modify-db-parameter-group](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-parameter-group.html) AWS CLI コマンドを使用します。

   ```
   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 コマンドを使用して DB インスタンスを再起動し、plrust ライブラリを初期化します。最初の再起動が完了するまでにさらに時間がかかる場合があります。

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

1. インスタンスが使用可能になったら、plrust が初期化されていることを確認できます。`psql` を使用して DB インスタンスに接続し、次のコマンドを実行します。

   ```
   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 は 2 つの追加のクレートをサポートしています。
+ `croaring-rs` 
+ `num-bigint` 

Amazon RDS for PostgreSQL バージョン 15.4、14.9、13.12 以降、PL/Rust は、次のクレートをサポートします。
+ `aes` 
+ `ctr` 
+ `rand` 

これらのクレートではデフォルト機能のみがサポートされています。新しい RDS for PostgreSQL バージョンには、更新されたバージョンのクレートが含まれているため、古いバージョンのクレートはサポートされなくなる可能性があります。

メジャーバージョンアップグレードを行う際のベストプラクティスに従って、お使いの PL/Rust 関数が新しいメジャーバージョンと互換性があるかどうかをテストしてください。詳細については、「Amazon RDS ユーザーガイド」のブログ「[Amazon RDS を PostgreSQL のメジャーバージョンとマイナーバージョンにアップグレードするためのベストプラクティス](https://aws.amazon.com/blogs/database/best-practices-for-upgrading-amazon-rds-to-major-and-minor-versions-of-postgresql/)」と「[Amazon RDS の PostgreSQL DB エンジンのアップグレード](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.PostgreSQL.html)」を参照してください。

PL/Rust 関数を作成する際の依存関係の使用例については、「[依存関係を使う](https://tcdi.github.io/plrust/use-plrust.html#use-dependencies)」を参照してください。

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

デフォルトでは、データベースユーザーは PL/Rust を使用できません。PL/Rust へのアクセスを提供するには、rds\$1superuser 権限を持つユーザーとして接続し、次のコマンドを実行します。

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