database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-28 23:42:10 +03:00
Code Activity

Create the catalog infrastructure for foreign-data-wrapper handlers.

Browse Source 
Add a fdwhandler column to pg_foreign_data_wrapper, plus HANDLER options
in the CREATE FOREIGN DATA WRAPPER and ALTER FOREIGN DATA WRAPPER commands,
plus pg_dump support for same.  Also invent a new pseudotype fdw_handler
with properties similar to language_handler.

This is split out of the "FDW API" patch for ease of review; it's all stuff
we will certainly need, regardless of any other details of the FDW API.
FDW handler functions will not actually get called yet.

In passing, fix some omissions and infelicities in foreigncmds.c.

Shigeru Hanada, Jan Urbanski, Heikki Linnakangas
This commit is contained in:
Tom Lane
2011-02-19 00:06:18 -05:00
parent 4077980d67
commit 327e025071
22 changed files with 496 additions and 210 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
doc/src/sgml/catalogs.sgml
View File

@ -3031,16 +3031,27 @@
<entry>Owner of the foreign-data wrapper</entry>
</row>
<row>
<entry><structfield>fdwhandler</structfield></entry>
<entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
<entry>
References a handler function that is responsible for
supplying execution routines for the foreign-data wrapper.
Zero if no handler is provided
</entry>
</row>
<row>
<entry><structfield>fdwvalidator</structfield></entry>
<entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
<entry>
References a validator function that is responsible for
checking the validity of the generic options given to the
foreign-data wrapper, as well as to foreign servers and user
checking the validity of the options given to the
foreign-data wrapper, as well as options for foreign servers and user
mappings using the foreign-data wrapper. Zero if no validator
is provided.
is provided
</entry>
</row>
@ -3079,8 +3090,8 @@
<para>
The catalog <structname>pg_foreign_server</structname> stores
foreign server definitions. A foreign server describes the
connection to a remote server, managing external data. Foreign
foreign server definitions. A foreign server describes a source
of external data, such as a remote server. Foreign
servers are accessed via foreign-data wrappers.
</para>
@ -3116,7 +3127,7 @@
<entry><structfield>srvfdw</structfield></entry>
<entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-foreign-data-wrapper"><structname>pg_foreign_data_wrapper</structname></link>.oid</literal></entry>
<entry>The OID of the foreign-data wrapper of this foreign server</entry>
<entry>OID of the foreign-data wrapper of this foreign server</entry>
</row>
<row>
@ -3167,9 +3178,12 @@
</indexterm>
<para>
The catalog <structname>pg_foreign_table</structname> contains part
of the information about foreign tables.
The rest is mostly in <structname>pg_class</structname>.
The catalog <structname>pg_foreign_table</structname> contains
auxiliary information about foreign tables. A foreign table is
primarily represented by a <structname>pg_class</structname> entry,
just like a regular table. Its <structname>pg_foreign_table</structname>
entry contains the information that is pertinent only to foreign tables
and not any other kind of relation.
</para>
<table>
@ -3190,14 +3204,14 @@
<entry><structfield>ftrelid</structfield></entry>
<entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
<entry>The OID of the <structname>pg_class</> entry for this foreign table</entry>
<entry>OID of the <structname>pg_class</> entry for this foreign table</entry>
</row>
<row>
<entry><structfield>ftserver</structfield></entry>
<entry><type>oid</type></entry>
<entry><literal><link linkend="catalog-pg-foreign-server"><structname>pg_foreign_server</structname></link>.oid</literal></entry>
<entry>The OID of the foreign server for this foreign table</entry>
<entry>OID of the foreign server for this foreign table</entry>
</row>
<row>
@ -3205,7 +3219,7 @@
<entry><type>text[]</type></entry>
<entry></entry>
<entry>
Foreign table options, as <quote>keyword=value</> strings.
Foreign table options, as <quote>keyword=value</> strings
</entry>
</row>
</tbody>

9
doc/src/sgml/datatype.sgml
View File

@ -4431,6 +4431,10 @@ SELECT * FROM pg_attribute
<primary>language_handler</primary>
</indexterm>
<indexterm zone="datatype-pseudo">
<primary>fdw_handler</primary>
</indexterm>
<indexterm zone="datatype-pseudo">
<primary>cstring</primary>
</indexterm>
@ -4513,6 +4517,11 @@ SELECT * FROM pg_attribute
<entry>A procedural language call handler is declared to return <type>language_handler</>.</entry>
</row>
<row>
<entry><type>fdw_handler</></entry>
<entry>A foreign-data wrapper handler is declared to return <type>fdw_handler</>.</entry>
</row>
<row>
<entry><type>record</></entry>
<entry>Identifies a function returning an unspecified row type.</entry>

39
doc/src/sgml/ref/alter_foreign_data_wrapper.sgml
View File

@ -22,7 +22,8 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
[ VALIDATOR <replaceable class="parameter">valfunction</replaceable> | NO VALIDATOR ]
[ HANDLER <replaceable class="parameter">handler_function</replaceable> | NO HANDLER ]
[ VALIDATOR <replaceable class="parameter">validator_function</replaceable> | NO VALIDATOR ]
[ OPTIONS ( [ ADD | SET | DROP ] <replaceable class="PARAMETER">option</replaceable> ['<replaceable class="PARAMETER">value</replaceable>'] [, ... ]) ]
ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> OWNER TO <replaceable>new_owner</replaceable>
</synopsis>
@ -34,7 +35,7 @@ ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> OWN
<para>
<command>ALTER FOREIGN DATA WRAPPER</command> changes the
definition of a foreign-data wrapper. The first form of the
command changes the library or the generic options of the
command changes the support functions or the generic options of the
foreign-data wrapper (at least one clause is required). The second
form changes the owner of the foreign-data wrapper.
</para>
@ -59,10 +60,33 @@ ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> OWN
</varlistentry>
<varlistentry>
<term><literal>VALIDATOR <replaceable class="parameter">valfunction</replaceable></literal></term>
<term><literal>HANDLER <replaceable class="parameter">handler_function</replaceable></literal></term>
<listitem>
<para>
Specifies a new foreign-data wrapper validator function.
Specifies a new handler function for the foreign-data wrapper.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>NO HANDLER</literal></term>
<listitem>
<para>
This is used to specify that the foreign-data wrapper should no
longer have a handler function.
</para>
<para>
Note that foreign tables that use a foreign-data wrapper with no
handler cannot be accessed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>VALIDATOR <replaceable class="parameter">validator_function</replaceable></literal></term>
<listitem>
<para>
Specifies a new validator function for the foreign-data wrapper.
</para>
<para>
@ -94,7 +118,7 @@ ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> OWN
specify the action to be performed. <literal>ADD</> is assumed
if no operation is explicitly specified. Option names must be
unique; names and values are also validated using the foreign
data wrapper library.
data wrapper's validator function, if any.
</para>
</listitem>
</varlistentry>
@ -126,9 +150,8 @@ ALTER FOREIGN DATA WRAPPER dbi VALIDATOR bob.myvalidator;
<para>
<command>ALTER FOREIGN DATA WRAPPER</command> conforms to ISO/IEC
9075-9 (SQL/MED). The standard does not specify the <literal>
VALIDATOR</literal> and <literal>OWNER TO</> variants of the
command.
9075-9 (SQL/MED), except that the <literal>HANDLER</literal>,
<literal>VALIDATOR</> and <literal>OWNER TO</> clauses are extensions.
</para>
</refsect1>

50
doc/src/sgml/ref/create_foreign_data_wrapper.sgml
View File

@ -22,7 +22,8 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
[ VALIDATOR <replaceable class="parameter">valfunction</replaceable> | NO VALIDATOR ]
[ HANDLER <replaceable class="parameter">handler_function</replaceable> | NO HANDLER ]
[ VALIDATOR <replaceable class="parameter">validator_function</replaceable> | NO VALIDATOR ]
[ OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] ) ]
</synopsis>
</refsynopsisdiv>
@ -59,13 +60,32 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
</varlistentry>
<varlistentry>
<term><literal>VALIDATOR <replaceable class="parameter">valfunction</replaceable></literal></term>
<term><literal>HANDLER <replaceable class="parameter">handler_function</replaceable></literal></term>
<listitem>
<para>
<replaceable class="parameter">valfunction</replaceable> is the
<replaceable class="parameter">handler_function</replaceable> is the
name of a previously registered function that will be called to
retrieve the execution functions for foreign tables.
The handler function must take no arguments, and
its return type must be <type>fdw_handler</type>.
</para>
<para>
It is possible to create a foreign-data wrapper with no handler
function, but foreign tables using such a wrapper can only be declared,
not accessed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>VALIDATOR <replaceable class="parameter">validator_function</replaceable></literal></term>
<listitem>
<para>
<replaceable class="parameter">validator_function</replaceable> is the
name of a previously registered function that will be called to
check the generic options given to the foreign-data wrapper, as
well as to foreign servers and user mappings using the
well as options for foreign servers and user mappings using the
foreign-data wrapper. If no validator function or <literal>NO
VALIDATOR</literal> is specified, then options will not be
checked at creation time. (Foreign-data wrappers will possibly
@ -75,8 +95,8 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
contain the array of options as stored in the system catalogs,
and one of type <type>oid</type>, which will be the OID of the
system catalog containing the options. The return type is ignored;
the function should indicate invalid options using the
<function>ereport()</function> function.
the function should report invalid options using the
<function>ereport(ERROR)</function> function.
</para>
</listitem>
</varlistentry>
@ -87,8 +107,8 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
<para>
This clause specifies options for the new foreign-data wrapper.
The allowed option names and values are specific to each foreign
data wrapper and are validated using the foreign-data wrapper
library. Option names must be unique.
data wrapper and are validated using the foreign-data wrapper's
validator function. Option names must be unique.
</para>
</listitem>
</varlistentry>
@ -122,17 +142,17 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
<title>Examples</title>
<para>
Create a foreign-data wrapper <literal>dummy</>:
Create a useless foreign-data wrapper <literal>dummy</>:
<programlisting>
CREATE FOREIGN DATA WRAPPER dummy;
</programlisting>
</para>
<para>
Create a foreign-data wrapper <literal>postgresql</> with
validator function <literal>postgresql_fdw_validator</>:
Create a foreign-data wrapper <literal>file</> with
handler function <literal>file_fdw_handler</>:
<programlisting>
CREATE FOREIGN DATA WRAPPER postgresql VALIDATOR postgresql_fdw_validator;
CREATE FOREIGN DATA WRAPPER file HANDLER file_fdw_handler;
</programlisting>
</para>
@ -151,10 +171,10 @@ CREATE FOREIGN DATA WRAPPER mywrapper
<para>
<command>CREATE FOREIGN DATA WRAPPER</command> conforms to ISO/IEC
9075-9 (SQL/MED), with the exception that
the <literal>VALIDATOR</literal> clause is an extension and the
9075-9 (SQL/MED), with the exception that the <literal>HANDLER</literal>
and <literal>VALIDATOR</literal> clauses are extensions and the standard
clauses <literal>LIBRARY</literal> and <literal>LANGUAGE</literal>
are not yet implemented in PostgreSQL.
are not implemented in PostgreSQL.
</para>
<para>