From 327e0250716f12fe94b62669d25e572b40a8fba5 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sat, 19 Feb 2011 00:06:18 -0500 Subject: 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 --- doc/src/sgml/catalogs.sgml | 38 +++++++++++------ doc/src/sgml/datatype.sgml | 9 ++++ doc/src/sgml/ref/alter_foreign_data_wrapper.sgml | 39 ++++++++++++++---- doc/src/sgml/ref/create_foreign_data_wrapper.sgml | 50 ++++++++++++++++------- 4 files changed, 101 insertions(+), 35 deletions(-) (limited to 'doc/src') 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 @@ -3031,16 +3031,27 @@ Owner of the foreign-data wrapper + + fdwhandler + oid + pg_proc.oid + + References a handler function that is responsible for + supplying execution routines for the foreign-data wrapper. + Zero if no handler is provided + + + fdwvalidator oid pg_proc.oid 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 @@ -3079,8 +3090,8 @@ The catalog pg_foreign_server 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. @@ -3116,7 +3127,7 @@ srvfdw oid pg_foreign_data_wrapper.oid - The OID of the foreign-data wrapper of this foreign server + OID of the foreign-data wrapper of this foreign server @@ -3167,9 +3178,12 @@ - The catalog pg_foreign_table contains part - of the information about foreign tables. - The rest is mostly in pg_class. + The catalog pg_foreign_table contains + auxiliary information about foreign tables. A foreign table is + primarily represented by a pg_class entry, + just like a regular table. Its pg_foreign_table + entry contains the information that is pertinent only to foreign tables + and not any other kind of relation. @@ -3190,14 +3204,14 @@ ftrelidoidpg_class.oid - The OID of the pg_class entry for this foreign table + OID of the pg_class entry for this foreign table ftserver oid pg_foreign_server.oid - The OID of the foreign server for this foreign table + OID of the foreign server for this foreign table @@ -3205,7 +3219,7 @@ text[] - Foreign table options, as keyword=value strings. + Foreign table options, as keyword=value strings 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 @@ -4431,6 +4431,10 @@ SELECT * FROM pg_attribute language_handler + + fdw_handler + + cstring @@ -4513,6 +4517,11 @@ SELECT * FROM pg_attribute A procedural language call handler is declared to return language_handler. + + fdw_handler + A foreign-data wrapper handler is declared to return fdw_handler. + + record Identifies a function returning an unspecified row type. 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 ALTER FOREIGN DATA WRAPPER name - [ VALIDATOR valfunction | NO VALIDATOR ] + [ HANDLER handler_function | NO HANDLER ] + [ VALIDATOR validator_function | NO VALIDATOR ] [ OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ]) ] ALTER FOREIGN DATA WRAPPER name OWNER TO new_owner @@ -34,7 +35,7 @@ ALTER FOREIGN DATA WRAPPER name OWN ALTER FOREIGN DATA WRAPPER 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. @@ -59,10 +60,33 @@ ALTER FOREIGN DATA WRAPPER name OWN - VALIDATOR valfunction + HANDLER handler_function - Specifies a new foreign-data wrapper validator function. + Specifies a new handler function for the foreign-data wrapper. + + + + + + NO HANDLER + + + This is used to specify that the foreign-data wrapper should no + longer have a handler function. + + + Note that foreign tables that use a foreign-data wrapper with no + handler cannot be accessed. + + + + + + VALIDATOR validator_function + + + Specifies a new validator function for the foreign-data wrapper. @@ -94,7 +118,7 @@ ALTER FOREIGN DATA WRAPPER name OWN specify the action to be performed. 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. @@ -126,9 +150,8 @@ ALTER FOREIGN DATA WRAPPER dbi VALIDATOR bob.myvalidator; ALTER FOREIGN DATA WRAPPER conforms to ISO/IEC - 9075-9 (SQL/MED). The standard does not specify the - VALIDATOR and OWNER TO variants of the - command. + 9075-9 (SQL/MED), except that the HANDLER, + VALIDATOR and OWNER TO clauses are extensions. 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 CREATE FOREIGN DATA WRAPPER name - [ VALIDATOR valfunction | NO VALIDATOR ] + [ HANDLER handler_function | NO HANDLER ] + [ VALIDATOR validator_function | NO VALIDATOR ] [ OPTIONS ( option 'value' [, ... ] ) ] @@ -59,13 +60,32 @@ CREATE FOREIGN DATA WRAPPER name - VALIDATOR valfunction + HANDLER handler_function - valfunction is the + handler_function 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 fdw_handler. + + + + 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. + + + + + + VALIDATOR validator_function + + + validator_function 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 NO VALIDATOR is specified, then options will not be checked at creation time. (Foreign-data wrappers will possibly @@ -75,8 +95,8 @@ CREATE FOREIGN DATA WRAPPER name contain the array of options as stored in the system catalogs, and one of type oid, 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 - ereport() function. + the function should report invalid options using the + ereport(ERROR) function. @@ -87,8 +107,8 @@ CREATE FOREIGN DATA WRAPPER name 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. @@ -122,17 +142,17 @@ CREATE FOREIGN DATA WRAPPER name Examples - Create a foreign-data wrapper dummy: + Create a useless foreign-data wrapper dummy: CREATE FOREIGN DATA WRAPPER dummy; - Create a foreign-data wrapper postgresql with - validator function postgresql_fdw_validator: + Create a foreign-data wrapper file with + handler function file_fdw_handler: -CREATE FOREIGN DATA WRAPPER postgresql VALIDATOR postgresql_fdw_validator; +CREATE FOREIGN DATA WRAPPER file HANDLER file_fdw_handler; @@ -151,10 +171,10 @@ CREATE FOREIGN DATA WRAPPER mywrapper CREATE FOREIGN DATA WRAPPER conforms to ISO/IEC - 9075-9 (SQL/MED), with the exception that - the VALIDATOR clause is an extension and the + 9075-9 (SQL/MED), with the exception that the HANDLER + and VALIDATOR clauses are extensions and the standard clauses LIBRARY and LANGUAGE - are not yet implemented in PostgreSQL. + are not implemented in PostgreSQL. -- cgit v1.2.3