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 current 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 BigQuery which only supports async data scan at this moment.
• Clickhouse: A FDW for ClickHouse which supports both async data scan and modify.
• Stripe: A FDW for Stripe API.

• 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.
• Pushdown is supported.

Wrappers is a pgx extension, so you can follow the installation steps as mentioned by pgx.

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

pub trait ForeignDataWrapper {
    // function for query planning
    fn get_rel_size(...) -> (i64, i32)

    // functions for data scan, e.g. select
    fn begin_scan(...);
    fn iter_scan(...) -> Option<Row>;
    fn re_scan(...);
    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(...);
}

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

These steps outline how to use the a demo FDW HelloWorldFdw:

1. Clone this repo

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

2. Run it using pgx with feature:

cd wrappers/wrappers
cargo pgx run --features helloworld_fdw

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

-- create extension
drop extension if exists wrappers cascade;
create extension wrappers;

-- create foreign data wrapper and enable 'HelloWorldFdw'
drop foreign data wrapper if exists helloworld_wrapper cascade;
create foreign data wrapper helloworld_wrapper
  handler wrappers_handler
  validator wrappers_validator
  options (
    wrapper 'HelloWorldFdw'
  );

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

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

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

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

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

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

Apache License Version 2.0