8000 Create the catalog infrastructure for foreign-data-wrapper handlers. · postgrespro/postgres_cluster@327e025 · GitHub
[go: up one dir, main page]
Skip to content

Commit 327e025

Browse files
tglsfdctglsfdc
committed
Create the catalog infrastructure for foreign-data-wrapper handlers.
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
1 parent 4077980 commit 327e025

File tree

22 files changed

+496
-210
lines changed

22 files changed

+496
-210
lines changed

‎doc/src/sgml/catalogs.sgml‎

Lines changed: 26 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3031,16 +3031,27 @@
30313031
<entry>Owner of the foreign-data wrapper</entry>
30323032
</row>
30333033

3034+
<row>
3035+
<entry><structfield>fdwhandler</structfield></entry>
3036+
<entry><type>oid</type></entry>
3037+
<entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
3038+
<entry>
3039+
References a handler function that is responsible for
3040+
supplying execution routines for the foreign-data wrapper.
3041+
Zero if no handler is provided
3042+
</entry>
3043+
</row>
3044+
30343045
<row>
30353046
<entry><structfield>fdwvalidator</structfield></entry>
30363047
<entry><type>oid</type></entry>
30373048
<entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
30383049
<entry>
30393050
References a validator function that is responsible for
3040-
checking the validity of the generic options given to the
3041-
foreign-data wrapper, as well as to foreign servers and user
3051+
checking the validity of the options given to the
3052+
foreign-data wrapper, as well as options for foreign servers and user
30423053
mappings using the foreign-data wrapper. Zero if no validator
3043-
is provided.
3054+
is provided
30443055
</entry>
30453056
</row>
30463057

@@ -3079,8 +3090,8 @@
30793090

30803091
<para>
30813092
The catalog <structname>pg_foreign_server</structname> stores
3082-
foreign server definitions. A foreign server describes the
3083-
connection to a remote server, managing external data. Foreign
3093+
foreign server definitions. A foreign server describes a source
3094+
of external data, such as a remote server. Foreign
30843095
servers are accessed via foreign-data wrappers.
30853096
</para>
30863097

@@ -3116,7 +3127,7 @@
31163127
<entry><structfield>srvfdw</structfield></entry>
31173128
<entry><type>oid</type></entry>
31183129
<entry><literal><link linkend="catalog-pg-foreign-data-wrapper"><structname>pg_foreign_data_wrapper</structname></link>.oid</literal></entry>
3119-
<entry>The OID of the foreign-data wrapper of this foreign server</entry>
3130+
<entry>OID of the foreign-data wrapper of this foreign server</entry>
31203131
</row>
31213132

31223133
<row>
@@ -3167,9 +3178,12 @@
31673178
</indexterm>
31683179

31693180
<para>
3170-
The catalog <structname>pg_foreign_table</structname> contains part
3171-
of the information about foreign tables.
3172-
The rest is mostly in <structname>pg_class</structname>.
3181+
The catalog <structname>pg_foreign_table</structname> contains
3182+
auxiliary information about foreign tables. A foreign table is
3183+
primarily represented by a <structname>pg_class</structname> entry,
3184+
just like a regular table. Its <structname>pg_foreign_table</structname>
3185+
entry contains the information that is pertinent only to foreign tables
3186+
and not any other kind of relation.
31733187
</para>
31743188

31753189
<table>
@@ -3190,22 +3204,22 @@
31903204
<entry><structfield>ftrelid</structfield></entry>
31913205
<entry><type>oid</type></entry>
31923206
<entry><literal><link linkend="catalog-pg-class"><structname>pg_class</structname></link>.oid</literal></entry>
3193-
<entry>The OID of the <structname>pg_class</> entry for this foreign table</entry>
3207+
<entry>OID of the <structname>pg_class</> entry for this foreign table</entry>
31943208
</row>
31953209

31963210
<row>
31973211
<entry><structfield>ftserver</structfield></entry>
31983212
<entry><type>oid</type></entry>
31993213
<entry><literal><link linkend="catalog-pg-foreign-server"><structname>pg_foreign_server</structname></link>.oid</literal></entry>
3200-
<entry>The OID of the foreign server for this foreign table</entry>
3214+
<entry>OID of the foreign server for this foreign table</entry>
32013215
</row>
32023216

32033217
<row>
32043218
<entry><structfield>ftoptions</structfield></entry>
32053219
<entry><type>text[]</type></entry>
32063220
<entry></entry>
32073221
<entry>
3208-
Foreign table options, as <quote>keyword=value</> strings.
3222+
Foreign table options, as <quote>keyword=value</> strings
32093223
</entry>
32103224
</row>
32113225
</tbody>

‎doc/src/sgml/datatype.sgml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4431,6 +4431,10 @@ SELECT * FROM pg_attribute
44314431
<primary>language_handler</primary>
44324432
</indexterm>
44334433

4434+
<indexterm zone="datatype-pseudo">
4435+
<primary>fdw_handler</primary>
4436+
</indexterm>
4437+
44344438
<indexterm zone="datatype-pseudo">
44354439
<primary>cstring</primary>
44364440
</indexterm>
@@ -4513,6 +4517,11 @@ SELECT * FROM pg_attribute
45134517
<entry>A procedural language call handler is declared to return <type>language_handler</>.</entry>
45144518
</row>
45154519

4520+
<row>
4521+
<entry><type>fdw_handler</></entry>
4522+
<entry>A foreign-data wrapper handler is declared to return <type>fdw_handler</>.</entry>
4523+
</row>
4524+
45164525
<row>
45174526
<entry><type>record</></entry>
45184527
<entry>Identifies a function returning an unspecified row type.</entry>

‎doc/src/sgml/ref/alter_foreign_data_wrapper.sgml‎

Lines changed: 31 additions & 8 deletions
< 3B0C tbody>
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,8 @@ PostgreSQL documentation
2222
<refsynopsisdiv>
2323
<synopsis>
2424
ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
25-
[ VALIDATOR <replaceable class="parameter">valfunction</replaceable> | NO VALIDATOR ]
25+
[ HANDLER <replaceable class="parameter">handler_function</replaceable> | NO HANDLER ]
26+
[ VALIDATOR <replaceable class="parameter">validator_function</replaceable> | NO VALIDATOR ]
2627
[ OPTIONS ( [ ADD | SET | DROP ] <replaceable class="PARAMETER">option</replaceable> ['<replaceable class="PARAMETER">value</replaceable>'] [, ... ]) ]
2728
ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> OWNER TO <replaceable>new_owner</replaceable>
2829
</synopsis>
@@ -34,7 +35,7 @@ ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> OWN
3435
<para>
3536
<command>ALTER FOREIGN DATA WRAPPER</command> changes the
3637
definition of a foreign-data wrapper. The first form of the
37-
command changes the library or the generic options of the
38+
command changes the support functions or the generic options of the
3839
foreign-data wrapper (at least one clause is required). The second
3940
form changes the owner of the foreign-data wrapper.
4041
</para>
@@ -59,10 +60,33 @@ ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> OWN
5960
</varlistentry>
6061

6162
<varlistentry>
62-
<term><literal>VALIDATOR <replaceable class="parameter">valfunction</replaceable></literal></term>
63+
<term><literal>HANDLER <replaceable class="parameter">handler_function</replaceable></literal></term>
6364
<listitem>
6465
<para>
65-
Specifies a new foreign-data wrapper validator function.
66+
Specifies a new handler function for the foreign-data wrapper.
67+
</para>
68+
</listitem>
69+
</varlistentry>
70+
71+
<varlistentry>
72+
<term><literal>NO HANDLER</literal></term>
73+
<listitem>
74+
<para>
75+
This is used to specify that the foreign-data wrapper should no
76+
longer have a handler function.
77+
</para>
78+
<para>
79+
Note that foreign tables that use a foreign-data wrapper with no
80+
handler cannot be accessed.
81+
</para>
82+
</listitem>
83+
</varlistentry>
84+
85+
<varlistentry>
86+
<term><literal>VALIDATOR <replaceable class="parameter">validator_fu 3B0C nction</replaceable></literal></term>
87+
<listitem>
88+
<para>
89+
Specifies a new validator function for the foreign-data wrapper.
6690
</para>
6791

6892
<para>
@@ -94,7 +118,7 @@ ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> OWN
94118
specify the action to be performed. <literal>ADD</> is assumed
95119
if no operation is explicitly specified. Option names must be
96120
unique; names and values are also validated using the foreign
97-
data wrapper library.
121+
data wrapper's validator function, if any.
98122
</para>
99123
</listitem>
100124
</varlistentry>
@@ -126,9 +150,8 @@ ALTER FOREIGN DATA WRAPPER dbi VALIDATOR bob.myvalidator;
126150

127151
<para>
128152
<command>ALTER FOREIGN DATA WRAPPER</command> conforms to ISO/IEC
129-
9075-9 (SQL/MED). The standard does not specify the <literal>
130-
VALIDATOR</literal> and <literal>OWNER TO</> variants of the
131-
command.
153+
9075-9 (SQL/MED), except that the <literal>HANDLER</literal>,
154+
<literal>VALIDATOR</> and <literal>OWNER TO</> clauses are extensions.
132155
</para>
133156
</refsect1>
134157

‎doc/src/sgml/ref/create_foreign_data_wrapper.sgml‎

Lines changed: 35 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,8 @@ PostgreSQL documentation
2222
<refsynopsisdiv>
2323
<synopsis>
2424
CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
25-
[ VALIDATOR <replaceable class="parameter">valfunction</replaceable> | NO VALIDATOR ]
25+
[ HANDLER <replaceable class="parameter">handler_function</replaceable> | NO HANDLER ]
26+
[ VALIDATOR <replaceable class="parameter">validator_function</replaceable> | NO VALIDATOR ]
2627
[ OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] ) ]
2728
</synopsis>
2829
</refsynopsisdiv>
@@ -59,13 +60,32 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
5960
</varlistentry>
6061

6162
<varlistentry>
62-
<term><literal>VALIDATOR <replaceable class="parameter">valfunction</replaceable></literal></term>
63+
<term><literal>HANDLER <replaceable class="parameter">handler_function</replaceable></literal></term>
6364
<listitem>
6465
<para>
65-
<replaceable class="parameter">valfunction</replaceable> is the
66+
<replaceable class="parameter">handler_function</replaceable> is the
67+
name of a previously registered function that will be called to
68+
retrieve the execution functions for foreign tables.
69+
The handler function must take no arguments, and
70+
its return type must be <type>fdw_handler</type>.
71+
</para>
72+
73+
<para>
74+
It is possible to create a foreign-data wrapper with no handler
75+
function, but foreign tables using such a wrapper can only be declared,
76+
not accessed.
77+
</para>
78+
</listitem>
79+
</varlistentry>
80+
81+
<varlistentry>
82+
<term><literal>VALIDATOR <replaceable class="parameter">validator_function</replaceable></literal></term>
83+
<listitem>
84+
<para>
85+
<replaceable class="parameter">validator_function</replaceable> is the
6686
name of a previously registered function that will be called to
6787
check the generic options given to the foreign-data wrapper, as
68-
well as to foreign servers and user mappings using the
88+
well as options for foreign servers and user mappings using the
6989
foreign-data wrapper. If no validator function or <literal>NO
7090
VALIDATOR</literal> is specified, then options will not be
7191
checked at creation time. (Foreign-data wrappers will possibly
@@ -75,8 +95,8 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
7595
contain the array of options as stored in the system catalogs,
7696
and one of type <type>oid</type>, which will be the OID of the
7797
system catalog containing the options. The return type is ignored;
78-
the function should indicate invalid options using the
79-
<function>ereport()</function> function.
98+
the function should report invalid options using the
99+
<function>ereport(ERROR)</function> function.
80100
</para>
81101
</listitem>
82102
</varlistentry>
@@ -87,8 +107,8 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
87107
<para>
88108
This clause specifies options for the new foreign-data wrapper.
89109
The allowed option names and values are specific to each foreign
90-
data wrapper and are validated using the foreign-data wrapper
91-
library. Option names must be unique.
110+
data wrapper and are validated using the foreign-data wrapper's
111+
validator function. Option names must be unique.
92112
</para>
93113
</listitem>
94114
</varlistentry>
@@ -122,17 +142,17 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
122142
<title>Examples</title>
123143

124144
<para>
125-
Create a foreign-data wrapper <literal>dummy</>:
145+
Create a useless foreign-data wrapper <literal>dummy</>:
126146
<programlisting>
127147
CREATE FOREIGN DATA WRAPPER dummy;
128148
</programlisting>
129149
</para>
130150

131151
<para>
132-
Create a foreign-data wrapper <literal>postgresql</> with
133-
validator function <literal>postgresql_fdw_validator</>:
152+
Create a foreign-data wrapper <literal>file</> with
153+
handler function <literal>file_fdw_handler</>:
134154
<programlisting>
135-
CREATE FOREIGN DATA WRAPPER postgresql VALIDATOR postgresql_fdw_validator;
155+
CREATE FOREIGN DATA WRAPPER file HANDLER file_fdw_handler;
136156
</programlisting>
137157
</para>
138158

@@ -151,10 +171,10 @@ CREATE FOREIGN DATA WRAPPER mywrapper
151171

152172
<para>
153173
<command>CREATE FOREIGN DATA WRAPPER</command> conforms to ISO/IEC
154-
9075-9 (SQL/MED), with the exception that
155-
the <literal>VALIDATOR</literal> clause is an extension and the
174+
9075-9 (SQL/MED), with the exception that the <literal>HANDLER</literal>
175+
and <literal>VALIDATOR</literal> clauses are extensions and the standard
156176
clauses <literal>LIBRARY</literal> and <literal>LANGUAGE</literal>
157-
are not yet implemented in PostgreSQL.
177+
are not implemented in PostgreSQL.
158178
</para>
159179

160180
<para>

0 commit comments

Comments
 (0)
0