Wrappers

Wrappers is a development framework for Postgres Foreign Data Wrappers (FDW), written in Rust. Its goal is to make Postgres FDW development easier while keeping Rust language's modern capabilities, such as high performance, strong types, and safety.

Wrappers is also a collection of FDWs built by Supabase. We currently support the following FDWs, with more are under development:

• HelloWorld: A demo FDW to show how to develop a baisc FDW.
• BigQuery: A FDW for Google BigQuery which supports data read and modify.
• Clickhouse: A FDW for ClickHouse which supports data read and modify.
• Stripe: A FDW for Stripe API which supports data read and modify.
• Firebase: A FDW for Google Firebase which supports data read only.
• Airtable: A FDW for Airtable API which supports data read only.

Features

• Minimum interface and easy to implement.
• Support for rich data types.
• Support both sync and async backends, such as RDBMS, RESTful APIs, flat files and etc.
• Built on top of pgx, providing higher level interfaces, without hiding lower-level C APIs.
• WHERE, ORDER BY, LIMIT pushdown are supported.

Documentation

Documentation on docs.rs.

Installation

Wrappers is a pgx extension, you can follow the pgx installation steps to install Wrappers.

Basically, run below command to install FDW after pgx is installed. For example,

bash cargo pgx install --pg-config [path_to_pg_config] --features stripe_fdw

Developing a FDW

To develop a FDW using Wrappers, you only need to implement the ForeignDataWrapper trait.

```rust 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
...

} ```

In a minimum FDW, which supports data scan only, new(), begin_scan(), iter_scan() and end_scan() are required, all the other functions are optional.

To know more about FDW development, please visit the Wrappers documentation.

Basic usage

These steps outline how to use the a demo FDW HelloWorldFdw, which only outputs a single line of fake data:

1. Clone this repo

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

1. Run it using pgx with feature:

bash cd wrappers/wrappers cargo pgx run --features helloworld_fdw

1. Create the extension, foreign data wrapper and related objects:

```sql -- create extension create extension wrappers;

-- create foreign data wrapper and enable 'HelloWorldFdw' create foreign data wrapper helloworldwrapper handler helloworldfdwhandler validator helloworldfdw_validator;

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

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

1. Run a query to check if it is working:

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

Limitations

• Windows is not supported, that limitation inherits from pgx.
• Currently only supports PostgreSQL v14 and v15.

Contribution

All contributions, feature requests, bug report or ideas are welcomed.

License

Apache License Version 2.0