SQL: SELECT * FROM remote_orders WHERE customer_id = 42

PLANNING PHASE
==============

1. GetForeignRelSize(root, baserel, foreigntableid)
   |
   |  Purpose: Estimate the size of the foreign table scan.
   |  The FDW sets baserel->rows, baserel->reltarget->width,
   |  and stores private state in baserel->fdw_private.
   |
   |  postgres_fdw: Opens a connection, runs EXPLAIN on the remote
   |  server to get row estimates.
   |
   v

2. GetForeignPaths(root, baserel, foreigntableid)
   |
   |  Purpose: Create one or more ForeignPath nodes representing
   |  different ways to scan the foreign table.
   |
   |  The FDW calls add_path() for each alternative. A typical
   |  FDW creates one path for a full remote scan and possibly
   |  a parameterized path for nested-loop joins.
   |
   v

3. GetForeignPlan(root, baserel, foreigntableid, best_path, tlist, scan_clauses, outer_plan)
   |
   |  Purpose: Convert the chosen ForeignPath into a ForeignScan
   |  plan node. The FDW decides which WHERE clauses to push down
   |  to the remote side and which to evaluate locally.
   |
   |  Returns: ForeignScan node with fdw_private data encoding
   |  the remote query to execute.
   |
   v

EXECUTION PHASE
===============

4. BeginForeignScan(node, eflags)
   |
   |  Purpose: Initialize execution state. Open remote connections,
   |  prepare remote queries, allocate buffers.
   |
   |  The FDW stores its state in node->fdw_state.
   |
   v

5. IterateForeignScan(node)  [called repeatedly]
   |
   |  Purpose: Fetch the next tuple from the foreign source.
   |  Returns a TupleTableSlot with data, or an empty slot
   |  when the scan is complete.
   |
   |  postgres_fdw: Fetches batches of rows from the remote cursor,
   |  returns them one at a time.
   |
   v

6. ReScanForeignScan(node)
   |
   |  Purpose: Restart the scan, possibly with new parameters
   |  (for parameterized nested-loop joins).
   |
   v

7. EndForeignScan(node)
   |
   |  Purpose: Release resources. Close remote connections/cursors,
   |  free buffers.
   |
   v
   Done.

INSERT INTO remote_orders VALUES (1, 42, 99.99)

Planning:
  AddForeignUpdateTargets(root, rtindex, rte, relation)
    --> Add junk columns needed to identify rows (e.g., ctid)
  PlanForeignModify(root, plan, resultRelation, subplan_index)
    --> Return fdw_private list with remote DML plan

Execution:
  BeginForeignModify(mtstate, rinfo, fdw_private, subplan_index, eflags)
    --> Prepare remote INSERT/UPDATE/DELETE statement
  ExecForeignInsert(estate, rinfo, slot, planSlot)
    --> Execute remote INSERT, return result slot
  EndForeignModify(estate, rinfo)
    --> Close remote statement

IsForeignScanParallelSafe(root, rel, rte)
  --> Return true if this scan can run in parallel workers

EstimateDSMForeignScan(node, pcxt)
  --> Return shared memory needed for parallel coordination

InitializeDSMForeignScan(node, pcxt, coordinate)
  --> Set up shared state in DSM segment (leader process)

InitializeWorkerForeignScan(node, toc, coordinate)
  --> Attach to shared state (worker processes)

ReInitializeDSMForeignScan(node, pcxt, coordinate)
  --> Reset for rescan in parallel context

ShutdownForeignScan(node)
  --> Cleanup before DSM is destroyed

IsForeignPathAsyncCapable(path)
  --> Return true if this path supports async execution

ForeignAsyncRequest(areq)
  --> Initiate an asynchronous data fetch

ForeignAsyncConfigureWait(areq)
  --> Register wait events (socket fd) with the wait event set

ForeignAsyncNotify(areq)
  --> Process completed async request, provide result tuple

FdwRoutine
 +-- type: NodeTag (T_FdwRoutine)
 |
 +-- REQUIRED: Scan Planning & Execution
 |    +-- GetForeignRelSize
 |    +-- GetForeignPaths
 |    +-- GetForeignPlan
 |    +-- BeginForeignScan
 |    +-- IterateForeignScan
 |    +-- ReScanForeignScan
 |    +-- EndForeignScan
 |
 +-- OPTIONAL: Join & Upper Pushdown
 |    +-- GetForeignJoinPaths
 |    +-- GetForeignUpperPaths
 |
 +-- OPTIONAL: DML
 |    +-- AddForeignUpdateTargets
 |    +-- PlanForeignModify
 |    +-- BeginForeignModify
 |    +-- ExecForeignInsert / ExecForeignBatchInsert
 |    +-- GetForeignModifyBatchSize
 |    +-- ExecForeignUpdate
 |    +-- ExecForeignDelete
 |    +-- EndForeignModify
 |    +-- BeginForeignInsert / EndForeignInsert
 |    +-- IsForeignRelUpdatable
 |
 +-- OPTIONAL: Direct Modify (UPDATE/DELETE pushdown)
 |    +-- PlanDirectModify
 |    +-- BeginDirectModify
 |    +-- IterateDirectModify
 |    +-- EndDirectModify
 |
 +-- OPTIONAL: Row Locking
 |    +-- GetForeignRowMarkType
 |    +-- RefetchForeignRow
 |    +-- RecheckForeignScan
 |
 +-- OPTIONAL: EXPLAIN
 |    +-- ExplainForeignScan
 |    +-- ExplainForeignModify
 |    +-- ExplainDirectModify
 |
 +-- OPTIONAL: ANALYZE
 |    +-- AnalyzeForeignTable
 |
 +-- OPTIONAL: IMPORT FOREIGN SCHEMA
 |    +-- ImportForeignSchema
 |
 +-- OPTIONAL: TRUNCATE
 |    +-- ExecForeignTruncate
 |
 +-- OPTIONAL: Parallel Execution
 |    +-- IsForeignScanParallelSafe
 |    +-- EstimateDSMForeignScan
 |    +-- InitializeDSMForeignScan
 |    +-- ReInitializeDSMForeignScan
 |    +-- InitializeWorkerForeignScan
 |    +-- ShutdownForeignScan
 |
 +-- OPTIONAL: Path Reparameterization
 |    +-- ReparameterizeForeignPathByChild
 |
 +-- OPTIONAL: Async Execution
      +-- IsForeignPathAsyncCapable
      +-- ForeignAsyncRequest
      +-- ForeignAsyncConfigureWait
      +-- ForeignAsyncNotify

ForeignScanState
 +-- ss (ScanState)       : base scan state with result slot, projection, quals
 +-- fdw_state (void*)    : FDW-private execution state
 +-- fdw_recheck_quals    : quals needing recheck for RecheckForeignScan
 +-- pscan_len            : parallel scan descriptor size
 +-- resultRelInfo        : for DML operations

SQL Object                  Catalog Table          C Struct
-----------                 -------------          --------
FOREIGN DATA WRAPPER        pg_foreign_data_wrapper ForeignDataWrapper
SERVER                      pg_foreign_server       ForeignServer
USER MAPPING                pg_user_mapping         UserMapping
FOREIGN TABLE               pg_foreign_table        ForeignTable
                            (+ pg_class for columns)

GetForeignPlan receives scan_clauses (all applicable WHERE clauses)
  |
  For each clause:
  |
  +-- Can remote evaluate this expression?
  |    +-- Only built-in operators?
  |    +-- No local functions?
  |    +-- No volatile expressions?
  |    +-- Collation compatible?
  |
  +-- YES: Add to remote_conds (pushed down)
  |         --> Deparse into remote SQL WHERE clause
  |         --> Remove from local execution
  |
  +-- NO:  Add to local_conds (evaluated locally)
            --> Keep in scan_clauses for local filtering
            --> extract_actual_clauses() to get executable form