← Back to branch summary

~ubuntu-branches/ubuntu/precise/postgresql-9.1/precise-security

« back to all changes in this revision

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

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/ref/create_foreign_table.sgml
 
1
<!-- doc/src/sgml/ref/create_foreign_table.sgml -->
 
2
 
 
3
<refentry id="SQL-CREATEFOREIGNTABLE">
 
4
 <refmeta>
 
5
  <refentrytitle>CREATE FOREIGN TABLE</refentrytitle>
 
6
  <manvolnum>7</manvolnum>
 
7
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 
8
 </refmeta>
 
9
 
 
10
 <refnamediv>
 
11
  <refname>CREATE FOREIGN TABLE</refname>
 
12
  <refpurpose>define a new foreign table</refpurpose>
 
13
 </refnamediv>
 
14
 
 
15
 <indexterm zone="sql-createforeigntable">
 
16
  <primary>CREATE FOREIGN TABLE</primary>
 
17
 </indexterm>
 
18
 
 
19
 <refsynopsisdiv>
 
20
<synopsis>
 
21
CREATE FOREIGN TABLE [ IF NOT EXISTS ] <replaceable class="PARAMETER">table_name</replaceable> ( [
 
22
  { <replaceable class="PARAMETER">column_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [ NULL | NOT NULL ] }
 
23
    [, ... ]
 
24
] )
 
25
  SERVER <replaceable class="parameter">server_name</replaceable>
 
26
[ OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] ) ]
 
27
 
 
28
</synopsis>
 
29
 </refsynopsisdiv>
 
30
 
 
31
 <refsect1 id="SQL-CREATEFOREIGNTABLE-description">
 
32
  <title>Description</title>
 
33
 
 
34
  <para>
 
35
   <command>CREATE FOREIGN TABLE</command> will create a new foreign table
 
36
   in the current database. The table will be owned by the user issuing the
 
37
   command.
 
38
  </para>
 
39
 
 
40
  <para>
 
41
   If a schema name is given (for example, <literal>CREATE FOREIGN TABLE
 
42
   myschema.mytable ...</>) then the table is created in the specified
 
43
   schema.  Otherwise it is created in the current schema.
 
44
   The name of the foreign table must be
 
45
   distinct from the name of any other foreign table, table, sequence, index,
 
46
   or view in the same schema.
 
47
  </para>
 
48
 
 
49
  <para>
 
50
   <command>CREATE FOREIGN TABLE</command> also automatically creates a data
 
51
   type that represents the composite type corresponding to one row of
 
52
   the foreign table.  Therefore, foreign tables cannot have the same
 
53
   name as any existing data type in the same schema.
 
54
  </para>
 
55
 </refsect1>
 
56
 
 
57
 <refsect1>
 
58
  <title>Parameters</title>
 
59
 
 
60
  <variablelist>
 
61
 
 
62
   <varlistentry>
 
63
    <term><literal>IF NOT EXISTS</></term>
 
64
    <listitem>
 
65
     <para>
 
66
      Do not throw an error if a relation with the same name already exists.
 
67
      A notice is issued in this case.  Note that there is no guarantee that
 
68
      the existing relation is anything like the one that would have been
 
69
      created.
 
70
     </para>
 
71
    </listitem>
 
72
   </varlistentry>
 
73
 
 
74
   <varlistentry>
 
75
    <term><replaceable class="PARAMETER">table_name</replaceable></term>
 
76
    <listitem>
 
77
     <para>
 
78
      The name (optionally schema-qualified) of the table to be created.
 
79
     </para>
 
80
    </listitem>
 
81
   </varlistentry>
 
82
 
 
83
   <varlistentry>
 
84
    <term><replaceable class="PARAMETER">column_name</replaceable></term>
 
85
    <listitem>
 
86
     <para>
 
87
      The name of a column to be created in the new table.
 
88
     </para>
 
89
    </listitem>
 
90
   </varlistentry>
 
91
 
 
92
   <varlistentry>
 
93
    <term><replaceable class="PARAMETER">data_type</replaceable></term>
 
94
    <listitem>
 
95
     <para>
 
96
      The data type of the column. This can include array
 
97
      specifiers. For more information on the data types supported by
 
98
      <productname>PostgreSQL</productname>, refer to <xref
 
99
      linkend="datatype">.
 
100
     </para>
 
101
    </listitem>
 
102
   </varlistentry>
 
103
 
 
104
   <varlistentry>
 
105
    <term><literal>NOT NULL</></term>
 
106
    <listitem>
 
107
     <para>
 
108
      The column is not allowed to contain null values.
 
109
     </para>
 
110
    </listitem>
 
111
   </varlistentry>
 
112
 
 
113
   <varlistentry>
 
114
    <term><literal>NULL</></term>
 
115
    <listitem>
 
116
     <para>
 
117
      The column is allowed to contain null values. This is the default.
 
118
     </para>
 
119
 
 
120
     <para>
 
121
      This clause is only provided for compatibility with
 
122
      non-standard SQL databases.  Its use is discouraged in new
 
123
      applications.
 
124
     </para>
 
125
    </listitem>
 
126
   </varlistentry>
 
127
 
 
128
   <varlistentry>
 
129
    <term><replaceable class="PARAMETER">server_name</replaceable></term>
 
130
    <listitem>
 
131
     <para>
 
132
      The name of an existing server for the foreign table.
 
133
     </para>
 
134
    </listitem>
 
135
   </varlistentry>
 
136
 
 
137
   <varlistentry>
 
138
    <term><literal>OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ...] )</literal></term>
 
139
    <listitem>
 
140
     <para>
 
141
      Options to be associated with the new foreign table.
 
142
      The allowed option names and values are specific to each foreign
 
143
      data wrapper and are validated using the foreign-data wrapper's
 
144
      validator function. Option names must be unique.
 
145
     </para>
 
146
    </listitem>
 
147
   </varlistentry>
 
148
 
 
149
  </variablelist>
 
150
 
 
151
 </refsect1>
 
152
 
 
153
 
 
154
 <refsect1 id="SQL-CREATEFOREIGNTABLE-examples">
 
155
  <title>Examples</title>
 
156
 
 
157
  <para>
 
158
   Create foreign table <structname>films</> with <structname>film_server</>:
 
159
 
 
160
<programlisting>
 
161
CREATE FOREIGN TABLE films (
 
162
    code        char(5) NOT NULL,
 
163
    title       varchar(40) NOT NULL,
 
164
    did         integer NOT NULL,
 
165
    date_prod   date,
 
166
    kind        varchar(10),
 
167
    len         interval hour to minute
 
168
)
 
169
SERVER film_server;
 
170
</programlisting>
 
171
  </para>
 
172
 
 
173
 </refsect1>
 
174
 
 
175
 <refsect1 id="SQL-CREATEFOREIGNTABLE-compatibility">
 
176
  <title id="SQL-CREATEFOREIGNTABLE-compatibility-title">Compatibility</title>
 
177
 
 
178
  <para>
 
179
   The <command>CREATE FOREIGN TABLE</command> command largely conforms to the
 
180
   <acronym>SQL</acronym> standard; however, much as with
 
181
   <link linkend="sql-createtable"><command>CREATE TABLE</></link>,
 
182
   <literal>NULL</> constraints and zero-column foreign tables are permitted.
 
183
  </para>
 
184
 
 
185
 </refsect1>
 
186
 
 
187
 <refsect1>
 
188
  <title>See Also</title>
 
189
 
 
190
  <simplelist type="inline">
 
191
   <member><xref linkend="sql-alterforeigntable"></member>
 
192
   <member><xref linkend="sql-dropforeigntable"></member>
 
193
   <member><xref linkend="sql-createtable"></member>
 
194
   <member><xref linkend="sql-createserver"></member>
 
195
  </simplelist>
 
196
 </refsect1>
 
197
</refentry>