# 使用 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)
+ [

## 将 crate 与 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 管理控制台或 AWS CLI 安装 plrust 扩展程序。

以下步骤假设您的数据库实例与自定义数据库参数组相关联。

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

**在 `shared_preload_libraries` 参数中安装 plrust 扩展**

使用作为 `rds_superuser` 组（角色）成员的账户完成以下步骤。

1. 登录AWS 管理控制台并通过以下网址打开 Amazon RDS 控制台：[https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/)。

1. 在导航窗格中，选择 **Databases (数据库)**。

1. 选择数据库实例的名称以显示其详细信息。

1. 打开数据库实例的**配置**选项卡，并找到数据库实例参数组链接。

1. 选择此链接以打开与您的数据库实例关联的自定义参数。

1. 在**参数**搜索字段中，键入 `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;
```

## 将 crate 与 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 支持额外的 crate：
+ `url` 
+ `regex` 
+ `serde` 
+ `serde_json` 

在 RDS for PostgreSQL 版本 15.5-R2 及更高版本、14.10-R2 及更高的 14 版本、13.13-R2 及更高的 13 版本中，PL/Rust 支持另外两个 crate：
+ `croaring-rs` 
+ `num-bigint` 

从 Amazon RDS for PostgreSQL 版本 15.4、14.9 和 13.12 开始，PL/Rust 支持以下 crate：
+ `aes` 
+ `ctr` 
+ `rand` 

这些 crate 仅支持默认特征。新的 RDS for PostgreSQL 版本可能包含更新版本的 crate，并且可能不再支持旧版本的 crate。

按照执行主要版本升级的最佳实践来测试您的 PL/Rust 函数是否与新的主要版本兼容。有关更多信息，请参阅博客[将 Amazon RDS 升级到 PostgreSQL 主要和次要版本的最佳实践](https://aws.amazon.com/blogs/database/best-practices-for-upgrading-amazon-rds-to-major-and-minor-versions-of-postgresql/)，以及《Amazon RDS 用户指南》中的[为 Amazon RDS 升级 PostgreSQL 数据库引擎](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;
```