--- /dev/null
+/*-------------------------------------------------------------------------
+ *
+ * postgresql_fdw.c
+ * foreign-data wrapper for PostgreSQL
+ *
+ * Portions Copyright (c) 1996-2011, PostgreSQL Global Development Group
+ *
+ * IDENTIFICATION
+ * contrib/postgresql_fdw/postgresql_fdw.c
+ *
+ *-------------------------------------------------------------------------
+ */
+#include "postgres.h"
+
+#include "catalog/pg_namespace.h"
+#include "catalog/pg_operator.h"
+#include "catalog/pg_proc.h"
+#include "foreign/fdwapi.h"
+#include "foreign/foreign.h"
+#include "funcapi.h"
+#include "libpq-fe.h"
+#include "mb/pg_wchar.h"
+#include "miscadmin.h"
+#include "nodes/makefuncs.h"
+#include "nodes/nodeFuncs.h"
+#include "nodes/relation.h"
+#include "optimizer/clauses.h"
+#include "optimizer/cost.h"
+#include "parser/parsetree.h"
+#include "parser/scansup.h"
+#include "utils/builtins.h"
+#include "utils/lsyscache.h"
+#include "utils/memutils.h"
+#include "utils/resowner.h"
+#include "utils/syscache.h"
+
+#include "postgresql_fdw.h"
+
+PG_MODULE_MAGIC;
+
+extern Datum postgresql_fdw_handler(PG_FUNCTION_ARGS);
+
+/*
+ * FDW routines
+ */
+static FdwPlan *pgPlanForeignScan(Oid foreigntableid, PlannerInfo *root,
+ RelOptInfo *baserel);
+static void pgExplainForeignScan(ForeignScanState *node,
+ struct ExplainState *es);
+static void pgBeginForeignScan(ForeignScanState *node, int eflags);
+static TupleTableSlot *pgIterateForeignScan(ForeignScanState *node);
+static void pgReScanForeignScan(ForeignScanState *node);
+static void pgEndForeignScan(ForeignScanState *node);
+
+/* helper for deparsing a request into SQL statement */
+
+static bool is_foreign_qual(PlannerInfo *root, RelOptInfo *baserel, Expr *expr);
+static bool foreign_qual_walker(Node *node, void *context);
+static void deparseSelectClause(StringInfo sql, ForeignTable *table, TupleDesc tupdesc, const char *aliasname, bool prefix);
+static char *deparseSql(Oid foreigntableid, PlannerInfo *root, RelOptInfo *baserel);
+
+static void storeResult(TupleTableSlot *slot, PGresult *res, int rowno);
+
+/*
+ * Connection management
+ */
+static PGconn *GetConnection(ForeignServer *server, UserMapping *user);
+static void ReleaseConnection(PGconn *conn);
+static void check_conn_params(const char **keywords, const char **values);
+static PGconn *connect_pg_server(ForeignServer *server, UserMapping *user);
+static void cleanup_connection(ResourceReleasePhase phase,
+ bool isCommit,
+ bool isTopLevel,
+ void *arg);
+
+/*
+ * PostgreSQL specific portion of a foreign query request
+ */
+typedef struct PgsqlFdwExecutionState
+{
+ PGconn *conn;
+ PGresult *res;
+ int nextrow;
+} PgsqlFdwExecutionState;
+
+
+/*
+ * return foreign-data wrapper handler object to execute foreign-data wrapper
+ * routines.
+ */
+PG_FUNCTION_INFO_V1(postgresql_fdw_handler);
+Datum
+postgresql_fdw_handler(PG_FUNCTION_ARGS)
+{
+ FdwRoutine *fdwroutine = makeNode(FdwRoutine);
+
+ fdwroutine->PlanForeignScan = pgPlanForeignScan;
+ fdwroutine->ExplainForeignScan = pgExplainForeignScan;
+ fdwroutine->BeginForeignScan = pgBeginForeignScan;
+ fdwroutine->IterateForeignScan = pgIterateForeignScan;
+ fdwroutine->ReScanForeignScan = pgReScanForeignScan;
+ fdwroutine->EndForeignScan = pgEndForeignScan;
+
+ PG_RETURN_POINTER(fdwroutine);
+}
+
+static FdwPlan *
+pgPlanForeignScan(Oid foreigntableid, PlannerInfo *root, RelOptInfo *baserel)
+{
+ FdwPlan *fdwplan;
+ char *sql;
+
+ fdwplan = makeNode(FdwPlan);
+
+ sql = deparseSql(foreigntableid, root, baserel);
+
+ fdwplan->fdw_private = lappend(NIL, makeString(sql));
+
+ return fdwplan;
+}
+
+/*
+ * pgExplainForeignScan
+ * Produce extra output for EXPLAIN
+ */
+static void
+pgExplainForeignScan(ForeignScanState *node, struct ExplainState *es)
+{
+}
+
+/*
+ * return true if node can NOT be evaluatated in foreign server.
+ */
+static bool
+foreign_qual_walker(Node *node, void *context)
+{
+ if (node == NULL)
+ return false;
+
+ switch (nodeTag(node))
+ {
+ case T_Param:
+ /* TODO: pass internal parameters to the foreign server */
+ {
+ ParamKind paramkind = ((Param *) node)->paramkind;
+ elog(DEBUG1, "%s() param=%s", __FUNCTION__,
+ paramkind == PARAM_EXTERN ? "PARAM_EXTERN" :
+ paramkind == PARAM_EXEC ? "PARAM_EXEC" :
+ paramkind == PARAM_SUBLINK ? "PARAM_SUBLINK" : "unkown");
+ }
+ if (((Param *) node)->paramkind != PARAM_EXTERN)
+ return true;
+ break;
+ case T_DistinctExpr:
+ case T_OpExpr:
+ case T_ScalarArrayOpExpr:
+ case T_FuncExpr:
+ /*
+ * If the qual contains any mutable function, the whole expression
+ * should be evaluated on local side.
+ */
+ if (contain_mutable_functions(node))
+ return true;
+ break;
+ case T_TargetEntry:
+ case T_PlaceHolderVar:
+ case T_AppendRelInfo:
+ case T_PlaceHolderInfo:
+ /* TODO: research whether those complex nodes are evaluatable. */
+ return true;
+ default:
+ break;
+ }
+
+ return expression_tree_walker(node, foreign_qual_walker, context);
+}
+
+/*
+ * Deparse the passed TupleDesc into SELECT clauses and append to the buffer
+ * 'sql'.
+ */
+static void
+deparseSelectClause(StringInfo sql, ForeignTable *table, TupleDesc tupdesc,
+ const char *aliasname, bool prefix)
+{
+ bool first;
+ int i;
+ const char *aliasname_q;
+
+ /* The alias of relation is used in both SELECT clause and FROM clause. */
+ aliasname_q = quote_identifier(aliasname);
+
+ /* deparse SELECT clause */
+ appendStringInfoString(sql, "SELECT ");
+
+ /*
+ * TODO: omit (deparse to "NULL") columns which are not used in the
+ * original SQL.
+ *
+ * We must parse nodes parents of this ForeignScan node to determine unused
+ * columns because some columns may be used only in parent Sort/Agg/Limit
+ * nodes.
+ */
+ first = true;
+ for (i = 0; i < tupdesc->natts; i++)
+ {
+#ifdef NOT_USED
+ List *options;
+ ListCell *lc;
+#endif
+ char *colname = NULL;
+
+ /* skip dropped attributes */
+ if (tupdesc->attrs[i]->attisdropped)
+ continue;
+
+ /* Determine column name to be used */
+#ifdef NOT_USED /* XXX: What was this all about? */
+ options = GetGenericOptionsPerColumn(table->relid, i + 1);
+ foreach (lc, options)
+ {
+ DefElem *def = (DefElem *) lfirst(lc);
+ if (strcmp(def->defname, "colname") == 0)
+ {
+ colname = strVal(def->arg);
+ break;
+ }
+ }
+#endif
+ if (!colname)
+ colname = tupdesc->attrs[i]->attname.data;
+
+ if (!first)
+ appendStringInfoString(sql, ", ");
+
+ if (prefix)
+ appendStringInfo(sql, "%s.%s", aliasname_q, colname);
+ else
+ appendStringInfo(sql, "%s", colname);
+
+ first = false;
+ }
+
+ /* if target list is composed only of system attributes, add dummy column */
+ if (first)
+ appendStringInfoString(sql, "NULL");
+
+ if (aliasname_q != aliasname)
+ pfree((char *) aliasname_q);
+}
+
+static void
+deparse_var(PlannerInfo *root, StringInfo buf, Var *var)
+{
+ RangeTblEntry *rte;
+ char *attname;
+
+ if (var->varlevelsup != 0)
+ elog(ERROR, "unexpected varlevelsup %d in remote query",
+ var->varlevelsup);
+
+ if (var->varno < 1 || var->varno > list_length(root->parse->rtable))
+ elog(ERROR, "unexpected varno %d in remote query", var->varno);
+ rte = rt_fetch(var->varno, root->parse->rtable);
+
+ attname = get_rte_attribute_name(rte, var->varattno);
+ appendStringInfoString(buf, quote_identifier(attname));
+}
+
+typedef struct
+{
+ PlannerInfo *root;
+ RelOptInfo *foreignrel;
+} remotely_executable_cxt;
+
+static bool
+is_proc_remotely_executable(Oid procid)
+{
+ /* assume that only built-in functions can be pushed down */
+ if (get_func_namespace(procid) != PG_CATALOG_NAMESPACE)
+ return false;
+ /* we don't check volatility here, that's done once at the top-level */
+
+ return true;
+}
+
+static bool
+is_not_remotely_executable_walker(Node *node, remotely_executable_cxt *context)
+{
+ if (node == NULL)
+ return false;
+
+ if (IsA(node, Query))
+ return true;
+
+ switch (nodeTag(node))
+ {
+ case T_Query:
+ /* give up on subqueries */
+ return true;
+ case T_Param:
+ /* TODO: pass internal parameters to the foreign server */
+ {
+ ParamKind paramkind = ((Param *) node)->paramkind;
+ elog(DEBUG1, "%s() param=%s", __FUNCTION__,
+ paramkind == PARAM_EXTERN ? "PARAM_EXTERN" :
+ paramkind == PARAM_EXEC ? "PARAM_EXEC" :
+ paramkind == PARAM_SUBLINK ? "PARAM_SUBLINK" : "unkown");
+ }
+ if (((Param *) node)->paramkind != PARAM_EXTERN)
+ return true;
+ break;
+ case T_OpExpr:
+ {
+ OpExpr *op = (OpExpr *) node;
+ if (!is_proc_remotely_executable(op->opfuncid))
+ return true;
+ else
+ return false;
+ }
+ case T_FuncExpr:
+ {
+ FuncExpr *fe = (FuncExpr *) node;
+ if (!is_proc_remotely_executable(fe->funcid))
+ return true;
+ else
+ return false;
+ }
+
+ case T_TargetEntry:
+ case T_PlaceHolderVar:
+ case T_AppendRelInfo:
+ case T_PlaceHolderInfo:
+ /* TODO: research whether those complex nodes are evaluatable. */
+ return true;
+ case T_Var:
+ {
+ Var *var = (Var *) node;
+ if (var->varno != context->foreignrel->relid || var->varlevelsup != 0)
+ return true;
+ else
+ return false;
+ }
+
+ default:
+ break;
+ }
+
+ return expression_tree_walker(node, foreign_qual_walker, context);
+}
+
+
+/*
+ * Check whether the ExprState node can be evaluated in foreign server.
+ *
+ * An expression which consists of expressions below can be evaluated in
+ * the foreign server.
+ * - constant value
+ * - variable (foreign table column)
+ * - external parameter (parameter of prepared statement)
+ * - array
+ * - bool expression (AND/OR/NOT)
+ * - NULL test (IS [NOT] NULL)
+ * - operator
+ * - IMMUTABLE only
+ * - It is required that the meaning of the operator be the same as the
+ * local server in the foreign server.
+ * - function
+ * - IMMUTABLE only
+ * - It is required that the meaning of the operator be the same as the
+ * local server in the foreign server.
+ * - scalar array operator (ANY/ALL)
+ */
+static bool
+is_foreign_qual(PlannerInfo *root, RelOptInfo *baserel, Expr *expr)
+{
+ remotely_executable_cxt context;
+
+ context.root = root;
+ context.foreignrel = baserel;
+ if (is_not_remotely_executable_walker((Node *) expr, &context))
+ return false;
+ if (contain_volatile_functions((Node *) expr))
+ return false;
+
+ return true;
+}
+
+/*
+ * Deparse query request into SQL statement.
+ *
+ * If an expression in PlanState.qual list satisfies is_foreign_qual(), the
+ * expression is:
+ * - deparsed into WHERE clause of remote SQL statement to evaluate that
+ * expression on remote side
+ * - removed from PlanState.qual list to avoid duplicate evaluation, on
+ * remote side and local side
+ */
+static char *
+deparseSql(Oid foreigntableid, PlannerInfo *root, RelOptInfo *baserel)
+{
+ List *context;
+ StringInfoData sql;
+ ForeignTable *table = GetForeignTable(foreigntableid);
+ ListCell *lc;
+ bool first;
+ char *nspname = NULL;
+ char *relname = NULL;
+
+ /* extract ForeignScan and RangeTblEntry */
+
+ /* prepare to deparse plan */
+ initStringInfo(&sql);
+
+ context = deparse_context_for("foreigntable", foreigntableid);
+
+ /* deparse SELECT target list */
+ appendStringInfoString(&sql, "SELECT ");
+ first = true;
+ foreach (lc, baserel->reltargetlist)
+ {
+ Var *var = lfirst(lc);
+
+ if (!first)
+ appendStringInfoString(&sql, ", ");
+ first = false;
+ deparse_var(root, &sql, var);
+ }
+
+ /*
+ * Deparse FROM
+ *
+ * If the foreign table has generic option "nspname" and/or "relname", use
+ * them in the foreign query. Otherwise, use local catalog names.
+ */
+ foreach(lc, table->options)
+ {
+ DefElem *opt = lfirst(lc);
+ if (strcmp(opt->defname, "nspname") == 0)
+ nspname = pstrdup(strVal(opt->arg));
+ else if (strcmp(opt->defname, "relname") == 0)
+ relname = pstrdup(strVal(opt->arg));
+ }
+ if (nspname == NULL)
+ nspname = get_namespace_name(get_rel_namespace(foreigntableid));
+ if (relname == NULL)
+ relname = get_rel_name(foreigntableid);
+ appendStringInfo(&sql, " FROM %s.%s",
+ quote_identifier(nspname),
+ quote_identifier(relname));
+
+
+ /*
+ * deparse WHERE cluase
+ *
+ * The expressions which satisfy is_foreign_qual() are deparsed into WHERE
+ * clause of result SQL string, and they could be removed from qual of
+ * PlanState to avoid duplicate evaluation at ExecScan().
+ *
+ * We never change the qual in the Plan node which was made by PREPARE
+ * statement to make following EXECUTE statements work properly. The Plan
+ * node is used repeatedly to create PlanState for each EXECUTE statement.
+ */
+ if (baserel->baserestrictinfo)
+ {
+ List *local_qual = NIL;
+ List *foreign_expr = NIL;
+ ListCell *lc;
+
+ /*
+ * Divide qual of PlanState into two lists, one for local evaluation
+ * and one for foreign evaluation.
+ */
+ foreach (lc, baserel->baserestrictinfo)
+ {
+ RestrictInfo *ri = (RestrictInfo *) lfirst(lc);
+
+ if (is_foreign_qual(root, baserel, ri->clause))
+ {
+ /* XXX: deparse and add to sql here */
+ foreign_expr = lappend(foreign_expr, ri->clause);
+ }
+ else
+ local_qual = lappend(local_qual, ri);
+ }
+ /*
+ * XXX: If the remote side is not reliable enough, we can keep the qual
+ * in PlanState as is and evaluate them on local side too. If so, just
+ * omit replacement below.
+ */
+ baserel->baserestrictinfo = local_qual;
+
+ /*
+ * Deparse quals to be evaluated in the foreign server if any.
+ * TODO: modify deparse_expression() to deparse conditions which use
+ * internal parameters.
+ */
+ if (foreign_expr != NIL)
+ {
+ Node *node;
+ node = (Node *) make_ands_explicit(foreign_expr);
+ appendStringInfo(&sql, " WHERE %s",
+ deparse_expression(node, context, false, false));
+ /*
+ * The contents of the list MUST NOT be free-ed because they are
+ * referenced from Plan.qual list.
+ */
+ list_free(foreign_expr);
+ }
+ }
+
+ elog(DEBUG1, "deparsed SQL is \"%s\"", sql.data);
+
+ return sql.data;
+}
+
+/*
+ * Initiate actual scan on a foreign table.
+ * This function is called just after pgOpen() if the ForeignScan was executed
+ * for a real query or EXPLAIN statement with ANALYZE option.
+ */
+static void
+pgBeginForeignScan(ForeignScanState *node, int eflags)
+{
+ PgsqlFdwExecutionState *festate;
+
+ Oid relid;
+ ForeignTable *table;
+ ForeignServer *server;
+ UserMapping *user;
+
+ FdwPlan *fdwplan;
+ const char *sql;
+ PGconn *conn;
+ PGresult *res;
+ ParamListInfo params = node->ss.ps.state->es_param_list_info;
+ int numParams = params ? params->numParams : 0;
+ Oid *types = NULL;
+ const char **values = NULL;
+
+ elog(DEBUG3, "%s() called", __FUNCTION__);
+
+ /*
+ * Do nothing in EXPLAIN (no ANALYZE) case. node->fdw_state stays NULL.
+ */
+ if (eflags & EXEC_FLAG_EXPLAIN_ONLY)
+ return;
+
+ festate = palloc(sizeof(PgsqlFdwExecutionState));
+
+ /* Get connection to external PostgreSQL server. */
+ relid = RelationGetRelid(node->ss.ss_currentRelation);
+ table = GetForeignTable(relid);
+ server = GetForeignServer(table->serverid);
+ user = GetUserMapping(table->serverid, GetOuterUserId());
+ conn = GetConnection(server, user);
+ festate->conn = conn;
+
+ /* construct parameter array in text format */
+ /* TODO: omit unused parameter */
+ if (numParams > 0)
+ {
+ int i;
+
+ types = palloc0(sizeof(Oid) * numParams);
+ values = palloc0(sizeof(char *) * numParams);
+ for (i = 0; i < numParams; i++)
+ {
+ types[i] = params->params[i].ptype;
+ if (params->params[i].isnull)
+ values[i] = NULL;
+ else
+ {
+ Oid out_func_oid;
+ bool isvarlena;
+ FmgrInfo func;
+
+ /* TODO: cache FmgrInfo to use it again after pgReOpen() */
+ /* TODO: send parameters in binary format rather than text */
+ getTypeOutputInfo(types[i], &out_func_oid, &isvarlena);
+ fmgr_info(out_func_oid, &func);
+ values[i] =
+ OutputFunctionCall(&func, params->params[i].value);
+ }
+ }
+ }
+
+ /*
+ * Execute query with the parameters.
+ * TODO: support internal parameters(PARAM_EXTERN)
+ * TODO: support cursor mode for huge result sets.
+ */
+ fdwplan = ((ForeignScan *) node->ss.ps.plan)->fdwplan;
+ sql = strVal(list_nth(fdwplan->fdw_private, 0));
+ res = PQexecParams(conn, sql, numParams, types, values, NULL, NULL, 0);
+ if (numParams > 0)
+ {
+ int i;
+ pfree(types);
+ for (i = 0; i < numParams; i++)
+ pfree((char *) values[i]);
+ pfree(values);
+ }
+
+ /*
+ * If the query has failed, reporting details is enough here.
+ * Connections which are used by this query (including other scans) will
+ * be cleaned up by the foreign connection manager.
+ */
+ if (!res || PQresultStatus(res) != PGRES_TUPLES_OK)
+ {
+ char *msg;
+
+ msg = pstrdup(PQerrorMessage(conn));
+ PQclear(res);
+ ereport(ERROR,
+ (errmsg("could not execute foreign query"),
+ errdetail("%s", msg),
+ errhint("%s", sql)));
+ }
+
+ festate->res = res;
+ festate->nextrow = 0;
+
+ node->fdw_state = (void *) festate;
+}
+
+/*
+ * return tuples one by one.
+ * - execute SQL statement which was deparsed in pgBeginForeignScan()
+ *
+ * The all of result are fetched at once when pgIterateForeignScan() is called
+ * first after pgBeginForeignScan() or pgReScanForeignScan().
+ * pgIterateForeignScan() moves the next tuple from tupstore to TupleTableSlot
+ * in ScanState.
+ */
+static TupleTableSlot *
+pgIterateForeignScan(ForeignScanState *node)
+{
+ TupleTableSlot *slot = node->ss.ss_ScanTupleSlot;
+ PgsqlFdwExecutionState *festate = (PgsqlFdwExecutionState *) node->fdw_state;
+
+ elog(DEBUG3, "%s() called", __FUNCTION__);
+
+ if (festate->nextrow == PQntuples(festate->res))
+ ExecClearTuple(slot);
+ else
+ storeResult(slot, festate->res, festate->nextrow++);
+
+ return slot;
+}
+
+static void
+pgReScanForeignScan(ForeignScanState *node)
+{
+ ((PgsqlFdwExecutionState *) node->fdw_state)->nextrow = 0;
+}
+
+static void
+pgEndForeignScan(ForeignScanState *node)
+{
+ PgsqlFdwExecutionState *festate = (PgsqlFdwExecutionState *) node->fdw_state;
+
+ PQclear(festate->res);
+ pfree(festate);
+}
+
+/*
+ * Store a PGresult into tuplestore.
+ */
+static void
+storeResult(TupleTableSlot *slot, PGresult *res, int rowno)
+{
+ int i;
+ int nfields;
+ int attnum; /* number of non-dropped columns */
+ char **values;
+ AttInMetadata *attinmeta;
+ Form_pg_attribute *attrs;
+ TupleDesc tupdesc = slot->tts_tupleDescriptor;
+
+ nfields = PQnfields(res);
+ attrs = tupdesc->attrs;
+
+ /* count non-dropped columns */
+ for (attnum = 0, i = 0; i < tupdesc->natts; i++)
+ if (!attrs[i]->attisdropped)
+ attnum++;
+
+ /* check result and tuple descriptor have the same number of columns */
+ if (attnum > 0 && attnum != nfields)
+ ereport(ERROR,
+ (errcode(ERRCODE_DATATYPE_MISMATCH),
+ errmsg("remote query result rowtype does not match "
+ "the specified FROM clause rowtype")));
+
+ /* buffer should include dropped columns */
+ values = palloc(sizeof(char *) * tupdesc->natts);
+
+ /* put all tuples into the tuplestore */
+ attinmeta = TupleDescGetAttInMetadata(tupdesc);
+ {
+ int j;
+ HeapTuple tuple;
+
+ for (i = 0, j = 0; i < tupdesc->natts; i++)
+ {
+ /* skip dropped columns. */
+ if (attrs[i]->attisdropped)
+ {
+ values[i] = NULL;
+ continue;
+ }
+
+ if (PQgetisnull(res, rowno, j))
+ values[i] = NULL;
+ else
+ values[i] = PQgetvalue(res, rowno, j);
+ j++;
+ }
+
+ /* build the tuple and put it into the tuplestore. */
+ tuple = BuildTupleFromCStrings(attinmeta, values);
+ ExecStoreTuple(tuple, slot, InvalidBuffer, true);
+ }
+
+ /* clean up and return the tuplestore */
+ tuplestore_donestoring(tupstore);
+ pfree(values);
+}
+
+#ifdef NOT_USED
+/*
+ * Retrieve cost-factors of the foreign server from catalog.
+ */
+static void
+get_server_costs(Oid relid, double *connection_cost, double *transfer_cost)
+{
+ ForeignTable *table;
+ ForeignServer *server;
+ int n;
+ const char **keywords;
+ const char **values;
+ int i;
+
+ /*
+ * Retrieve generic options from the target table and its server to correct
+ * costs.
+ */
+ table = GetForeignTable(relid);
+ server = GetForeignServer(table->serverid);
+ n = list_length(table->options) + list_length(server->options) + 1;
+ keywords = (const char **) palloc(sizeof(char *) * n);
+ values = (const char **) palloc(sizeof(char *) * n);
+ n = 0;
+ n += flatten_generic_options(server->options, keywords + n, values + n);
+ n += flatten_generic_options(table->options, keywords + n, values + n);
+ keywords[n] = values[n] = NULL;
+
+ for (i = 0; keywords[i]; i++)
+ {
+ if (pg_strcasecmp(keywords[i], "connection_cost") == 0)
+ *connection_cost = strtod(values[i], NULL);
+ else if (pg_strcasecmp(keywords[i], "transfer_cost") == 0)
+ *transfer_cost = strtod(values[i], NULL);
+ }
+
+ pfree(keywords);
+ pfree(values);
+}
+#endif
+
+/*
+ * Estimate costs of scanning on a foreign table.
+ *
+ * baserel->baserestrictinfo can be used to examine quals on the relation.
+ */
+static void
+pgEstimateCosts(ForeignPath *path, PlannerInfo *root, RelOptInfo *baserel)
+{
+ RangeTblEntry *rte;
+ double connection_cost = 0.0;
+ double transfer_cost = 0.0;
+
+ elog(DEBUG3, "%s() called", __FUNCTION__);
+
+ /*
+ * Use cost_seqscan() to get approximate value.
+ */
+ cost_seqscan(&path->path, root, baserel);
+
+ /* Get cost factor from catalog to correct costs. */
+ rte = planner_rt_fetch(baserel->relid, root);
+#ifdef NOT_USED
+ get_server_costs(rte->relid, &connection_cost, &transfer_cost);
+#endif
+ /* XXX arbitrary guesses */
+ connection_cost = 10.0;
+ transfer_cost = 1.0;
+ path->path.startup_cost += connection_cost;
+ path->path.total_cost += connection_cost;
+ path->path.total_cost += transfer_cost *
+ path->path.parent->width * path->path.parent->rows;
+}
+
+/* ============================================================================
+ * Connection management functions
+ * ==========================================================================*/
+
+/*
+ * Connection cache entry managed with hash table.
+ */
+typedef struct ConnCacheEntry
+{
+ /* hash key must be first */
+ char name[NAMEDATALEN]; /* connection name; used as hash key */
+ int refs; /* reference counter */
+ PGconn *conn; /* foreign server connection */
+} ConnCacheEntry;
+
+/*
+ * Hash table which is used to cache connection to PostgreSQL servers, will be
+ * initialized before first attempt to connect PostgreSQL server by the backend.
+ */
+static HTAB *FSConnectionHash;
+
+/*
+ * Get a PGconn which can be used to execute foreign query on the remote
+ * PostgreSQL server with the user's authorization. If this was the first
+ * request for the server, new connection is established.
+ */
+static PGconn *
+GetConnection(ForeignServer *server, UserMapping *user)
+{
+ const char *conname = server->servername;
+ bool found;
+ ConnCacheEntry *entry;
+ PGconn *conn = NULL;
+
+ /* initialize connection cache if it isn't */
+ if (FSConnectionHash == NULL)
+ {
+ HASHCTL ctl;
+
+ /* hash key is the name of the connection */
+ MemSet(&ctl, 0, sizeof(ctl));
+ ctl.keysize = NAMEDATALEN;
+ ctl.entrysize = sizeof(ConnCacheEntry);
+ /* allocate FSConnectionHash in the cache context */
+ ctl.hcxt = CacheMemoryContext;
+ FSConnectionHash = hash_create("Foreign Connections", 32,
+ &ctl,
+ HASH_ELEM | HASH_CONTEXT);
+ }
+
+ /* Is there any cached and valid connection with such name? */
+ entry = hash_search(FSConnectionHash, conname, HASH_ENTER, &found);
+ if (found)
+ {
+ if (entry->conn != NULL)
+ {
+ entry->refs++;
+ elog(DEBUG3, "ref %d for %s", entry->refs, entry->name);
+ return entry->conn;
+ }
+
+ /*
+ * Connection cache entry was found but connection in it is invalid.
+ * We reuse entry to store newly established connection later.
+ */
+ }
+ else
+ {
+ /*
+ * Use ResourceOner to clean the connection up on error including
+ * user interrupt.
+ */
+ entry->refs = 0;
+ entry->conn = NULL;
+ RegisterResourceReleaseCallback(cleanup_connection, entry);
+ }
+
+ /*
+ * Here we have to establish new connection.
+ * Use PG_TRY block to ensure closing connection on error.
+ */
+ PG_TRY();
+ {
+ /* Connect to the foreign PostgreSQL server */
+ conn = connect_pg_server(server, user);
+
+ /*
+ * Initialize the cache entry to keep new connection.
+ * Note: entry->name has been initialized in hash_search(HASH_ENTER).
+ */
+ entry->refs = 1;
+ entry->conn = conn;
+ elog(DEBUG3, "connected to %s (%d)", entry->name, entry->refs);
+ }
+ PG_CATCH();
+ {
+ PQfinish(conn);
+ entry->refs = 0;
+ entry->conn = NULL;
+ PG_RE_THROW();
+ }
+ PG_END_TRY();
+
+ return conn;
+}
+
+/*
+ * For non-superusers, insist that the connstr specify a password. This
+ * prevents a password from being picked up from .pgpass, a service file,
+ * the environment, etc. We don't want the postgres user's passwords
+ * to be accessible to non-superusers.
+ */
+static void
+check_conn_params(const char **keywords, const char **values)
+{
+ int i;
+
+ /* no check required if superuser */
+ if (superuser())
+ return;
+
+ /* ok if params contain a non-empty password */
+ for (i = 0; keywords[i] != NULL; i++)
+ {
+ if (strcmp(keywords[i], "password") == 0 && values[i][0] != '\0')
+ return;
+ }
+
+ ereport(ERROR,
+ (errcode(ERRCODE_S_R_E_PROHIBITED_SQL_STATEMENT_ATTEMPTED),
+ errmsg("password is required"),
+ errdetail("Non-superusers must provide a password in the connection string.")));
+}
+
+static int
+flatten_generic_options(List *defelems, const char **keywords, const char **values)
+{
+ ListCell *lc;
+ int i;
+
+ i = 0;
+ foreach(lc, defelems)
+ {
+ DefElem *d = (DefElem *) lfirst(lc);
+ keywords[i] = d->defname;
+ values[i] = strVal(d->arg);
+ i++;
+ }
+ return i;
+}
+
+static PGconn *
+connect_pg_server(ForeignServer *server, UserMapping *user)
+{
+ const char *conname = server->servername;
+ PGconn *conn;
+ const char **all_keywords;
+ const char **all_values;
+ const char **keywords;
+ const char **values;
+ int n;
+ int i, j;
+
+ /*
+ * Construct connection params from generic options of ForeignServer and
+ * UserMapping. Generic options might not be a one of connection options.
+ */
+ n = list_length(server->options) + list_length(user->options) + 1;
+ all_keywords = (const char **) palloc(sizeof(char *) * n);
+ all_values = (const char **) palloc(sizeof(char *) * n);
+ keywords = (const char **) palloc(sizeof(char *) * n);
+ values = (const char **) palloc(sizeof(char *) * n);
+ n = 0;
+ n += flatten_generic_options(server->options,
+ all_keywords + n, all_values + n);
+ n += flatten_generic_options(user->options,
+ all_keywords + n, all_values + n);
+ all_keywords[n] = all_values[n] = NULL;
+
+ for (i = 0, j = 0; all_keywords[i]; i++)
+ {
+ /* Use only libpq connection options. */
+ if (!is_libpq_connection_option(all_keywords[i]))
+ continue;
+ keywords[j] = all_keywords[i];
+ values[j] = all_values[i];
+ j++;
+ }
+ keywords[j] = values[j] = NULL;
+ pfree(all_keywords);
+ pfree(all_values);
+
+ /* verify connection parameters and do connect */
+ check_conn_params(keywords, values);
+ conn = PQconnectdbParams(keywords, values, 0);
+ if (!conn || PQstatus(conn) != CONNECTION_OK)
+ ereport(ERROR,
+ (errcode(ERRCODE_SQLCLIENT_UNABLE_TO_ESTABLISH_SQLCONNECTION),
+ errmsg("could not connect to server \"%s\"", conname),
+ errdetail("%s", PQerrorMessage(conn))));
+ pfree(keywords);
+ pfree(values);
+
+ return conn;
+}
+
+/*
+ * Mark the connection as "unused", and close it if the caller was the last
+ * user of the connection.
+ */
+static void
+ReleaseConnection(PGconn *conn)
+{
+ HASH_SEQ_STATUS scan;
+ ConnCacheEntry *entry;
+
+ if (conn == NULL)
+ return;
+
+ /*
+ * We need to scan seqencially since we use the address to find appropriate
+ * PGconn from the hash table.
+ */
+ hash_seq_init(&scan, FSConnectionHash);
+ while ((entry = (ConnCacheEntry *) hash_seq_search(&scan)))
+ {
+ if (entry->conn == conn)
+ break;
+ }
+ hash_seq_term(&scan);
+
+ /*
+ * If the released connection was an orphan, just close it.
+ */
+ if (entry == NULL)
+ {
+ PQfinish(conn);
+ return;
+ }
+
+ /* If the caller was the last referer, unregister it from cache. */
+ entry->refs--;
+ elog(DEBUG3, "ref %d for %s", entry->refs, entry->name);
+ if (entry->refs == 0)
+ {
+ elog(DEBUG3, "closing connection \"%s\"", entry->name);
+ PQfinish(entry->conn);
+ entry->refs = 0;
+ entry->conn = NULL;
+ }
+}
+
+/*
+ * Clean the connection up via ResourceOwner when pgClose couldn't close the
+ * connection gracefully.
+ */
+static void
+cleanup_connection(ResourceReleasePhase phase,
+ bool isCommit,
+ bool isTopLevel,
+ void *arg)
+{
+ ConnCacheEntry *entry = (ConnCacheEntry *) arg;
+
+ /*
+ * If the transaction was committed, the connection has been closed via
+ * pgClose() and ReleaseConnection().
+ */
+ if (isCommit)
+ return;
+
+ /*
+ * We clean the connection up on post-lock because foreign connections are
+ * backend-internal resource.
+ */
+ if (phase != RESOURCE_RELEASE_AFTER_LOCKS)
+ return;
+
+ /*
+ * We ignore cleanup for ResourceOwners other than transaction. At this
+ * point, such a ResourceOwner is only Portal.
+ */
+ if (CurrentResourceOwner != CurTransactionResourceOwner)
+ return;
+
+ /*
+ * We don't care whether we are in TopTransaction or Subtransaction.
+ * Anyway, we close the connection and reset the reference counter.
+ */
+ if (entry->conn != NULL)
+ {
+ elog(DEBUG3, "closing connection to %s", entry->name);
+ PQfinish(entry->conn);
+ entry->refs = 0;
+ entry->conn = NULL;
+ }
+ else
+ elog(DEBUG3, "connection to %s already closed", entry->name);
+}
--- /dev/null
+<!-- doc/src/sgml/postgresql_fdw.sgml -->
+
+<sect1 id="postgresql-fdw">
+ <title>postgresql_fdw</title>
+
+ <indexterm zone="postgresql-fdw">
+ <primary>postgresql_fdw</primary>
+ </indexterm>
+
+ <para>
+ The <filename>postgresql_fdw</> module provides foreign-data wrapper
+ handler function <function>postgresql_fdw_handler</function> which can be
+ used to access external <productname>PostgreSQL</> server via plain SQL.
+ </para>
+
+ <sect2>
+ <title>Functions</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>postgresql_fdw_handler() returns fdw_handler</function>
+ </term>
+
+ <listitem>
+ <para>
+ <function>postgresql_fdw_handler</function> is a foreign-data wrapper
+ handler function which returns foreign-data wrapper handler for
+ PostgreSQL in type of <type>fdw_handler</type>.
+ Since fdw_hanlder is a pseudo type, postgresql_fdw_handler can't be
+ called from a SQL statement.
+ </para>
+ <para>
+ Internally, it returns a pointer to a <structname>FdwRoutine</structname>
+ object which has set of foreign-data wrapper API functions for handling
+ foreign scan on the external PostgreSQL server. Functions other than
+ Iterate can be NULL if the foreign-data wrapper has nothing to do in the
+ function.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </sect2>
+
+ <sect2>
+ <title>Details of postgresql_fdw</title>
+
+ <sect3>
+ <title>Connection options</title>
+ <para>
+ The postgresql_fdw retrieves connection information from generic options of
+ user mapping and foriegn server. All of generic options of these objects
+ are passed to <function>PQconnectdbParams()</function>.
+ </para>
+ <para>
+ Currently, all of the generic options which are allowed in the context of
+ user mapping and foreign server are libpq connection options.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Connection management</title>
+ <para>
+ The postgresql_fdw connects to a remote PostgreSQL server when
+ <function>pgConnectServer()</function> is called for the foreign server
+ first time in the local query. The connection is used by all of remote
+ queries which are executed on same remote PostgreSQL server.
+ If the local query uses multiple foreign PostgreSQL servers, connections
+ are established for each server (not for each foreign table) and all of
+ them will be closed at the end of the query. This also means that
+ connection pooling is not implemented in postgresql_fdw.
+ </para>
+ <para>
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Transaction management</title>
+ <para>
+ The postgresql_fdw never emit transaction command such as <command>BEGIN</>,
+ <command>ROLLBACK</> and <command>COMMIT</>. Thus, all SQL statements are
+ executed in each transaction when '<varname>autocommit</>' was set to 'on'.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Retrieving all tuples at once</title>
+ <para>
+ The postgresql_fdw retrieves all of the result tuples at once via libpq
+ when the query was executed. Note that huge result set causes huge memory
+ consumption. The memory for the result set will be freed at the end of the
+ each query.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>WHERE clause push-down</title>
+ <para>
+ The postgresql_fdw pushes some part of WHERE clause down to the remote
+ server, only if the evaluating the part of clause doesn't break the
+ consistency of the query. If a clause consist of elements below, the
+ clause will be pushed down.
+ </para>
+ <table id="postgresql-fdw-push-downable">
+ <title>push-down-able elements</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Element</entry>
+ <entry>Note</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Constant value and column reference</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Array of push-down-able type</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Parameter of <command>EXECUTE</command></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Bool expression such as <literal>A AND B</literal> or
+ <literal>A OR B</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Immutable operator</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>DISTINCT operator, such as
+ <literal>A IS DISTINCT FROM B</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Scalar array operator, such as <literal>ALL(...)</literal> and
+ <literal>ANY(...)</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Immutable function call</entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </sect3>
+
+ </sect2>
+
+</sect1>
+<!-- doc/src/sgml/postgresql_fdw.sgml -->
+
+<sect1 id="postgresql-fdw">
+ <title>postgresql_fdw</title>
+
+ <indexterm zone="postgresql-fdw">
+ <primary>postgresql_fdw</primary>
+ </indexterm>
+
+ <para>
+ The <filename>postgresql_fdw</> module provides foreign-data wrapper
+ handler function <function>postgresql_fdw_handler</function> which can be
+ used to access external <productname>PostgreSQL</> server via plain SQL.
+ </para>
+
+ <sect2>
+ <title>Functions</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>postgresql_fdw_handler() returns fdw_handler</function>
+ </term>
+
+ <listitem>
+ <para>
+ <function>postgresql_fdw_handler</function> is a foreign-data wrapper
+ handler function which returns foreign-data wrapper handler for
+ PostgreSQL in type of <type>fdw_handler</type>.
+ Since fdw_hanlder is a pseudo type, postgresql_fdw_handler can't be
+ called from a SQL statement.
+ </para>
+ <para>
+ Internally, it returns a pointer to a <structname>FdwRoutine</structname>
+ object which has set of foreign-data wrapper API functions for handling
+ foreign scan on the external PostgreSQL server. Functions other than
+ Iterate can be NULL if the foreign-data wrapper has nothing to do in the
+ function.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </sect2>
+
+ <sect2>
+ <title>Details of postgresql_fdw</title>
+
+ <sect3>
+ <title>Connection options</title>
+ <para>
+ The postgresql_fdw retrieves connection information from generic options of
+ user mapping and foriegn server. All of generic options of these objects
+ are passed to <function>PQconnectdbParams()</function>.
+ </para>
+ <para>
+ Currently, all of the generic options which are allowed in the context of
+ user mapping and foreign server are libpq connection options.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Connection management</title>
+ <para>
+ The postgresql_fdw connects to a remote PostgreSQL server when
+ <function>pgConnectServer()</function> is called for the foreign server
+ first time in the local query. The connection is used by all of remote
+ queries which are executed on same remote PostgreSQL server.
+ If the local query uses multiple foreign PostgreSQL servers, connections
+ are established for each server (not for each foreign table) and all of
+ them will be closed at the end of the query. This also means that
+ connection pooling is not implemented in postgresql_fdw.
+ </para>
+ <para>
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Transaction management</title>
+ <para>
+ The postgresql_fdw never emit transaction command such as <command>BEGIN</>,
+ <command>ROLLBACK</> and <command>COMMIT</>. Thus, all SQL statements are
+ executed in each transaction when '<varname>autocommit</>' was set to 'on'.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Retrieving all tuples at once</title>
+ <para>
+ The postgresql_fdw retrieves all of the result tuples at once via libpq
+ when the query was executed. Note that huge result set causes huge memory
+ consumption. The memory for the result set will be freed at the end of the
+ each query.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>WHERE clause push-down</title>
+ <para>
+ The postgresql_fdw pushes some part of WHERE clause down to the remote
+ server, only if the evaluating the part of clause doesn't break the
+ consistency of the query. If a clause consist of elements below, the
+ clause will be pushed down.
+ </para>
+ <table id="postgresql-fdw-push-downable">
+ <title>push-down-able elements</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Element</entry>
+ <entry>Note</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Constant value and column reference</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Array of push-down-able type</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Parameter of <command>EXECUTE</command></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Bool expression such as <literal>A AND B</literal> or
+ <literal>A OR B</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Immutable operator</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>DISTINCT operator, such as
+ <literal>A IS DISTINCT FROM B</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Scalar array operator, such as <literal>ALL(...)</literal> and
+ <literal>ANY(...)</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Immutable function call</entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </sect3>
+
+ </sect2>
+
+</sect1>
+<!-- doc/src/sgml/postgresql_fdw.sgml -->
+
+<sect1 id="postgresql-fdw">
+ <title>postgresql_fdw</title>
+
+ <indexterm zone="postgresql-fdw">
+ <primary>postgresql_fdw</primary>
+ </indexterm>
+
+ <para>
+ The <filename>postgresql_fdw</> module provides foreign-data wrapper
+ handler function <function>postgresql_fdw_handler</function> which can be
+ used to access external <productname>PostgreSQL</> server via plain SQL.
+ </para>
+
+ <sect2>
+ <title>Functions</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>postgresql_fdw_handler() returns fdw_handler</function>
+ </term>
+
+ <listitem>
+ <para>
+ <function>postgresql_fdw_handler</function> is a foreign-data wrapper
+ handler function which returns foreign-data wrapper handler for
+ PostgreSQL in type of <type>fdw_handler</type>.
+ Since fdw_hanlder is a pseudo type, postgresql_fdw_handler can't be
+ called from a SQL statement.
+ </para>
+ <para>
+ Internally, it returns a pointer to a <structname>FdwRoutine</structname>
+ object which has set of foreign-data wrapper API functions for handling
+ foreign scan on the external PostgreSQL server. Functions other than
+ Iterate can be NULL if the foreign-data wrapper has nothing to do in the
+ function.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </sect2>
+
+ <sect2>
+ <title>Details of postgresql_fdw</title>
+
+ <sect3>
+ <title>Connection options</title>
+ <para>
+ The postgresql_fdw retrieves connection information from generic options of
+ user mapping and foriegn server. All of generic options of these objects
+ are passed to <function>PQconnectdbParams()</function>.
+ </para>
+ <para>
+ Currently, all of the generic options which are allowed in the context of
+ user mapping and foreign server are libpq connection options.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Connection management</title>
+ <para>
+ The postgresql_fdw connects to a remote PostgreSQL server when
+ <function>pgConnectServer()</function> is called for the foreign server
+ first time in the local query. The connection is used by all of remote
+ queries which are executed on same remote PostgreSQL server.
+ If the local query uses multiple foreign PostgreSQL servers, connections
+ are established for each server (not for each foreign table) and all of
+ them will be closed at the end of the query. This also means that
+ connection pooling is not implemented in postgresql_fdw.
+ </para>
+ <para>
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Transaction management</title>
+ <para>
+ The postgresql_fdw never emit transaction command such as <command>BEGIN</>,
+ <command>ROLLBACK</> and <command>COMMIT</>. Thus, all SQL statements are
+ executed in each transaction when '<varname>autocommit</>' was set to 'on'.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Retrieving all tuples at once</title>
+ <para>
+ The postgresql_fdw retrieves all of the result tuples at once via libpq
+ when the query was executed. Note that huge result set causes huge memory
+ consumption. The memory for the result set will be freed at the end of the
+ each query.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>WHERE clause push-down</title>
+ <para>
+ The postgresql_fdw pushes some part of WHERE clause down to the remote
+ server, only if the evaluating the part of clause doesn't break the
+ consistency of the query. If a clause consist of elements below, the
+ clause will be pushed down.
+ </para>
+ <table id="postgresql-fdw-push-downable">
+ <title>push-down-able elements</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Element</entry>
+ <entry>Note</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Constant value and column reference</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Array of push-down-able type</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Parameter of <command>EXECUTE</command></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Bool expression such as <literal>A AND B</literal> or
+ <literal>A OR B</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Immutable operator</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>DISTINCT operator, such as
+ <literal>A IS DISTINCT FROM B</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Scalar array operator, such as <literal>ALL(...)</literal> and
+ <literal>ANY(...)</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Immutable function call</entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </sect3>
+
+ </sect2>
+
+</sect1>
+<!-- doc/src/sgml/postgresql_fdw.sgml -->
+
+<sect1 id="postgresql-fdw">
+ <title>postgresql_fdw</title>
+
+ <indexterm zone="postgresql-fdw">
+ <primary>postgresql_fdw</primary>
+ </indexterm>
+
+ <para>
+ The <filename>postgresql_fdw</> module provides foreign-data wrapper
+ handler function <function>postgresql_fdw_handler</function> which can be
+ used to access external <productname>PostgreSQL</> server via plain SQL.
+ </para>
+
+ <sect2>
+ <title>Functions</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>postgresql_fdw_handler() returns fdw_handler</function>
+ </term>
+
+ <listitem>
+ <para>
+ <function>postgresql_fdw_handler</function> is a foreign-data wrapper
+ handler function which returns foreign-data wrapper handler for
+ PostgreSQL in type of <type>fdw_handler</type>.
+ Since fdw_hanlder is a pseudo type, postgresql_fdw_handler can't be
+ called from a SQL statement.
+ </para>
+ <para>
+ Internally, it returns a pointer to a <structname>FdwRoutine</structname>
+ object which has set of foreign-data wrapper API functions for handling
+ foreign scan on the external PostgreSQL server. Functions other than
+ Iterate can be NULL if the foreign-data wrapper has nothing to do in the
+ function.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </sect2>
+
+ <sect2>
+ <title>Details of postgresql_fdw</title>
+
+ <sect3>
+ <title>Connection options</title>
+ <para>
+ The postgresql_fdw retrieves connection information from generic options of
+ user mapping and foriegn server. All of generic options of these objects
+ are passed to <function>PQconnectdbParams()</function>.
+ </para>
+ <para>
+ Currently, all of the generic options which are allowed in the context of
+ user mapping and foreign server are libpq connection options.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Connection management</title>
+ <para>
+ The postgresql_fdw connects to a remote PostgreSQL server when
+ <function>pgConnectServer()</function> is called for the foreign server
+ first time in the local query. The connection is used by all of remote
+ queries which are executed on same remote PostgreSQL server.
+ If the local query uses multiple foreign PostgreSQL servers, connections
+ are established for each server (not for each foreign table) and all of
+ them will be closed at the end of the query. This also means that
+ connection pooling is not implemented in postgresql_fdw.
+ </para>
+ <para>
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Transaction management</title>
+ <para>
+ The postgresql_fdw never emit transaction command such as <command>BEGIN</>,
+ <command>ROLLBACK</> and <command>COMMIT</>. Thus, all SQL statements are
+ executed in each transaction when '<varname>autocommit</>' was set to 'on'.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Retrieving all tuples at once</title>
+ <para>
+ The postgresql_fdw retrieves all of the result tuples at once via libpq
+ when the query was executed. Note that huge result set causes huge memory
+ consumption. The memory for the result set will be freed at the end of the
+ each query.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>WHERE clause push-down</title>
+ <para>
+ The postgresql_fdw pushes some part of WHERE clause down to the remote
+ server, only if the evaluating the part of clause doesn't break the
+ consistency of the query. If a clause consist of elements below, the
+ clause will be pushed down.
+ </para>
+ <table id="postgresql-fdw-push-downable">
+ <title>push-down-able elements</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Element</entry>
+ <entry>Note</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Constant value and column reference</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Array of push-down-able type</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Parameter of <command>EXECUTE</command></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Bool expression such as <literal>A AND B</literal> or
+ <literal>A OR B</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Immutable operator</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>DISTINCT operator, such as
+ <literal>A IS DISTINCT FROM B</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Scalar array operator, such as <literal>ALL(...)</literal> and
+ <literal>ANY(...)</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Immutable function call</entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </sect3>
+
+ </sect2>
+
+</sect1>
+<!-- doc/src/sgml/postgresql_fdw.sgml -->
+
+<sect1 id="postgresql-fdw">
+ <title>postgresql_fdw</title>
+
+ <indexterm zone="postgresql-fdw">
+ <primary>postgresql_fdw</primary>
+ </indexterm>
+
+ <para>
+ The <filename>postgresql_fdw</> module provides foreign-data wrapper
+ handler function <function>postgresql_fdw_handler</function> which can be
+ used to access external <productname>PostgreSQL</> server via plain SQL.
+ </para>
+
+ <sect2>
+ <title>Functions</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>postgresql_fdw_handler() returns fdw_handler</function>
+ </term>
+
+ <listitem>
+ <para>
+ <function>postgresql_fdw_handler</function> is a foreign-data wrapper
+ handler function which returns foreign-data wrapper handler for
+ PostgreSQL in type of <type>fdw_handler</type>.
+ Since fdw_hanlder is a pseudo type, postgresql_fdw_handler can't be
+ called from a SQL statement.
+ </para>
+ <para>
+ Internally, it returns a pointer to a <structname>FdwRoutine</structname>
+ object which has set of foreign-data wrapper API functions for handling
+ foreign scan on the external PostgreSQL server. Functions other than
+ Iterate can be NULL if the foreign-data wrapper has nothing to do in the
+ function.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </sect2>
+
+ <sect2>
+ <title>Details of postgresql_fdw</title>
+
+ <sect3>
+ <title>Connection options</title>
+ <para>
+ The postgresql_fdw retrieves connection information from generic options of
+ user mapping and foriegn server. All of generic options of these objects
+ are passed to <function>PQconnectdbParams()</function>.
+ </para>
+ <para>
+ Currently, all of the generic options which are allowed in the context of
+ user mapping and foreign server are libpq connection options.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Connection management</title>
+ <para>
+ The postgresql_fdw connects to a remote PostgreSQL server when
+ <function>pgConnectServer()</function> is called for the foreign server
+ first time in the local query. The connection is used by all of remote
+ queries which are executed on same remote PostgreSQL server.
+ If the local query uses multiple foreign PostgreSQL servers, connections
+ are established for each server (not for each foreign table) and all of
+ them will be closed at the end of the query. This also means that
+ connection pooling is not implemented in postgresql_fdw.
+ </para>
+ <para>
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Transaction management</title>
+ <para>
+ The postgresql_fdw never emit transaction command such as <command>BEGIN</>,
+ <command>ROLLBACK</> and <command>COMMIT</>. Thus, all SQL statements are
+ executed in each transaction when '<varname>autocommit</>' was set to 'on'.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Retrieving all tuples at once</title>
+ <para>
+ The postgresql_fdw retrieves all of the result tuples at once via libpq
+ when the query was executed. Note that huge result set causes huge memory
+ consumption. The memory for the result set will be freed at the end of the
+ each query.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>WHERE clause push-down</title>
+ <para>
+ The postgresql_fdw pushes some part of WHERE clause down to the remote
+ server, only if the evaluating the part of clause doesn't break the
+ consistency of the query. If a clause consist of elements below, the
+ clause will be pushed down.
+ </para>
+ <table id="postgresql-fdw-push-downable">
+ <title>push-down-able elements</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Element</entry>
+ <entry>Note</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Constant value and column reference</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Array of push-down-able type</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Parameter of <command>EXECUTE</command></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Bool expression such as <literal>A AND B</literal> or
+ <literal>A OR B</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Immutable operator</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>DISTINCT operator, such as
+ <literal>A IS DISTINCT FROM B</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Scalar array operator, such as <literal>ALL(...)</literal> and
+ <literal>ANY(...)</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Immutable function call</entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </sect3>
+
+ </sect2>
+
+</sect1>
projects / users / hanada / postgres.git / commitdiff