begriffs open source - ai-pg/blob - full-docs/html/sql-createforeigntable.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE FOREIGN TABLE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER" /><link rel="next" href="sql-createfunction.html" title="CREATE FUNCTION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE FOREIGN TABLE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createfunction.html" title="CREATE FUNCTION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEFOREIGNTABLE"><div class="titlepage"></div><a id="id-1.9.3.66.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE FOREIGN TABLE</span></h2><p>CREATE FOREIGN TABLE — define a new foreign table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
   3 CREATE FOREIGN TABLE [ IF NOT EXISTS ] <em class="replaceable"><code>table_name</code></em> ( [
   4   { <em class="replaceable"><code>column_name</code></em> <em class="replaceable"><code>data_type</code></em> [ OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [, ... ] ) ] [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ <em class="replaceable"><code>column_constraint</code></em> [ ... ] ]
   5     | <em class="replaceable"><code>table_constraint</code></em>
   6     | LIKE <em class="replaceable"><code>source_table</code></em> [ <em class="replaceable"><code>like_option</code></em> ... ] }
   7     [, ... ]
   8 ] )
   9 [ INHERITS ( <em class="replaceable"><code>parent_table</code></em> [, ... ] ) ]
  10   SERVER <em class="replaceable"><code>server_name</code></em>
  11 [ OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [, ... ] ) ]
  12
  13 CREATE FOREIGN TABLE [ IF NOT EXISTS ] <em class="replaceable"><code>table_name</code></em>
  14   PARTITION OF <em class="replaceable"><code>parent_table</code></em> [ (
  15   { <em class="replaceable"><code>column_name</code></em> [ WITH OPTIONS ] [ <em class="replaceable"><code>column_constraint</code></em> [ ... ] ]
  16     | <em class="replaceable"><code>table_constraint</code></em> }
  17     [, ... ]
  18 ) ]
  19 { FOR VALUES <em class="replaceable"><code>partition_bound_spec</code></em> | DEFAULT }
  20   SERVER <em class="replaceable"><code>server_name</code></em>
  21 [ OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [, ... ] ) ]
  22
  23 <span class="phrase">where <em class="replaceable"><code>column_constraint</code></em> is:</span>
  24
  25 [ CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> ]
  26 { NOT NULL [ NO INHERIT ] |
  27   NULL |
  28   CHECK ( <em class="replaceable"><code>expression</code></em> ) [ NO INHERIT ] |
  29   DEFAULT <em class="replaceable"><code>default_expr</code></em> |
  30   GENERATED ALWAYS AS ( <em class="replaceable"><code>generation_expr</code></em> ) [ STORED | VIRTUAL ] }
  31 [ ENFORCED | NOT ENFORCED ]
  32
  33 <span class="phrase">and <em class="replaceable"><code>table_constraint</code></em> is:</span>
  34
  35 [ CONSTRAINT <em class="replaceable"><code>constraint_name</code></em> ]
  36 {  NOT NULL <em class="replaceable"><code>column_name</code></em> [ NO INHERIT ] |
  37    CHECK ( <em class="replaceable"><code>expression</code></em> ) [ NO INHERIT ] }
  38 [ ENFORCED | NOT ENFORCED ]
  39
  40 <span class="phrase">and <em class="replaceable"><code>like_option</code></em> is:</span>
  41
  42 { INCLUDING | EXCLUDING } { COMMENTS | CONSTRAINTS | DEFAULTS | GENERATED | STATISTICS | ALL }
  43
  44 <span class="phrase">and <em class="replaceable"><code>partition_bound_spec</code></em> is:</span>
  45
  46 IN ( <em class="replaceable"><code>partition_bound_expr</code></em> [, ...] ) |
  47 FROM ( { <em class="replaceable"><code>partition_bound_expr</code></em> | MINVALUE | MAXVALUE } [, ...] )
  48   TO ( { <em class="replaceable"><code>partition_bound_expr</code></em> | MINVALUE | MAXVALUE } [, ...] ) |
  49 WITH ( MODULUS <em class="replaceable"><code>numeric_literal</code></em>, REMAINDER <em class="replaceable"><code>numeric_literal</code></em> )
  50 </pre></div><div class="refsect1" id="SQL-CREATEFOREIGNTABLE-DESCRIPTION"><h2>Description</h2><p>
  51    <code class="command">CREATE FOREIGN TABLE</code> creates a new foreign table
  52    in the current database. The table will be owned by the user issuing the
  53    command.
  54   </p><p>
  55    If a schema name is given (for example, <code class="literal">CREATE FOREIGN TABLE
  56    myschema.mytable ...</code>) then the table is created in the specified
  57    schema.  Otherwise it is created in the current schema.
  58    The name of the foreign table must be
  59    distinct from the name of any other relation (table, sequence, index, view,
  60    materialized view, or foreign table) in the same schema.
  61   </p><p>
  62    <code class="command">CREATE FOREIGN TABLE</code> also automatically creates a data
  63    type that represents the composite type corresponding to one row of
  64    the foreign table.  Therefore, foreign tables cannot have the same
  65    name as any existing data type in the same schema.
  66   </p><p>
  67    If <code class="literal">PARTITION OF</code> clause is specified then the table is
  68    created as a partition of <code class="literal">parent_table</code> with specified
  69    bounds.
  70   </p><p>
  71    To be able to create a foreign table, you must have <code class="literal">USAGE</code>
  72    privilege on the foreign server, as well as <code class="literal">USAGE</code>
  73    privilege on all column types used in the table.
  74   </p></div><div class="refsect1" id="id-1.9.3.66.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF NOT EXISTS</code></span></dt><dd><p>
  75       Do not throw an error if a relation with the same name already exists.
  76       A notice is issued in this case.  Note that there is no guarantee that
  77       the existing relation is anything like the one that would have been
  78       created.
  79      </p></dd><dt><span class="term"><em class="replaceable"><code>table_name</code></em></span></dt><dd><p>
  80       The name (optionally schema-qualified) of the table to be created.
  81      </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
  82       The name of a column to be created in the new table.
  83      </p></dd><dt><span class="term"><em class="replaceable"><code>data_type</code></em></span></dt><dd><p>
  84       The data type of the column. This can include array
  85       specifiers. For more information on the data types supported by
  86       <span class="productname">PostgreSQL</span>, refer to <a class="xref" href="datatype.html" title="Chapter 8. Data Types">Chapter 8</a>.
  87      </p></dd><dt><span class="term"><code class="literal">COLLATE <em class="replaceable"><code>collation</code></em></code></span></dt><dd><p>
  88       The <code class="literal">COLLATE</code> clause assigns a collation to
  89       the column (which must be of a collatable data type).
  90       If not specified, the column data type's default collation is used.
  91      </p></dd><dt><span class="term"><code class="literal">INHERITS ( <em class="replaceable"><code>parent_table</code></em> [, ... ] )</code></span></dt><dd><p>
  92       The optional <code class="literal">INHERITS</code> clause specifies a list of
  93       tables from which the new foreign table automatically inherits
  94       all columns.  Parent tables can be plain tables or foreign tables.
  95       See the similar form of
  96       <a class="link" href="sql-createtable.html" title="CREATE TABLE"><code class="command">CREATE TABLE</code></a> for more details.
  97      </p></dd><dt><span class="term"><code class="literal">PARTITION OF <em class="replaceable"><code>parent_table</code></em> { FOR VALUES <em class="replaceable"><code>partition_bound_spec</code></em> | DEFAULT }</code></span></dt><dd><p>
  98       This form can be used to create the foreign table as partition of
  99       the given parent table with specified partition bound values.
 100       See the similar form of
 101       <a class="link" href="sql-createtable.html" title="CREATE TABLE"><code class="command">CREATE TABLE</code></a> for more details.
 102       Note that it is currently not allowed to create the foreign table as a
 103       partition of the parent table if there are <code class="literal">UNIQUE</code>
 104       indexes on the parent table.  (See also
 105       <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE ATTACH PARTITION</code></a>.)
 106      </p></dd><dt><span class="term"><code class="literal">LIKE <em class="replaceable"><code>source_table</code></em> [ <em class="replaceable"><code>like_option</code></em> ... ]</code></span></dt><dd><p>
 107       The <code class="literal">LIKE</code> clause specifies a table from which
 108       the new table automatically copies all column names, their data types,
 109       and their not-null constraints.
 110      </p><p>
 111       Unlike <code class="literal">INHERITS</code>, the new table and original table
 112       are completely decoupled after creation is complete.  Changes to the
 113       original table will not be applied to the new table, and it is not
 114       possible to include data of the new table in scans of the original
 115       table.
 116      </p><p>
 117       Also unlike <code class="literal">INHERITS</code>, columns and
 118       constraints copied by <code class="literal">LIKE</code> are not merged with similarly
 119       named columns and constraints.
 120       If the same name is specified explicitly or in another
 121       <code class="literal">LIKE</code> clause, an error is signaled.
 122      </p><p>
 123       The optional <em class="replaceable"><code>like_option</code></em> clauses specify
 124       which additional properties of the original table to copy.  Specifying
 125       <code class="literal">INCLUDING</code> copies the property, specifying
 126       <code class="literal">EXCLUDING</code> omits the property.
 127       <code class="literal">EXCLUDING</code> is the default.  If multiple specifications
 128       are made for the same kind of object, the last one is used.  The
 129       available options are:
 130
 131       </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">INCLUDING COMMENTS</code></span></dt><dd><p>
 132           Comments for the copied columns and constraints will be
 133           copied.  The default behavior is to exclude comments, resulting in
 134           the copied columns and constraints in the new table having no
 135           comments.
 136          </p></dd><dt><span class="term"><code class="literal">INCLUDING CONSTRAINTS</code></span></dt><dd><p>
 137           <code class="literal">CHECK</code> constraints will be copied.  No distinction
 138           is made between column constraints and table constraints.  Not-null
 139           constraints are always copied to the new table.
 140          </p></dd><dt><span class="term"><code class="literal">INCLUDING DEFAULTS</code></span></dt><dd><p>
 141           Default expressions for the copied column definitions will be
 142           copied.  Otherwise, default expressions are not copied, resulting in
 143           the copied columns in the new table having null defaults.  Note that
 144           copying defaults that call database-modification functions, such as
 145           <code class="function">nextval</code>, may create a functional linkage
 146           between the original and new tables.
 147          </p></dd><dt><span class="term"><code class="literal">INCLUDING GENERATED</code></span></dt><dd><p>
 148           Any generation expressions of copied column definitions will be
 149           copied.  By default, new columns will be regular base columns.
 150          </p></dd><dt><span class="term"><code class="literal">INCLUDING STATISTICS</code></span></dt><dd><p>
 151           Extended statistics are copied to the new table.
 152          </p></dd><dt><span class="term"><code class="literal">INCLUDING ALL</code></span></dt><dd><p>
 153           <code class="literal">INCLUDING ALL</code> is an abbreviated form selecting
 154           all the available individual options.  (It could be useful to write
 155           individual <code class="literal">EXCLUDING</code> clauses after
 156           <code class="literal">INCLUDING ALL</code> to select all but some specific
 157           options.)
 158          </p></dd></dl></div><p>
 159      </p></dd><dt><span class="term"><code class="literal">CONSTRAINT <em class="replaceable"><code>constraint_name</code></em></code></span></dt><dd><p>
 160       An optional name for a column or table constraint.  If the
 161       constraint is violated, the constraint name is present in error messages,
 162       so constraint names like <code class="literal">col must be positive</code> can be used
 163       to communicate helpful constraint information to client applications.
 164       (Double-quotes are needed to specify constraint names that contain spaces.)
 165       If a constraint name is not specified, the system generates a name.
 166      </p></dd><dt><span class="term"><code class="literal">NOT NULL</code> [ NO INHERIT ]</span></dt><dd><p>
 167       The column is not allowed to contain null values.
 168      </p><p>
 169       A constraint marked with <code class="literal">NO INHERIT</code> will not propagate to
 170       child tables.
 171      </p></dd><dt><span class="term"><code class="literal">NULL</code></span></dt><dd><p>
 172       The column is allowed to contain null values. This is the default.
 173      </p><p>
 174       This clause is only provided for compatibility with
 175       non-standard SQL databases.  Its use is discouraged in new
 176       applications.
 177      </p></dd><dt><span class="term"><code class="literal">CHECK ( <em class="replaceable"><code>expression</code></em> ) [ NO INHERIT ] </code></span></dt><dd><p>
 178       The <code class="literal">CHECK</code> clause specifies an expression producing a
 179       Boolean result which each row in the foreign table is expected
 180       to satisfy; that is, the expression should produce TRUE or UNKNOWN,
 181       never FALSE, for all rows in the foreign table.
 182       A check constraint specified as a column constraint should
 183       reference that column's value only, while an expression
 184       appearing in a table constraint can reference multiple columns.
 185      </p><p>
 186       Currently, <code class="literal">CHECK</code> expressions cannot contain
 187       subqueries nor refer to variables other than columns of the
 188       current row.  The system column <code class="literal">tableoid</code>
 189       may be referenced, but not any other system column.
 190      </p><p>
 191       A constraint marked with <code class="literal">NO INHERIT</code> will not propagate to
 192       child tables.
 193      </p></dd><dt><span class="term"><code class="literal">DEFAULT
 194     <em class="replaceable"><code>default_expr</code></em></code></span></dt><dd><p>
 195       The <code class="literal">DEFAULT</code> clause assigns a default data value for
 196       the column whose column definition it appears within.  The value
 197       is any variable-free expression (subqueries and cross-references
 198       to other columns in the current table are not allowed).  The
 199       data type of the default expression must match the data type of the
 200       column.
 201      </p><p>
 202       The default expression will be used in any insert operation that
 203       does not specify a value for the column.  If there is no default
 204       for a column, then the default is null.
 205      </p></dd><dt><span class="term"><code class="literal">GENERATED ALWAYS AS ( <em class="replaceable"><code>generation_expr</code></em> ) [ STORED | VIRTUAL ]</code><a id="id-1.9.3.66.6.2.14.1.2" class="indexterm"></a></span></dt><dd><p>
 206       This clause creates the column as a <em class="firstterm">generated
 207       column</em>.  The column cannot be written to, and when read the
 208       result of the specified expression will be returned.
 209      </p><p>
 210       When <code class="literal">VIRTUAL</code> is specified, the column will be
 211       computed when it is read.  (The foreign-data wrapper will see it as a
 212       null value in new rows and may choose to store it as a null value or
 213       ignore it altogether.)  When <code class="literal">STORED</code> is specified, the
 214       column will be computed on write.  (The computed value will be presented
 215       to the foreign-data wrapper for storage and must be returned on
 216       reading.)  <code class="literal">VIRTUAL</code> is the default.
 217      </p><p>
 218       The generation expression can refer to other columns in the table, but
 219       not other generated columns.  Any functions and operators used must be
 220       immutable.  References to other tables are not allowed.
 221      </p></dd><dt><span class="term"><em class="replaceable"><code>server_name</code></em></span></dt><dd><p>
 222       The name of an existing foreign server to use for the foreign table.
 223       For details on defining a server, see <a class="xref" href="sql-createserver.html" title="CREATE SERVER"><span class="refentrytitle">CREATE SERVER</span></a>.
 224      </p></dd><dt><span class="term"><code class="literal">OPTIONS ( <em class="replaceable"><code>option</code></em> '<em class="replaceable"><code>value</code></em>' [, ...] )</code></span></dt><dd><p>
 225       Options to be associated with the new foreign table or one of its
 226       columns.
 227       The allowed option names and values are specific to each foreign
 228       data wrapper and are validated using the foreign-data wrapper's
 229       validator function.  Duplicate option names are not allowed (although
 230       it's OK for a table option and a column option to have the same name).
 231      </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.66.7"><h2>Notes</h2><p>
 232     Constraints on foreign tables (such as <code class="literal">CHECK</code>
 233     or <code class="literal">NOT NULL</code> clauses) are not enforced by the
 234     core <span class="productname">PostgreSQL</span> system, and most foreign data wrappers
 235     do not attempt to enforce them either; that is, the constraint is
 236     simply assumed to hold true.  There would be little point in such
 237     enforcement since it would only apply to rows inserted or updated via
 238     the foreign table, and not to rows modified by other means, such as
 239     directly on the remote server.  Instead, a constraint attached to a
 240     foreign table should represent a constraint that is being enforced by
 241     the remote server.
 242    </p><p>
 243     Some special-purpose foreign data wrappers might be the only access
 244     mechanism for the data they access, and in that case it might be
 245     appropriate for the foreign data wrapper itself to perform constraint
 246     enforcement.  But you should not assume that a wrapper does that
 247     unless its documentation says so.
 248    </p><p>
 249     Although <span class="productname">PostgreSQL</span> does not attempt to enforce
 250     constraints on foreign tables, it does assume that they are correct
 251     for purposes of query optimization.  If there are rows visible in the
 252     foreign table that do not satisfy a declared constraint, queries on
 253     the table might produce errors or incorrect answers.  It is the user's
 254     responsibility to ensure that the constraint definition matches
 255     reality.
 256    </p><div class="caution"><h3 class="title">Caution</h3><p>
 257      When a foreign table is used as a partition of a partitioned table,
 258      there is an implicit constraint that its contents must satisfy the
 259      partitioning rule.  Again, it is the user's responsibility to ensure
 260      that that is true, which is best done by installing a matching
 261      constraint on the remote server.
 262     </p></div><p>
 263     Within a partitioned table containing foreign-table partitions,
 264     an <code class="command">UPDATE</code> that changes the partition key value can
 265     cause a row to be moved from a local partition to a foreign-table
 266     partition, provided the foreign data wrapper supports tuple routing.
 267     However, it is not currently possible to move a row from a
 268     foreign-table partition to another partition.
 269     An <code class="command">UPDATE</code> that would require doing that will fail
 270     due to the partitioning constraint, assuming that that is properly
 271     enforced by the remote server.
 272    </p><p>
 273     Similar considerations apply to generated columns.  Stored generated
 274     columns are computed on insert or update on the local
 275     <span class="productname">PostgreSQL</span> server and handed to the
 276     foreign-data wrapper for writing out to the foreign data store, but it is
 277     not enforced that a query of the foreign table returns values for stored
 278     generated columns that are consistent with the generation expression.
 279     Again, this might result in incorrect query results.
 280    </p></div><div class="refsect1" id="SQL-CREATEFOREIGNTABLE-EXAMPLES"><h2>Examples</h2><p>
 281    Create foreign table <code class="structname">films</code>, which will be accessed through
 282    the server <code class="structname">film_server</code>:
 283
 284 </p><pre class="programlisting">
 285 CREATE FOREIGN TABLE films (
 286     code        char(5) NOT NULL,
 287     title       varchar(40) NOT NULL,
 288     did         integer NOT NULL,
 289     date_prod   date,
 290     kind        varchar(10),
 291     len         interval hour to minute
 292 )
 293 SERVER film_server;
 294 </pre><p>
 295    Create foreign table <code class="structname">measurement_y2016m07</code>, which will be
 296    accessed through the server <code class="structname">server_07</code>, as a partition
 297    of the range partitioned table <code class="structname">measurement</code>:
 298
 299 </p><pre class="programlisting">
 300 CREATE FOREIGN TABLE measurement_y2016m07
 301     PARTITION OF measurement FOR VALUES FROM ('2016-07-01') TO ('2016-08-01')
 302     SERVER server_07;
 303 </pre></div><div class="refsect1" id="SQL-CREATEFOREIGNTABLE-COMPATIBILITY"><h2>Compatibility</h2><p>
 304    The <code class="command">CREATE FOREIGN TABLE</code> command largely conforms to the
 305    <acronym class="acronym">SQL</acronym> standard; however, much as with
 306    <a class="link" href="sql-createtable.html" title="CREATE TABLE"><code class="command">CREATE TABLE</code></a>,
 307    <code class="literal">NULL</code> constraints and zero-column foreign tables are permitted.
 308    The ability to specify column default values is also
 309    a <span class="productname">PostgreSQL</span> extension.  Table inheritance, in the form
 310    defined by <span class="productname">PostgreSQL</span>, is nonstandard.
 311    The <code class="literal">LIKE</code> clause, as supported in this command, is
 312    nonstandard.
 313   </p></div><div class="refsect1" id="id-1.9.3.66.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterforeigntable.html" title="ALTER FOREIGN TABLE"><span class="refentrytitle">ALTER FOREIGN TABLE</span></a>, <a class="xref" href="sql-dropforeigntable.html" title="DROP FOREIGN TABLE"><span class="refentrytitle">DROP FOREIGN TABLE</span></a>, <a class="xref" href="sql-createtable.html" title="CREATE TABLE"><span class="refentrytitle">CREATE TABLE</span></a>, <a class="xref" href="sql-createserver.html" title="CREATE SERVER"><span class="refentrytitle">CREATE SERVER</span></a>, <a class="xref" href="sql-importforeignschema.html" title="IMPORT FOREIGN SCHEMA"><span class="refentrytitle">IMPORT FOREIGN SCHEMA</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createfunction.html" title="CREATE FUNCTION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE FOREIGN DATA WRAPPER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE FUNCTION</td></tr></table></div></body></html>