begriffs open source - ai-pg/blob - full-docs/man7/CREATE_FOREIGN_DATA_WRAPPER.7

   1 '\" t
   2 .\"     Title: CREATE FOREIGN DATA WRAPPER
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "CREATE FOREIGN DATA WRAPPER" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 CREATE_FOREIGN_DATA_WRAPPER \- define a new foreign\-data wrapper
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 CREATE FOREIGN DATA WRAPPER \fIname\fR
  36     [ HANDLER \fIhandler_function\fR | NO HANDLER ]
  37     [ VALIDATOR \fIvalidator_function\fR | NO VALIDATOR ]
  38     [ OPTIONS ( \fIoption\fR \*(Aq\fIvalue\fR\*(Aq [, \&.\&.\&. ] ) ]
  39 .fi
  40 .SH "DESCRIPTION"
  41 .PP
  42 \fBCREATE FOREIGN DATA WRAPPER\fR
  43 creates a new foreign\-data wrapper\&. The user who defines a foreign\-data wrapper becomes its owner\&.
  44 .PP
  45 The foreign\-data wrapper name must be unique within the database\&.
  46 .PP
  47 Only superusers can create foreign\-data wrappers\&.
  48 .SH "PARAMETERS"
  49 .PP
  50 \fIname\fR
  51 .RS 4
  52 The name of the foreign\-data wrapper to be created\&.
  53 .RE
  54 .PP
  55 HANDLER \fIhandler_function\fR
  56 .RS 4
  57 \fIhandler_function\fR
  58 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
  59 fdw_handler\&.
  60 .sp
  61 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\&.
  62 .RE
  63 .PP
  64 VALIDATOR \fIvalidator_function\fR
  65 .RS 4
  66 \fIvalidator_function\fR
  67 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 options for foreign servers, user mappings and foreign tables using the foreign\-data wrapper\&. If no validator function or
  68 NO VALIDATOR
  69 is specified, then options will not be checked at creation time\&. (Foreign\-data wrappers will possibly ignore or reject invalid option specifications at run time, depending on the implementation\&.) The validator function must take two arguments: one of type
  70 text[], which will contain the array of options as stored in the system catalogs, and one of type
  71 oid, which will be the OID of the system catalog containing the options\&. The return type is ignored; the function should report invalid options using the
  72 \fBereport(ERROR)\fR
  73 function\&.
  74 .RE
  75 .PP
  76 OPTIONS ( \fIoption\fR \*(Aq\fIvalue\fR\*(Aq [, \&.\&.\&. ] )
  77 .RS 4
  78 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\*(Aqs validator function\&. Option names must be unique\&.
  79 .RE
  80 .SH "NOTES"
  81 .PP
  82 PostgreSQL\*(Aqs foreign\-data functionality is still under active development\&. Optimization of queries is primitive (and mostly left to the wrapper, too)\&. Thus, there is considerable room for future performance improvements\&.
  83 .SH "EXAMPLES"
  84 .PP
  85 Create a useless foreign\-data wrapper
  86 dummy:
  87 .sp
  88 .if n \{\
  89 .RS 4
  90 .\}
  91 .nf
  92 CREATE FOREIGN DATA WRAPPER dummy;
  93 .fi
  94 .if n \{\
  95 .RE
  96 .\}
  97 .PP
  98 Create a foreign\-data wrapper
  99 file
 100 with handler function
 101 file_fdw_handler:
 102 .sp
 103 .if n \{\
 104 .RS 4
 105 .\}
 106 .nf
 107 CREATE FOREIGN DATA WRAPPER file HANDLER file_fdw_handler;
 108 .fi
 109 .if n \{\
 110 .RE
 111 .\}
 112 .PP
 113 Create a foreign\-data wrapper
 114 mywrapper
 115 with some options:
 116 .sp
 117 .if n \{\
 118 .RS 4
 119 .\}
 120 .nf
 121 CREATE FOREIGN DATA WRAPPER mywrapper
 122     OPTIONS (debug \*(Aqtrue\*(Aq);
 123 .fi
 124 .if n \{\
 125 .RE
 126 .\}
 127 .SH "COMPATIBILITY"
 128 .PP
 129 \fBCREATE FOREIGN DATA WRAPPER\fR
 130 conforms to ISO/IEC 9075\-9 (SQL/MED), with the exception that the
 131 HANDLER
 132 and
 133 VALIDATOR
 134 clauses are extensions and the standard clauses
 135 LIBRARY
 136 and
 137 LANGUAGE
 138 are not implemented in
 139 PostgreSQL\&.
 140 .PP
 141 Note, however, that the SQL/MED functionality as a whole is not yet conforming\&.
 142 .SH "SEE ALSO"
 143 ALTER FOREIGN DATA WRAPPER (\fBALTER_FOREIGN_DATA_WRAPPER\fR(7)), DROP FOREIGN DATA WRAPPER (\fBDROP_FOREIGN_DATA_WRAPPER\fR(7)), CREATE SERVER (\fBCREATE_SERVER\fR(7)), CREATE USER MAPPING (\fBCREATE_USER_MAPPING\fR(7)), CREATE FOREIGN TABLE (\fBCREATE_FOREIGN_TABLE\fR(7))