diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index a65b4bc..06a82a4 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -2986,6 +2986,41 @@ ANALYZE measurement;
+
+ Foreign Data
+
+ foreign data
+
+
+ PostgreSQL implements parts of the SQL/MED
+ specification, which allows you to access external data that resides
+ outside PostgreSQL, using normal SQL queries.
+
+
+
+ Foreign data is accessed with help from a
+ foreign data wrapper. A foreign data wrapper is a
+ library that can communicate with an external data source, hiding the
+ details of connecting to the data source and fetching data from it. There
+ are several foreign data wrappers available for e.g reading files residing
+ on the server, or to connect to another PostgreSQL instance. If none of
+ the existing foreign data wrappers suite your needs, you can write your
+ own, see .
+
+
+
+ To access foreign data, you need to create a foreign server to define
+ the connection details to the external data source, using options required
+ by the foreign data wrapper. Then you need to create one or more
+ foreign tables that define the structure of the
+ remote data. A foreign table can be used in queries just like a normal
+ table, but a foreign table has no storage in the PostgreSQL server.
+ Whenever it is used, PostgreSQL asks the foreign data wrapper to fetch
+ the data from the external source.
+
+
+
+
Other Database Objects
diff --git a/doc/src/sgml/fdwhandler.sgml b/doc/src/sgml/fdwhandler.sgml
new file mode 100644
index 0000000..8ef93bc
--- /dev/null
+++ b/doc/src/sgml/fdwhandler.sgml
@@ -0,0 +1,125 @@
+
+
+
+ Writing A Foreign Data Wrapper
+
+
+ foreign data wrapper
+ handler for
+
+
+
+ All operations on foreign tables are handled through a foreign data
+ wrapper, which consists of a set of functions that the planner and
+ executor call. The foreign data wrapper is responsible for fetching
+ data from the remote data source and returning it to the PostgreSQL
+ executor. This chapter outlines how to write a new foreign data wrapper.
+
+
+
+ The FDW provider needs to implement a handler function, and (optionally)
+ a validator function. Both functions must be written in a compiled
+ language such as C, using the version-1 interface.
+
+ The validator function must be registered with
+ PostgreSQL as taking two arguments, a text
+ array containing the options, and an oid representing the type of object
+ the options are to be associated with. The handler function must be
+ registered as taking no arguments, and returning the type
+ fdw_handler. This special pseudotype identifies the
+ function as a fdw handler and prevents it from being called directly in
+ SQL commands. For more details on C language calling conventions and
+ dynamic loading, see .
+
+
+
+ The validator function is responsible for validating
+ options given in the CREATE FOREIGN DATA WRAPPER, CREATE SERVER and
+ CREATE FOREIGN TABLE commands.
+
+
+
+ The handler function returns a struct of function pointers to callback
+ functions that are called by the planner and executor.
+
+
+
+ The SQL standard specifies an interface for writing foreign data wrappers.
+ However, PostgreSQL does not implement that API, because the effort to
+ accommodate it into PostgreSQL would be large. The standard API hasn't
+ gained wide adoption anyway, there aren't many standard-compliant foreign
+ data wrappers out there.
+
+
+
+ The foreign data wrappers included in the standard distribution
+ are good references when trying to write your own.
+ Look into the contrib/file_fdw subdirectory of the source tree.
+ The
+ reference page also has some useful details.
+
+
+
+ Foreign Data Wrapper routines
+
+
+ The FDW handler function returns a FdwRoutine struct with the following
+ callback functions:
+
+
+
+
+FdwPlan *
+PlanRelScan (Oid foreigntableid,
+ PlannerInfo *root,
+ RelOptInfo *baserel);
+
+ Plan a scan on a foreign table. This is called when a query is planned.
+ The function must return a palloc'd struct containing cost estimates,
+ a string to show for this scan in EXPLAIN, and any FDW-private information
+ that is needed to execute the foreign scan at a later stage.
+ A prepared plan may be executed many times.
+
+
+
+
+FdwExecutionState *
+BeginScan (FdwPlan *plan
+ ParamListInfo *params);
+
+ Begin exeucuting a foreign scan. This is called when a query is executed.
+ The function must return a palloc'd struct containing any private
+ information needed by the Iterate and EndScan calls that follow.
+
+
+
+
+void
+Iterate (FdwExecutionState *state,
+ TupleTableSlot *slot);
+
+ Fetch one row from the foreign source. Note that this is called in a
+ short-lived memory context that may be reset between every invocation of
+ Iterate. Create a memory context in BeginScan if you need longer-lived
+ storage.
+
+
+
+
+void
+ReScan (FdwExecutionState *state);
+
+ Restarts the scan.
+
+
+
+
+void
+EndScan (FdwExecutionState *state);
+
+ Ends the scan.
+
+
+
+
+
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 99437ac..c2f4169 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -82,10 +82,11 @@
-
+
+
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 4d32f7d..98d19a5 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -238,6 +238,7 @@
&sources;
&nls;
&plhandler;
+ &fdwhandler;
&geqo;
&indexam;
&gist;
diff --git a/src/backend/commands/foreigncmds.c b/src/backend/commands/foreigncmds.c
index 360016c..6acdc9c 100644
--- a/src/backend/commands/foreigncmds.c
+++ b/src/backend/commands/foreigncmds.c
@@ -330,6 +330,9 @@ lookup_fdw_validator_func(DefElem *validator)
/* return value is ignored, so we don't check the type */
}
+/*
+ * Convert a handler function name passed from the parser to an Oid
+ */
static Oid
lookup_fdw_handler_func(DefElem *handler)
{
@@ -365,19 +368,21 @@ parse_func_options(List *func_options, DefElem **validator, DefElem **handler)
if (pg_strcasecmp(def->defname, "validator") == 0)
{
if (*validator)
- elog(ERROR, "duplicated VALIDATOR");
+ ereport(ERROR,
+ (errcode(ERRCODE_SYNTAX_ERROR),
+ errmsg("conflicting or redundant options")));
*validator = def;
}
else if (pg_strcasecmp(def->defname, "handler") == 0)
{
if (*handler)
- elog(ERROR, "duplicated HANDLER");
+ ereport(ERROR,
+ (errcode(ERRCODE_SYNTAX_ERROR),
+ errmsg("conflicting or redundant options")));
*handler = def;
}
else
- {
- elog(ERROR, "invalid option");
- }
+ elog(ERROR, "option \"%s\" not recognized", def->defname);
}
}
diff --git a/src/backend/executor/execAmi.c b/src/backend/executor/execAmi.c
index b27de28..9f7b138 100644
--- a/src/backend/executor/execAmi.c
+++ b/src/backend/executor/execAmi.c
@@ -21,8 +21,8 @@
#include "executor/nodeBitmapIndexscan.h"
#include "executor/nodeBitmapOr.h"
#include "executor/nodeCtescan.h"
-#include "executor/nodeFunctionscan.h"
#include "executor/nodeForeignscan.h"
+#include "executor/nodeFunctionscan.h"
#include "executor/nodeGroup.h"
#include "executor/nodeGroup.h"
#include "executor/nodeHash.h"
diff --git a/src/backend/executor/execProcnode.c b/src/backend/executor/execProcnode.c
index 92b83ac..f275b41 100644
--- a/src/backend/executor/execProcnode.c
+++ b/src/backend/executor/execProcnode.c
@@ -85,8 +85,8 @@
#include "executor/nodeBitmapIndexscan.h"
#include "executor/nodeBitmapOr.h"
#include "executor/nodeCtescan.h"
-#include "executor/nodeFunctionscan.h"
#include "executor/nodeForeignscan.h"
+#include "executor/nodeFunctionscan.h"
#include "executor/nodeGroup.h"
#include "executor/nodeHash.h"
#include "executor/nodeHashjoin.h"
diff --git a/src/backend/executor/nodeForeignscan.c b/src/backend/executor/nodeForeignscan.c
index e6354c7..3183f43 100644
--- a/src/backend/executor/nodeForeignscan.c
+++ b/src/backend/executor/nodeForeignscan.c
@@ -1,7 +1,7 @@
/*-------------------------------------------------------------------------
*
* nodeForeignscan.c
- * Support routines for sequential scans of foreign tables.
+ * Support routines for scans of foreign tables.
*
* Portions Copyright (c) 1996-2011, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
@@ -14,9 +14,9 @@
*/
/*
* INTERFACE ROUTINES
- * ExecForeignScan sequentially scans a foreign table.
- * ExecForeignNext retrieve next tuple in sequential order.
- * ExecInitForeignScan creates and initializes a seqscan node.
+ * ExecForeignScan scans a foreign table.
+ * ExecForeignNext retrieve next tuple.
+ * ExecInitForeignScan creates and initializes a foreign scan node.
* ExecEndForeignScan releases any storage allocated.
* ExecForeignReScan rescans the foreign table
* ExecForeignMarkPos marks scan position
@@ -76,6 +76,8 @@ ForeignNext(ForeignScanState *node)
ExecMaterializeSlot(slot);
/* overwrite only tableoid of the tuple */
+ /* XXX: Isn't this a bit dirty? We're scribbling over the field in
+ * the heap tuple that might've been allocated by the FDW. */
slot->tts_tuple->t_tableOid =
RelationGetRelid(node->ss.ss_currentRelation);
}
@@ -180,8 +182,8 @@ ExecInitForeignScan(ForeignScan *node, EState *estate, int eflags)
scanstate->routine = routine;
/*
- * If this execution was not for EXPLAIN w/o ANALYZE flag, initiate the
- * foreign scan.
+ * Tell the FDW to initiate the foreign scan, unless we're just doing
+ * EXPLAIN (ie, aren't going to run the plan).
*/
if (!(eflags & EXEC_FLAG_EXPLAIN_ONLY))
{
diff --git a/src/backend/foreign/foreign.c b/src/backend/foreign/foreign.c
index 1fdd925..3da8541 100644
--- a/src/backend/foreign/foreign.c
+++ b/src/backend/foreign/foreign.c
@@ -263,10 +263,7 @@ GetForeignTable(Oid relid)
Datum datum;
bool isnull;
- tp = SearchSysCache(FOREIGNTABLEREL,
- ObjectIdGetDatum(relid),
- 0, 0, 0);
-
+ tp = SearchSysCache1(FOREIGNTABLEREL, ObjectIdGetDatum(relid));
if (!HeapTupleIsValid(tp))
elog(ERROR, "cache lookup failed for foreign table %u", relid);
@@ -297,10 +294,10 @@ GetForeignTable(Oid relid)
FdwRoutine *
GetFdwRoutine(Oid fdwhandler)
{
- FmgrInfo flinfo;
- FunctionCallInfoData fcinfo;
- Datum result;
- FdwRoutine *routine;
+ FmgrInfo flinfo;
+ FunctionCallInfoData fcinfo;
+ Datum result;
+ FdwRoutine *routine;
if (fdwhandler == InvalidOid)
elog(ERROR, "foreign-data wrapper has no handler");
diff --git a/src/backend/nodes/copyfuncs.c b/src/backend/nodes/copyfuncs.c
index 79c71c4..61c8599 100644
--- a/src/backend/nodes/copyfuncs.c
+++ b/src/backend/nodes/copyfuncs.c
@@ -572,9 +572,6 @@ _copyFdwPlan(FdwPlan *from)
{
FdwPlan *newnode = makeNode(FdwPlan);
- /*
- * copy node superclass fields
- */
COPY_STRING_FIELD(explainInfo);
COPY_SCALAR_FIELD(startup_cost);
COPY_SCALAR_FIELD(total_cost);
diff --git a/src/backend/nodes/outfuncs.c b/src/backend/nodes/outfuncs.c
index dee46ba..4602ced 100644
--- a/src/backend/nodes/outfuncs.c
+++ b/src/backend/nodes/outfuncs.c
@@ -546,8 +546,8 @@ _outFdwPlan(StringInfo str, FdwPlan *node)
WRITE_NODE_TYPE("FDWPLAN");
WRITE_STRING_FIELD(explainInfo);
- WRITE_FLOAT_FIELD(startup_cost, "%.2f");
- WRITE_FLOAT_FIELD(total_cost, "%.2f");
+ WRITE_FLOAT_FIELD(startup_cost, "%.2f");
+ WRITE_FLOAT_FIELD(total_cost, "%.2f");
WRITE_NODE_FIELD(private);
}
diff --git a/src/backend/optimizer/path/allpaths.c b/src/backend/optimizer/path/allpaths.c
index ae2e134..c196ab6 100644
--- a/src/backend/optimizer/path/allpaths.c
+++ b/src/backend/optimizer/path/allpaths.c
@@ -258,7 +258,7 @@ set_plain_rel_pathlist(PlannerInfo *root, RelOptInfo *rel, RangeTblEntry *rte)
if (IsForeignTable(rte->relid))
{
- /* only foreign scan path is applyable to foreign table */
+ /* only foreign scan path is applicable to a foreign table */
add_path(rel, create_foreignscan_path(root, rel));
}
else
diff --git a/src/backend/optimizer/plan/createplan.c b/src/backend/optimizer/plan/createplan.c
index 938b8af..53ae495 100644
--- a/src/backend/optimizer/plan/createplan.c
+++ b/src/backend/optimizer/plan/createplan.c
@@ -352,9 +352,9 @@ create_scan_plan(PlannerInfo *root, Path *best_path)
case T_ForeignScan:
plan = (Plan *) create_foreignscan_plan(root,
- best_path,
- tlist,
- scan_clauses);
+ best_path,
+ tlist,
+ scan_clauses);
break;
default:
diff --git a/src/backend/optimizer/prep/prepunion.c b/src/backend/optimizer/prep/prepunion.c
index 61f6d5f..2605efb 100644
--- a/src/backend/optimizer/prep/prepunion.c
+++ b/src/backend/optimizer/prep/prepunion.c
@@ -1238,13 +1238,14 @@ expand_inherited_rtentry(PlannerInfo *root, RangeTblEntry *rte, Index rti)
}
/*
- * SELECT FOR UPDATE/SHARE is not allowd to foreign tables because
+ * SELECT FOR UPDATE/SHARE is not allowed on foreign tables because
* they are read-only.
*/
if (newrelation->rd_rel->relkind == RELKIND_FOREIGN_TABLE &&
lockmode != AccessShareLock)
- ereport(ERROR, (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
- errmsg("SELECT FOR UPDATE/SHARE is not allowed with foreign tables")));
+ ereport(ERROR,
+ (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
+ errmsg("SELECT FOR UPDATE/SHARE is not allowed with foreign tables")));
/*
* Build an RTE for the child, and attach to query's rangetable list.
diff --git a/src/backend/optimizer/util/pathnode.c b/src/backend/optimizer/util/pathnode.c
index 134ec7e..d53f7aa 100644
--- a/src/backend/optimizer/util/pathnode.c
+++ b/src/backend/optimizer/util/pathnode.c
@@ -1435,7 +1435,7 @@ create_foreignscan_path(PlannerInfo *root, RelOptInfo *rel)
pathnode->path.pathtype = T_ForeignScan;
pathnode->path.parent = rel;
pathnode->path.pathkeys = NIL; /* result is always unordered */
-
+
rte = planner_rt_fetch(rel->relid, root);
routine = GetFdwRoutineByRelId(rte->relid);
if (routine->PlanRelScan == NULL)
diff --git a/src/backend/optimizer/util/plancat.c b/src/backend/optimizer/util/plancat.c
index 1d60af8..8d477a6 100644
--- a/src/backend/optimizer/util/plancat.c
+++ b/src/backend/optimizer/util/plancat.c
@@ -455,7 +455,7 @@ estimate_rel_size(Relation rel, int32 *attr_widths,
*tuples = 1;
break;
case RELKIND_FOREIGN_TABLE:
- /* foreign tables has no storage, trust statistics */
+ /* foreign tables have no storage, trust statistics */
*pages = rel->rd_rel->relpages;
*tuples = rel->rd_rel->reltuples;
break;
diff --git a/src/bin/pg_dump/pg_dump.c b/src/bin/pg_dump/pg_dump.c
index 2a381a0..23cc95a 100644
--- a/src/bin/pg_dump/pg_dump.c
+++ b/src/bin/pg_dump/pg_dump.c
@@ -5986,14 +5986,30 @@ getForeignDataWrappers(int *numForeignDataWrappers)
/* Make sure we are in proper schema */
selectSourceSchema("pg_catalog");
- appendPQExpBuffer(query, "SELECT tableoid, oid, fdwname, "
- "(%s fdwowner) AS rolname, fdwvalidator::pg_catalog.regproc, "
- "fdwhandler::pg_catalog.regproc, fdwacl,"
- "array_to_string(ARRAY("
- " SELECT option_name || ' ' || quote_literal(option_value) "
- " FROM pg_options_to_table(fdwoptions)), ', ') AS fdwoptions "
- "FROM pg_foreign_data_wrapper",
- username_subquery);
+ if (g_fout->remoteVersion >= 90100)
+ {
+ appendPQExpBuffer(query, "SELECT tableoid, oid, fdwname, "
+ "(%s fdwowner) AS rolname, "
+ "fdwvalidator::pg_catalog.regproc, "
+ "fdwhandler::pg_catalog.regproc, fdwacl,"
+ "array_to_string(ARRAY("
+ " SELECT option_name || ' ' || quote_literal(option_value) "
+ " FROM pg_options_to_table(fdwoptions)), ', ') AS fdwoptions "
+ "FROM pg_foreign_data_wrapper",
+ username_subquery);
+ }
+ else
+ {
+ appendPQExpBuffer(query, "SELECT tableoid, oid, fdwname, "
+ "(%s fdwowner) AS rolname, "
+ "fdwvalidator::pg_catalog.regproc, "
+ "0::oid AS fdwhandler, fdwacl,"
+ "array_to_string(ARRAY("
+ " SELECT option_name || ' ' || quote_literal(option_value) "
+ " FROM pg_options_to_table(fdwoptions)), ', ') AS fdwoptions "
+ "FROM pg_foreign_data_wrapper",
+ username_subquery);
+ }
res = PQexec(g_conn, query->data);
check_sql_result(res, g_conn, query->data, PGRES_TUPLES_OK);
@@ -6026,7 +6042,6 @@ getForeignDataWrappers(int *numForeignDataWrappers)
fdwinfo[i].fdwoptions = strdup(PQgetvalue(res, i, i_fdwoptions));
fdwinfo[i].fdwacl = strdup(PQgetvalue(res, i, i_fdwacl));
-
/* Decide whether we want to dump it */
selectDumpableObject(&(fdwinfo[i].dobj));
}
diff --git a/src/include/foreign/fdwapi.h b/src/include/foreign/fdwapi.h
index 7be1999..9afdbe7 100644
--- a/src/include/foreign/fdwapi.h
+++ b/src/include/foreign/fdwapi.h
@@ -21,7 +21,7 @@
* context with copyObject. It means that FdwPlan, a part of ForeignScan plan
* node, and its contents must have copyObject support too.
*/
-struct FdwPlan
+typedef struct
{
NodeTag type;
@@ -46,20 +46,18 @@ struct FdwPlan
#endif
/*
- * FDW-private data. FDW must guarantee that every elements in this list
- * have copyObject support. If FDW needs to store arbitrary data such as
- * non-Node structure, Const of bytea would be able to use as a container.
+ * FDW-private data. Anything stored here needs to have copyObject
+ * support. If FDW needs to store arbitrary data such as a non-Node
+ * structure, Const of bytea can be used as a container.
*/
- List *private;
-};
-typedef struct FdwPlan FdwPlan;
+ Node *private;
+} FdwPlan;
-struct FdwExecutionState
+typedef struct
{
- /* FDW-private data */
+ /* FDW-private data. This doesn't need to have copyObject support. */
void *private;
-};
-typedef struct FdwExecutionState FdwExecutionState;
+} FdwExecutionState;
/*
* Common interface routines of FDW, inspired by the FDW API in the SQL/MED
@@ -72,7 +70,7 @@ typedef struct FdwExecutionState FdwExecutionState;
* with BeginScan. The implementation should fill in the cost estimates in
* FdwPlan, and may store private information.
*/
-struct FdwRoutine
+typedef struct
{
/*
* Plan a scan on a foreign table. 'foreigntableid' identifies the foreign
@@ -144,7 +142,6 @@ struct FdwRoutine
*/
FdwPlan *(*PlanQuery)(PlannerInfo *root, Query query);
#endif
-};
-typedef struct FdwRoutine FdwRoutine;
+} FdwRoutine;
#endif /* FDWAPI_H */
diff --git a/src/include/nodes/execnodes.h b/src/include/nodes/execnodes.h
index 7d1c681..561d512 100644
--- a/src/include/nodes/execnodes.h
+++ b/src/include/nodes/execnodes.h
@@ -1415,7 +1415,7 @@ typedef struct ForeignScanState
{
ScanState ss; /* its first field is NodeTag */
FdwRoutine *routine;
- FdwExecutionState *fstate; /* private data for each data wrapper */
+ FdwExecutionState *fstate; /* private state of the wrapper */
} ForeignScanState;
/* ----------------------------------------------------------------