Foreign Data

FOREIGN DATA WRAPPER, SERVER, USER MAPPING, and FOREIGN TABLE declarations.

FOREIGN DATA WRAPPER

In the common case, FDWs are installed via extension (EXTENSION postgres_fdw;). The explicit declaration is reserved for custom C-implemented FDWs. Place in the cluster objects directory.

FOREIGN DATA WRAPPER myfdw
    HANDLER   myfdw_handler
    VALIDATOR myfdw_validator;
-- emits
CREATE FOREIGN DATA WRAPPER myfdw
    HANDLER   myfdw_handler
    VALIDATOR myfdw_validator;

SERVER

Servers are database-level objects that reference a foreign data wrapper.

SERVER analytics_warehouse
    FOREIGN DATA WRAPPER postgres_fdw
    OPTIONS (host 'warehouse.internal', dbname 'analytics', port '5432');
-- emits
CREATE SERVER "analytics_warehouse"
    FOREIGN DATA WRAPPER postgres_fdw
    OPTIONS (host 'warehouse.internal', dbname 'analytics', port '5432');

USER MAPPING

USER MAPPING FOR app_service
    SERVER analytics_warehouse
    OPTIONS (user 'fdw_user', password '{{vault:secret/fdw/analytics#password}}');
-- emits
CREATE USER MAPPING FOR "app_service"
    SERVER "analytics_warehouse"
    OPTIONS (user 'fdw_user', password '<resolved-at-apply-time>');

FOREIGN TABLE

SERVER and OPTIONS are PG SQL clauses on the CREATE FOREIGN TABLE signature — they stay in Part 1 per the two-part syntax rules.

FOREIGN TABLE remote_events (
    id         BIGINT,
    payload    JSONB,
    created_at TIMESTAMPTZ
) SERVER log_server OPTIONS (table_name 'events', schema_name 'public')
{
    COLUMN id { COMMENT 'Remote event primary key'; }
    GRANTS { SELECT TO app_readonly; }
}
-- emits
CREATE FOREIGN TABLE "public"."remote_events" (
    "id"         bigint,
    "payload"    jsonb,
    "created_at" timestamptz
) SERVER "log_server" OPTIONS (table_name 'events', schema_name 'public');

COMMENT ON COLUMN "public"."remote_events"."id" IS 'Remote event primary key';
GRANT SELECT ON "public"."remote_events" TO "app_readonly";

Diffing behaviour

ObjectChangeSafety
FDWHANDLER/VALIDATOR/OPTIONS changedDESTRUCTIVE (drop + recreate)
FDWOwner changedSAFE
FDWRenamedCAUTION
FDWGrants/revocations changedSAFE
FDWRemovedDESTRUCTIVE
ServerOPTIONS changedSAFE
ServerVERSION changed onlySAFE
ServerOwner changedSAFE
ServerRenamedCAUTION
ServerFDW changedDESTRUCTIVE (drop + recreate)
ServerRemovedDESTRUCTIVE
User mappingOPTIONS changedDESTRUCTIVE then SAFE (drop + recreate)
User mappingRemovedDESTRUCTIVE
Foreign tableColumn changesALTER FOREIGN TABLE