diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/ref/alter_foreign_table.sgml | 113 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_foreign_table.sgml | 65 |
2 files changed, 149 insertions, 29 deletions
diff --git a/doc/src/sgml/ref/alter_foreign_table.sgml b/doc/src/sgml/ref/alter_foreign_table.sgml index 9d9c439315f..ff48ab88829 100644 --- a/doc/src/sgml/ref/alter_foreign_table.sgml +++ b/doc/src/sgml/ref/alter_foreign_table.sgml @@ -42,6 +42,8 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceab ALTER [ COLUMN ] <replaceable class="PARAMETER">column_name</replaceable> SET ( <replaceable class="PARAMETER">attribute_option</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] ) ALTER [ COLUMN ] <replaceable class="PARAMETER">column_name</replaceable> RESET ( <replaceable class="PARAMETER">attribute_option</replaceable> [, ... ] ) ALTER [ COLUMN ] <replaceable class="PARAMETER">column_name</replaceable> OPTIONS ( [ ADD | SET | DROP ] <replaceable class="PARAMETER">option</replaceable> ['<replaceable class="PARAMETER">value</replaceable>'] [, ... ]) + ADD <replaceable class="PARAMETER">table_constraint</replaceable> + DROP CONSTRAINT [ IF EXISTS ] <replaceable class="PARAMETER">constraint_name</replaceable> [ RESTRICT | CASCADE ] DISABLE TRIGGER [ <replaceable class="PARAMETER">trigger_name</replaceable> | ALL | USER ] ENABLE TRIGGER [ <replaceable class="PARAMETER">trigger_name</replaceable> | ALL | USER ] ENABLE REPLICA TRIGGER <replaceable class="PARAMETER">trigger_name</replaceable> @@ -88,16 +90,6 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceab </varlistentry> <varlistentry> - <term><literal>IF EXISTS</literal></term> - <listitem> - <para> - Do not throw an error if the foreign table does not exist. A notice is - issued in this case. - </para> - </listitem> - </varlistentry> - - <varlistentry> <term><literal>SET DATA TYPE</literal></term> <listitem> <para> @@ -153,41 +145,54 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceab </varlistentry> <varlistentry> - <term><literal>DISABLE</literal>/<literal>ENABLE [ REPLICA | ALWAYS ] TRIGGER</literal></term> + <term><literal>ADD <replaceable class="PARAMETER">table_constraint</replaceable></literal></term> <listitem> <para> - These forms configure the firing of trigger(s) belonging to the foreign - table. See the similar form of <xref linkend="sql-altertable"> for more - details. + This form adds a new constraint to a foreign table, using the same + syntax as <xref linkend="SQL-CREATEFOREIGNTABLE">. + Currently only <literal>CHECK</> constraints are supported. + </para> + + <para> + Unlike the case when adding a constraint to a regular table, nothing is + done to verify the constraint is correct; rather, this action simply + declares that some new condition holds for all rows in the foreign + table. (See the discussion in <xref linkend="SQL-CREATEFOREIGNTABLE">.) + Note that constraints on foreign tables cannot be marked + <literal>NOT VALID</> since such constraints are simply declarative. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>OWNER</literal></term> + <term><literal>DROP CONSTRAINT [ IF EXISTS ]</literal></term> <listitem> <para> - This form changes the owner of the foreign table to the - specified user. + This form drops the specified constraint on a foreign table. + If <literal>IF EXISTS</literal> is specified and the constraint + does not exist, no error is thrown. + In this case a notice is issued instead. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>RENAME</literal></term> + <term><literal>DISABLE</literal>/<literal>ENABLE [ REPLICA | ALWAYS ] TRIGGER</literal></term> <listitem> <para> - The <literal>RENAME</literal> forms change the name of a foreign table - or the name of an individual column in a foreign table. + These forms configure the firing of trigger(s) belonging to the foreign + table. See the similar form of <xref linkend="sql-altertable"> for more + details. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>SET SCHEMA</literal></term> + <term><literal>OWNER</literal></term> <listitem> <para> - This form moves the foreign table into another schema. + This form changes the owner of the foreign table to the + specified user. </para> </listitem> </varlistentry> @@ -207,6 +212,25 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceab </listitem> </varlistentry> + <varlistentry> + <term><literal>RENAME</literal></term> + <listitem> + <para> + The <literal>RENAME</literal> forms change the name of a foreign table + or the name of an individual column in a foreign table. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>SET SCHEMA</literal></term> + <listitem> + <para> + This form moves the foreign table into another schema. + </para> + </listitem> + </varlistentry> + </variablelist> </para> @@ -219,6 +243,12 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceab </para> <para> + If the command is written as <literal>ALTER FOREIGN TABLE IF EXISTS ...</> + and the foreign table does not exist, no error is thrown. A notice is + issued in this case. + </para> + + <para> You must own the table to use <command>ALTER FOREIGN TABLE</>. To change the schema of a foreign table, you must also have <literal>CREATE</literal> privilege on the new schema. @@ -285,11 +315,29 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceab </varlistentry> <varlistentry> + <term><replaceable class="PARAMETER">table_constraint</replaceable></term> + <listitem> + <para> + New table constraint for the foreign table. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="PARAMETER">constraint_name</replaceable></term> + <listitem> + <para> + Name of an existing constraint to drop. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><literal>CASCADE</literal></term> <listitem> <para> Automatically drop objects that depend on the dropped column - (for example, views referencing the column). + or constraint (for example, views referencing the column). </para> </listitem> </varlistentry> @@ -298,7 +346,7 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceab <term><literal>RESTRICT</literal></term> <listitem> <para> - Refuse to drop the column if there are any dependent + Refuse to drop the column or constraint if there are any dependent objects. This is the default behavior. </para> </listitem> @@ -365,10 +413,10 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceab <para> Consistency with the foreign server is not checked when a column is added or removed with <literal>ADD COLUMN</literal> or - <literal>DROP COLUMN</literal>, a <literal>NOT NULL</> constraint is - added, or a column type is changed with <literal>SET DATA TYPE</>. It is - the user's responsibility to ensure that the table definition matches the - remote side. + <literal>DROP COLUMN</literal>, a <literal>NOT NULL</> + or <literal>CHECK</> constraint is added, or a column type is changed + with <literal>SET DATA TYPE</>. It is the user's responsibility to ensure + that the table definition matches the remote side. </para> <para> @@ -413,4 +461,13 @@ ALTER FOREIGN TABLE myschema.distributors OPTIONS (ADD opt1 'value', SET opt2, ' extension of SQL, which disallows zero-column foreign tables. </para> </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-createforeigntable"></member> + <member><xref linkend="sql-dropforeigntable"></member> + </simplelist> + </refsect1> </refentry> diff --git a/doc/src/sgml/ref/create_foreign_table.sgml b/doc/src/sgml/ref/create_foreign_table.sgml index 46a20eff14f..a24aa6e6d1d 100644 --- a/doc/src/sgml/ref/create_foreign_table.sgml +++ b/doc/src/sgml/ref/create_foreign_table.sgml @@ -19,7 +19,8 @@ <refsynopsisdiv> <synopsis> CREATE FOREIGN TABLE [ IF NOT EXISTS ] <replaceable class="PARAMETER">table_name</replaceable> ( [ - <replaceable class="PARAMETER">column_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [ OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] ) ] [ COLLATE <replaceable>collation</replaceable> ] [ <replaceable class="PARAMETER">column_constraint</replaceable> [ ... ] ] + { <replaceable class="PARAMETER">column_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [ OPTIONS ( <replaceable class="PARAMETER">option</replaceable> '<replaceable class="PARAMETER">value</replaceable>' [, ... ] ) ] [ COLLATE <replaceable>collation</replaceable> ] [ <replaceable class="PARAMETER">column_constraint</replaceable> [ ... ] ] + | <replaceable>table_constraint</replaceable> } [, ... ] ] ) SERVER <replaceable class="parameter">server_name</replaceable> @@ -30,7 +31,13 @@ CREATE FOREIGN TABLE [ IF NOT EXISTS ] <replaceable class="PARAMETER">table_name [ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ] { NOT NULL | NULL | + CHECK ( <replaceable class="PARAMETER">expression</replaceable> ) | DEFAULT <replaceable>default_expr</replaceable> } + +<phrase>and <replaceable class="PARAMETER">table_constraint</replaceable> is:</phrase> + +[ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ] +CHECK ( <replaceable class="PARAMETER">expression</replaceable> ) </synopsis> </refsynopsisdiv> @@ -138,6 +145,28 @@ CREATE FOREIGN TABLE [ IF NOT EXISTS ] <replaceable class="PARAMETER">table_name </varlistentry> <varlistentry> + <term><literal>CHECK ( <replaceable class="PARAMETER">expression</replaceable> )</literal></term> + <listitem> + <para> + The <literal>CHECK</> clause specifies an expression producing a + Boolean result which each row in the foreign table is expected + to satisfy; that is, the expression should produce TRUE or UNKNOWN, + never FALSE, for all rows in the foreign table. + A check constraint specified as a column constraint should + reference that column's value only, while an expression + appearing in a table constraint can reference multiple columns. + </para> + + <para> + Currently, <literal>CHECK</literal> expressions cannot contain + subqueries nor refer to variables other than columns of the + current row. The system column <literal>tableoid</literal> + may be referenced, but not any other system column. + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><literal>DEFAULT <replaceable>default_expr</replaceable></literal></term> <listitem> @@ -187,6 +216,40 @@ CREATE FOREIGN TABLE [ IF NOT EXISTS ] <replaceable class="PARAMETER">table_name </refsect1> + <refsect1> + <title>Notes</title> + + <para> + Constraints on foreign tables (such as <literal>CHECK</> + or <literal>NOT NULL</> clauses) are not enforced by the + core <productname>PostgreSQL</> system, and most foreign data wrappers + do not attempt to enforce them either; that is, the constraint is + simply assumed to hold true. There would be little point in such + enforcement since it would only apply to rows inserted or updated via + the foreign table, and not to rows modified by other means, such as + directly on the remote server. Instead, a constraint attached to a + foreign table should represent a constraint that is being enforced by + the remote server. + </para> + + <para> + Some special-purpose foreign data wrappers might be the only access + mechanism for the data they access, and in that case it might be + appropriate for the foreign data wrapper itself to perform constraint + enforcement. But you should not assume that a wrapper does that + unless its documentation says so. + </para> + + <para> + Although <productname>PostgreSQL</> does not attempt to enforce + constraints on foreign tables, it does assume that they are correct + for purposes of query optimization. If there are rows visible in the + foreign table that do not satisfy a declared constraint, queries on + the table might produce incorrect answers. It is the user's + responsibility to ensure that the constraint definition matches + reality. + </para> + </refsect1> <refsect1 id="SQL-CREATEFOREIGNTABLE-examples"> <title>Examples</title> |