Home Explore Blog CI



postgresql

22th chunk of `doc/src/sgml/fdwhandler.sgml`
6a3933f5ded4b5e91eaa98c3b896ddacd63c688bc81415f50000000100000fa5
 remote
     schema should be imported (in this case <structfield>table_list</structfield> is
     empty), <literal>FDW_IMPORT_SCHEMA_LIMIT_TO</literal> means to include only
     tables listed in <structfield>table_list</structfield>,
     and <literal>FDW_IMPORT_SCHEMA_EXCEPT</literal> means to exclude the tables
     listed in <structfield>table_list</structfield>.
     <structfield>options</structfield> is a list of options used for the import process.
     The meanings of the options are up to the FDW.
     For example, an FDW could use an option to define whether the
     <literal>NOT NULL</literal> attributes of columns should be imported.
     These options need not have anything to do with those supported by the
     FDW as database object options.
    </para>

    <para>
     The FDW may ignore the <structfield>local_schema</structfield> field of
     the <structname>ImportForeignSchemaStmt</structname>, because the core server
     will automatically insert that name into the parsed <command>CREATE
     FOREIGN TABLE</command> commands.
    </para>

    <para>
     The FDW does not have to concern itself with implementing the filtering
     specified by <structfield>list_type</structfield> and <structfield>table_list</structfield>,
     either, as the core server will automatically skip any returned commands
     for tables excluded according to those options.  However, it's often
     useful to avoid the work of creating commands for excluded tables in the
     first place.  The function <function>IsImportableForeignTable()</function> may be
     useful to test whether a given foreign-table name will pass the filter.
    </para>

    <para>
     If the FDW does not support importing table definitions, the
     <function>ImportForeignSchema</function> pointer can be set to <literal>NULL</literal>.
    </para>

   </sect2>

   <sect2 id="fdw-callbacks-parallel">
    <title>FDW Routines for Parallel Execution</title>
    <para>
     A <structname>ForeignScan</structname> node can, optionally, support parallel
     execution.  A parallel <structname>ForeignScan</structname> will be executed
     in multiple processes and must return each row exactly once across
     all cooperating processes.  To do this, processes can coordinate through
     fixed-size chunks of dynamic shared memory.  This shared memory is not
     guaranteed to be mapped at the same address in every process, so it
     must not contain pointers.  The following functions are all optional,
     but most are required if parallel execution is to be supported.
    </para>

    <para>
<programlisting>
bool
IsForeignScanParallelSafe(PlannerInfo *root, RelOptInfo *rel,
                          RangeTblEntry *rte);
</programlisting>
    Test whether a scan can be performed within a parallel worker.  This
    function will only be called when the planner believes that a parallel
    plan might be possible, and should return true if it is safe for that scan
    to run within a parallel worker.  This will generally not be the case if
    the remote data source has transaction semantics, unless the worker's
    connection to the data can somehow be made to share the same transaction
    context as the leader.
    </para>

    <para>
    If this function is not defined, it is assumed that the scan must take
    place within the parallel leader.  Note that returning true does not mean
    that the scan itself can be done in parallel, only that the scan can be
    performed within a parallel worker.  Therefore, it can be useful to define
    this method even when parallel execution is not supported.
    </para>

    <para>
<programlisting>
Size
EstimateDSMForeignScan(ForeignScanState *node, ParallelContext *pcxt);
</programlisting>
    Estimate the amount of dynamic shared memory that will be required
    for parallel operation.  This may be higher than the amount that will
    actually be used, but it must not be lower.  The return value is in bytes.
    This function

Title: FDW Routines for IMPORT FOREIGN SCHEMA (Continued) and Parallel Execution
Summary
The FDW may ignore the `local_schema` field of the `ImportForeignSchemaStmt`, as the core server automatically inserts the name into the parsed `CREATE FOREIGN TABLE` commands. The FDW doesn't have to implement filtering; the server skips commands for excluded tables. `IsImportableForeignTable()` can test if a table name passes the filter. The `ImportForeignSchema` pointer can be NULL if the FDW doesn't support importing table definitions. ForeignScan nodes can support parallel execution with coordination through shared memory. The following functions are optional but mostly required if parallel execution is to be supported. `IsForeignScanParallelSafe` tests if a scan can be performed within a parallel worker, returning true if safe; otherwise, it's assumed the scan takes place in the parallel leader. `EstimateDSMForeignScan` estimates the dynamic shared memory required for parallel operation, in bytes.