← Back to branch summary

~ubuntu-branches/ubuntu/hardy/postgresql-8.4/hardy-backports

« back to all changes in this revision

Viewing changes to doc/src/sgml/ref/create_foreign_data_wrapper.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2009-03-20 12:00:13 UTC
  • Revision ID: james.westby@ubuntu.com-20090320120013-hogj7egc5mjncc5g
Tags: upstream-8.4~0cvs20090328
Import upstream version 8.4~0cvs20090328

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/ref/create_foreign_data_wrapper.sgml
 
1
<!--
 
2
$PostgreSQL$
 
3
PostgreSQL documentation
 
4
-->
 
5
 
 
6
<refentry id="SQL-CREATEFOREIGNDATAWRAPPER">
 
7
 <refmeta>
 
8
  <refentrytitle id="sql-createforeigndatawrapper-title">CREATE FOREIGN DATA WRAPPER</refentrytitle>
 
9
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 
10
 </refmeta>
 
11
 
 
12
 <refnamediv>
 
13
  <refname>CREATE FOREIGN DATA WRAPPER</refname>
 
14
  <refpurpose>define a new foreign-data wrapper</refpurpose>
 
15
 </refnamediv>
 
16
 
 
17
 <indexterm zone="sql-createforeigndatawrapper">
 
18
  <primary>CREATE FOREIGN DATA WRAPPER</primary>
 
19
 </indexterm>
 
20
 
 
21
 <refsynopsisdiv>
 
22
<synopsis>
 
23
CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable>
 
24
    [ VALIDATOR <replaceable class="parameter">valfunction</replaceable> | NO VALIDATOR ]
 
25
    [ OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] ) ]
 
26
</synopsis>
 
27
 </refsynopsisdiv>
 
28
 
 
29
 <refsect1>
 
30
  <title>Description</title>
 
31
 
 
32
  <para>
 
33
   <command>CREATE FOREIGN DATA WRAPPER</command> creates a new
 
34
   foreign-data wrapper.  The user who defines a foreign-data wrapper
 
35
   becomes its owner.
 
36
  </para>
 
37
 
 
38
  <para>
 
39
   The foreign-data wrapper name must be unique within the database.
 
40
  </para>
 
41
 
 
42
  <para>
 
43
   Only superusers can create foreign-data wrappers.
 
44
  </para>
 
45
 </refsect1>
 
46
 
 
47
 <refsect1>
 
48
  <title>Parameters</title>
 
49
 
 
50
  <variablelist>
 
51
   <varlistentry>
 
52
    <term><replaceable class="parameter">name</replaceable></term>
 
53
    <listitem>
 
54
     <para>
 
55
      The name of the foreign-data wrapper to be created.
 
56
     </para>
 
57
    </listitem>
 
58
   </varlistentry>
 
59
 
 
60
   <varlistentry>
 
61
    <term><literal>VALIDATOR <replaceable class="parameter">valfunction</replaceable></literal></term>
 
62
    <listitem>
 
63
     <para>
 
64
      <replaceable class="parameter">valfunction</replaceable> is the
 
65
      name of a previously registered function that will be called to
 
66
      check the generic options given to the foreign-data wrapper, as
 
67
      well as to foreign servers and user mappings using the
 
68
      foreign-data wrapper.  If no validator function or <literal>NO
 
69
      VALIDATOR</literal> is specified, then options will not be
 
70
      checked at creation time.  (Foreign-data wrappers will possibly
 
71
      ignore or reject invalid option specifications at run time,
 
72
      depending on the implementation.)  The validator function must
 
73
      take two arguments: one of type <type>text[]</type>, which will
 
74
      contain the array of options as stored in the system catalogs,
 
75
      and one of type <type>oid</type>, which will be the OID of the
 
76
      system catalog containing the options, or zero if the context is
 
77
      not known.  The return type is ignored; the function should
 
78
      indicate invalid options using
 
79
      the <function>ereport()</function> function.
 
80
     </para>
 
81
    </listitem>
 
82
   </varlistentry>
 
83
 
 
84
   <varlistentry>
 
85
    <term><literal>OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] )</literal></term>
 
86
    <listitem>
 
87
     <para>
 
88
      This clause specifies options for the new foreign-data wrapper.
 
89
      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.
 
92
     </para>
 
93
    </listitem>
 
94
   </varlistentry>
 
95
  </variablelist>
 
96
 </refsect1>
 
97
 
 
98
 <refsect1>
 
99
  <title>Notes</title>
 
100
 
 
101
  <para>
 
102
   At the moment, the foreign-data wrapper functionality is very
 
103
   rudimentary.  The purpose of foreign-data wrappers, foreign
 
104
   servers, and user mappings is to store this information in a
 
105
   standard way so that it can be queried by interested applications.
 
106
   The functionality to actually query external data does not exist
 
107
   yet.
 
108
  </para>
 
109
 
 
110
  <para>
 
111
   There is currently one foreign-data wrapper validator function
 
112
   provided:
 
113
   <filename>postgresql_fdw_validator</filename>, which accepts
 
114
   options corresponding to <application>libpq</> connection
 
115
   parameters.
 
116
  </para>
 
117
 </refsect1>
 
118
 
 
119
 <refsect1>
 
120
  <title>Examples</title>
 
121
 
 
122
  <para>
 
123
   Create a foreign-data wrapper <literal>dummy</>:
 
124
<programlisting>
 
125
CREATE FOREIGN DATA WRAPPER dummy;
 
126
</programlisting>
 
127
  </para>
 
128
 
 
129
  <para>
 
130
   Create a foreign-data wrapper <literal>postgresql</> with
 
131
   validator function <literal>postgresql_fdw_validator</>:
 
132
<programlisting>
 
133
CREATE FOREIGN DATA WRAPPER postgresql VALIDATOR postgresql_fdw_validator;
 
134
</programlisting>
 
135
  </para>
 
136
 
 
137
  <para>
 
138
   Create a foreign-data wrapper <literal>mywrapper</> with some
 
139
   options:
 
140
<programlisting>
 
141
CREATE FOREIGN DATA WRAPPER mywrapper
 
142
    OPTIONS (debug 'true');
 
143
</programlisting>
 
144
  </para>
 
145
 </refsect1>
 
146
 
 
147
 <refsect1>
 
148
  <title>Compatibility</title>
 
149
 
 
150
  <para>
 
151
   <command>CREATE FOREIGN DATA WRAPPER</command> conforms to ISO/IEC
 
152
   9075-9 (SQL/MED), with the exception that
 
153
   the <literal>VALIDATOR</literal> clause is an extension and the
 
154
   clauses <literal>LIBRARY</literal> and <literal>LANGUAGE</literal>
 
155
   are not yet implemented in PostgreSQL.
 
156
  </para>
 
157
 
 
158
  <para>
 
159
   Note, however, that the SQL/MED functionality as a whole is not yet
 
160
   conforming.
 
161
  </para>
 
162
 </refsect1>
 
163
 
 
164
 <refsect1>
 
165
  <title>See Also</title>
 
166
 
 
167
  <simplelist type="inline">
 
168
   <member><xref linkend="sql-alterforeigndatawrapper" endterm="sql-alterforeigndatawrapper-title"></member>
 
169
   <member><xref linkend="sql-dropforeigndatawrapper" endterm="sql-dropforeigndatawrapper-title"></member>
 
170
   <member><xref linkend="sql-createserver" endterm="sql-createserver-title"></member>
 
171
   <member><xref linkend="sql-createusermapping" endterm="sql-createusermapping-title"></member>
 
172
  </simplelist>
 
173
 </refsect1>
 
174
 
 
175
</refentry>