包装器

Wrappers 是Postgres Foreign Data Wrappers (FDW) 的开发框架，用Rust编写。它的目标是使Postgres FDW开发更加容易，同时保持Rust语言的现代特性，如高性能、强类型和安全性。

Wrappers 还是由Supabase构建的一组FDW。我们目前支持以下FDW，更多正在开发中

• HelloWorld：一个演示FDW，展示如何开发基本的FDW。
• BigQuery：一个支持数据读取和修改的Google BigQuery FDW。
• Clickhouse：一个支持数据读取和修改的ClickHouse FDW。
• Stripe：一个支持数据读取和修改的Stripe API FDW。
• Firebase：一个支持只读数据读取的Google Firebase FDW。
• Airtable：一个支持只读数据读取的Airtable API FDW。
• S3：一个支持只读数据读取的AWS S3 FDW。
• Logflare：一个支持只读数据读取的Logflare FDW。
• Auth0：一个Auth0 FDW。
• SQL Server：一个支持只读数据读取的Microsoft SQL Server FDW。
• Redis：一个支持只读数据读取的Redis FDW。

特性

• 最小接口，易于实现。
• 支持丰富的数据类型。
• 支持同步和异步后端，例如RDBMS、RESTful API、平面文件等。
• 基于 pgrx 构建，提供更高级别的接口，而不隐藏底层 C API。
• 支持 WHERE、ORDER BY、LIMIT 下推。

文档

在 docs.rs 上的文档.

安装

Wrappers 是 pgrx 的一个扩展，您可以通过遵循 pgrx 安装步骤 来安装 Wrappers。

基本上，在安装 pgrx 之后，运行以下命令来安装 FDW。例如，

cargo pgrx install --pg-config [path_to_pg_config] --features stripe_fdw

开发 FDW

要使用 Wrappers 开发 FDW，您只需实现 ForeignDataWrapper 特性。

pub trait ForeignDataWrapper {
    // create a FDW instance
    fn new(...) -> Self;

    // functions for data scan, e.g. select
    fn begin_scan(...);
    fn iter_scan(...) -> Option<Row>;
    fn end_scan(...);

    // functions for data modify, e.g. insert, update and delete
    fn begin_modify(...);
    fn insert(...);
    fn update(...);
    fn delete(...);
    fn end_modify(...);

    // other optional functions
    ...
}

在仅支持数据扫描的最小 FDW 中，需要 new()、begin_scan()、iter_scan() 和 end_scan()，其他所有函数都是可选的。

要了解更多关于 FDW 开发的信息，请访问 Wrappers 文档。

基本用法

以下步骤概述了如何使用一个演示 FDW HelloWorldFdw，它只输出一行假数据

1. 克隆此存储库

git clone https://github.com/supabase/wrappers.git

2. 使用具有功能的 pgrx 运行它

cd wrappers/wrappers
cargo pgrx run --features helloworld_fdw

3. 创建扩展、外部数据包装器和相关对象

-- create extension
create extension wrappers;

-- create foreign data wrapper and enable 'HelloWorldFdw'
create foreign data wrapper helloworld_wrapper
  handler hello_world_fdw_handler
  validator hello_world_fdw_validator;

-- create server and specify custom options
create server my_helloworld_server
  foreign data wrapper helloworld_wrapper
  options (
    foo 'bar'
  );

-- create an example foreign table
create foreign table hello (
  id bigint,
  col text
)
  server my_helloworld_server
  options (
    foo 'bar'
  );

4. 运行一个查询以检查其是否正常工作

wrappers=# select * from hello;
 id |    col
----+-------------
  0 | Hello world
(1 row)

限制

• Windows 不受支持，此限制继承自 pgrx。
• 目前仅支持 PostgreSQL v14、v15 和 v16。
• 不支持生成列。

贡献

欢迎所有贡献、功能请求、错误报告或想法。

许可证

Apache 许可证版本 2.0