Trait ForeignDataWrapper 

pub trait ForeignDataWrapper<E: Into<ErrorReport>> {
    // Required methods
    fn new(server: ForeignServer) -> Result<Self, E>
       where Self: Sized;
    fn begin_scan(
        &mut self,
        quals: &[Qual],
        columns: &[Column],
        sorts: &[Sort],
        limit: &Option<Limit>,
        options: &HashMap<String, String>,
    ) -> Result<(), E>;
    fn iter_scan(&mut self, row: &mut Row) -> Result<Option<()>, E>;
    fn end_scan(&mut self) -> Result<(), E>;

    // Provided methods
    fn get_rel_size(
        &mut self,
        _quals: &[Qual],
        _columns: &[Column],
        _sorts: &[Sort],
        _limit: &Option<Limit>,
        _options: &HashMap<String, String>,
    ) -> Result<(i64, i32), E> { ... }
    fn re_scan(&mut self) -> Result<(), E> { ... }
    fn begin_modify(
        &mut self,
        _options: &HashMap<String, String>,
    ) -> Result<(), E> { ... }
    fn insert(&mut self, _row: &Row) -> Result<(), E> { ... }
    fn update(&mut self, _rowid: &Cell, _new_row: &Row) -> Result<(), E> { ... }
    fn delete(&mut self, _rowid: &Cell) -> Result<(), E> { ... }
    fn end_modify(&mut self) -> Result<(), E> { ... }
    fn import_foreign_schema(
        &mut self,
        _stmt: ImportForeignSchemaStmt,
    ) -> Result<Vec<String>, E> { ... }
    fn fdw_routine() -> FdwRoutine
       where Self: Sized { ... }
    fn fdw_routine_hook(_routine: &mut FdwRoutine<AllocatedByRust>) { ... }
    fn validator(
        _options: Vec<Option<String>>,
        _catalog: Option<Oid>,
    ) -> Result<(), E> { ... }
}

The Foreign Data Wrapper trait

This is the main interface for your foreign data wrapper. Required functions are listed below, all the others are optional.

1. new
2. begin_scan
3. iter_scan
4. end_scan

See the module-level document for more details.

Required Methods

fn new(server: ForeignServer) -> Result<Self, E>

where Self: Sized,

Create a FDW instance

options is the key-value pairs defined in CREATE SERVER SQL. For example,

create server my_helloworld_server
  foreign data wrapper wrappers_helloworld
  options (
    foo 'bar'
);

options passed here will be a hashmap { ‘foo’ -> ‘bar’ }.

You can do any initalization in this function, like saving connection info or API url in an variable, but don’t do heavy works like database connection or API call.

fn begin_scan( &mut self, quals: &[Qual], columns: &[Column], sorts: &[Sort], limit: &Option<Limit>, options: &HashMap<String, String>, ) -> Result<(), E>

Called when begin executing a foreign scan

• quals - WHERE clause pushed down
• columns - target columns to be queried
• sorts - ORDER BY clause pushed down
• limit - LIMIT clause pushed down
• options - the options defined when CREATE FOREIGN TABLE

See more details.

fn iter_scan(&mut self, row: &mut Row) -> Result<Option<()>, E>

Called when fetch one row from the foreign source

FDW must save fetched foreign data into the Row, or return None if no more rows to read.

See more details.

fn end_scan(&mut self) -> Result<(), E>

Called when end the scan

See more details.

Provided Methods

fn get_rel_size( &mut self, _quals: &[Qual], _columns: &[Column], _sorts: &[Sort], _limit: &Option<Limit>, _options: &HashMap<String, String>, ) -> Result<(i64, i32), E>

Obtain relation size estimates for a foreign table

Return the expected number of rows and row size (in bytes) by the foreign table scan.

See more details.

fn re_scan(&mut self) -> Result<(), E>

Called when restart the scan from the beginning.

See more details.

fn begin_modify(&mut self, _options: &HashMap<String, String>) -> Result<(), E>

Called when begin executing a foreign table modification operation.

• options - the options defined when CREATE FOREIGN TABLE

The foreign table must include a rowid_column option which specify the unique identification column of the foreign table to enable data modification.

For example,

create foreign table my_foreign_table (
  id bigint,
  name text
)
  server my_server
  options (
    rowid_column 'id'
  );

See more details.

fn insert(&mut self, _row: &Row) -> Result<(), E>

Called when insert one row into the foreign table

• row - the new row to be inserted

See more details.

fn update(&mut self, _rowid: &Cell, _new_row: &Row) -> Result<(), E>

Called when update one row into the foreign table

• rowid - the rowid_column cell
• new_row - the new row with updated cells

See more details.

fn delete(&mut self, _rowid: &Cell) -> Result<(), E>

Called when delete one row into the foreign table

• rowid - the rowid_column cell

See more details.

fn end_modify(&mut self) -> Result<(), E>

Called when end the table update

See more details.

fn import_foreign_schema( &mut self, _stmt: ImportForeignSchemaStmt, ) -> Result<Vec<String>, E>

Obtain a list of foreign table creation commands

Return a list of string, each of which must contain a CREATE FOREIGN TABLE which will be executed by the core server.

See more details.

fn fdw_routine() -> FdwRoutine

where Self: Sized,

Returns a FdwRoutine for the FDW

Not to be used directly, use wrappers_fdw macro instead.

fn fdw_routine_hook(_routine: &mut FdwRoutine<AllocatedByRust>)

Additional FwdRoutine setup, called by default Self::fdw_routine() after completing its initialization.

fn validator( _options: Vec<Option<String>>, _catalog: Option<Oid>, ) -> Result<(), E>

Validator function for validating options given in CREATE and ALTER commands for its foreign data wrapper, as well as foreign servers, user mappings, and foreign tables using the wrapper.

See more details about validator

Example

use pgrx::pg_sys::Oid;
use supabase_wrappers::prelude::check_options_contain;

use pgrx::pg_sys::panic::ErrorReport;
use pgrx::PgSqlErrorCode;

enum FdwError {
    InvalidFdwOption,
    InvalidServerOption,
    InvalidTableOption,
}

impl From<FdwError> for ErrorReport {
    fn from(value: FdwError) -> Self {
        let error_message = match value {
            FdwError::InvalidFdwOption => "invalid foreign data wrapper option",
            FdwError::InvalidServerOption => "invalid foreign server option",
            FdwError::InvalidTableOption => "invalid foreign table option",
        };
        ErrorReport::new(PgSqlErrorCode::ERRCODE_FDW_ERROR, error_message, "")
    }
}

fn validator(opt_list: Vec<Option<String>>, catalog: Option<Oid>) -> Result<(), FdwError> {
    if let Some(oid) = catalog {
        match oid {
            FOREIGN_DATA_WRAPPER_RELATION_ID => {
                // check a required option when create foreign data wrapper
                check_options_contain(&opt_list, "foreign_data_wrapper_required_option");
            }
            FOREIGN_SERVER_RELATION_ID => {
                // check option here when create server
                check_options_contain(&opt_list, "foreign_server_required_option");
            }
            FOREIGN_TABLE_RELATION_ID => {
                // check option here when create foreign table
                check_options_contain(&opt_list, "foreign_table_required_option");
            }
            _ => {}
        }
    }

    Ok(())
}

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors