begriffs open source - ai-pg/blob - full-docs/txt/sql-createforeigndatawrapper.txt

   1
   2 CREATE FOREIGN DATA WRAPPER
   3
   4    CREATE FOREIGN DATA WRAPPER — define a new foreign-data wrapper
   5
   6 Synopsis
   7
   8 CREATE FOREIGN DATA WRAPPER name
   9     [ HANDLER handler_function | NO HANDLER ]
  10     [ VALIDATOR validator_function | NO VALIDATOR ]
  11     [ OPTIONS ( option 'value' [, ... ] ) ]
  12
  13 Description
  14
  15    CREATE FOREIGN DATA WRAPPER creates a new foreign-data wrapper. The
  16    user who defines a foreign-data wrapper becomes its owner.
  17
  18    The foreign-data wrapper name must be unique within the database.
  19
  20    Only superusers can create foreign-data wrappers.
  21
  22 Parameters
  23
  24    name
  25           The name of the foreign-data wrapper to be created.
  26
  27    HANDLER handler_function
  28           handler_function is the name of a previously registered function
  29           that will be called to retrieve the execution functions for
  30           foreign tables. The handler function must take no arguments, and
  31           its return type must be fdw_handler.
  32
  33           It is possible to create a foreign-data wrapper with no handler
  34           function, but foreign tables using such a wrapper can only be
  35           declared, not accessed.
  36
  37    VALIDATOR validator_function
  38           validator_function is the name of a previously registered
  39           function that will be called to check the generic options given
  40           to the foreign-data wrapper, as well as options for foreign
  41           servers, user mappings and foreign tables using the foreign-data
  42           wrapper. If no validator function or NO VALIDATOR is specified,
  43           then options will not be checked at creation time. (Foreign-data
  44           wrappers will possibly ignore or reject invalid option
  45           specifications at run time, depending on the implementation.)
  46           The validator function must take two arguments: one of type
  47           text[], which will contain the array of options as stored in the
  48           system catalogs, and one of type oid, which will be the OID of
  49           the system catalog containing the options. The return type is
  50           ignored; the function should report invalid options using the
  51           ereport(ERROR) function.
  52
  53    OPTIONS ( option 'value' [, ... ] )
  54           This clause specifies options for the new foreign-data wrapper.
  55           The allowed option names and values are specific to each foreign
  56           data wrapper and are validated using the foreign-data wrapper's
  57           validator function. Option names must be unique.
  58
  59 Notes
  60
  61    PostgreSQL's foreign-data functionality is still under active
  62    development. Optimization of queries is primitive (and mostly left to
  63    the wrapper, too). Thus, there is considerable room for future
  64    performance improvements.
  65
  66 Examples
  67
  68    Create a useless foreign-data wrapper dummy:
  69 CREATE FOREIGN DATA WRAPPER dummy;
  70
  71    Create a foreign-data wrapper file with handler function
  72    file_fdw_handler:
  73 CREATE FOREIGN DATA WRAPPER file HANDLER file_fdw_handler;
  74
  75    Create a foreign-data wrapper mywrapper with some options:
  76 CREATE FOREIGN DATA WRAPPER mywrapper
  77     OPTIONS (debug 'true');
  78
  79 Compatibility
  80
  81    CREATE FOREIGN DATA WRAPPER conforms to ISO/IEC 9075-9 (SQL/MED), with
  82    the exception that the HANDLER and VALIDATOR clauses are extensions and
  83    the standard clauses LIBRARY and LANGUAGE are not implemented in
  84    PostgreSQL.
  85
  86    Note, however, that the SQL/MED functionality as a whole is not yet
  87    conforming.
  88
  89 See Also
  90
  91    ALTER FOREIGN DATA WRAPPER, DROP FOREIGN DATA WRAPPER, CREATE SERVER,
  92    CREATE USER MAPPING, CREATE FOREIGN TABLE