aboutsummaryrefslogtreecommitdiff
path: root/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/sgml/catalogs.sgml38
-rw-r--r--doc/src/sgml/datatype.sgml9
-rw-r--r--doc/src/sgml/ref/alter_foreign_data_wrapper.sgml39
-rw-r--r--doc/src/sgml/ref/create_foreign_data_wrapper.sgml50
4 files changed, 101 insertions, 35 deletions
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index 30f39806970..88eaca0bea0 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -3032,15 +3032,26 @@
</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>
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 253b7578985..b8f6e238f0b 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -4432,6 +4432,10 @@ SELECT * FROM pg_attribute
</indexterm>
<indexterm zone="datatype-pseudo">
+ <primary>fdw_handler</primary>
+ </indexterm>
+
+ <indexterm zone="datatype-pseudo">
<primary>cstring</primary>
</indexterm>
@@ -4514,6 +4518,11 @@ SELECT * FROM pg_attribute
</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>
</row>
diff --git a/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml b/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml
index 4e9e8a2e28a..af56ed7561d 100644
--- a/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml
+++ b/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml
@@ -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>
diff --git a/doc/src/sgml/ref/create_foreign_data_wrapper.sgml b/doc/src/sgml/ref/create_foreign_data_wrapper.sgml
index f626d56665b..711f32b118b 100644
--- a/doc/src/sgml/ref/create_foreign_data_wrapper.sgml
+++ b/doc/src/sgml/ref/create_foreign_data_wrapper.sgml
@@ -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>
generated by cgit v1.2.3 (git 2.25.1) at 2025-07-08 00:21:37 +0000