database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-05-01 01:04:50 +03:00
Code

Bring CREATE TABLE syntax synopsis into line with reality; update a

Browse Source 
bunch of old or poorly-worded documentation.
This commit is contained in:
Tom Lane 2001-01-12 05:06:40 +00:00
parent 06ef1ef2ec
commit 359459a44d
1 changed files with 242 additions and 337 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

549
doc/src/sgml/ref/create_table.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table.sgml,v 1.39 2001/01/05 06:34:16 tgl Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table.sgml,v 1.40 2001/01/12 05:06:40 tgl Exp $
Postgres documentation Postgres documentation
--> -->
@ -20,18 +20,31 @@ Postgres documentation
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<refsynopsisdivinfo> <refsynopsisdivinfo>
<date>2001-01-04</date> <date>2001-01-11</date>
</refsynopsisdivinfo> </refsynopsisdivinfo>
<synopsis> <synopsis>
CREATE [ TEMPORARY | TEMP ] TABLE <replaceable class="PARAMETER">table</replaceable> ( CREATE [ TEMPORARY | TEMP ] TABLE <replaceable class="PARAMETER">table_name</replaceable> (
<replaceable class="PARAMETER">column</replaceable> <replaceable class="PARAMETER">type</replaceable> { <replaceable class="PARAMETER">column_name</replaceable> <replaceable class="PARAMETER">type</replaceable> [ <replaceable class="PARAMETER">column_constraint</replaceable> [ ... ] ]
[ NULL | NOT NULL ] [ UNIQUE ] [ DEFAULT <replaceable class="PARAMETER">value</replaceable> ] | <replaceable>table_constraint</replaceable> } [, ... ]
[<replaceable>column_constraint_clause</replaceable> | PRIMARY KEY } [ ... ] ]
[, ... ]
[, PRIMARY KEY ( <replaceable class="PARAMETER">column</replaceable> [, ...] ) ]
[, CHECK ( <replaceable class="PARAMETER">condition</replaceable> ) ]
[, <replaceable>table_constraint_clause</replaceable> ]
) [ INHERITS ( <replaceable>inherited_table</replaceable> [, ... ] ) ] ) [ INHERITS ( <replaceable>inherited_table</replaceable> [, ... ] ) ]
where <replaceable class="PARAMETER">column_constraint</replaceable> can be:
[ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ]
{ NOT NULL | NULL | UNIQUE | PRIMARY KEY | DEFAULT <replaceable class="PARAMETER">value</replaceable> | CHECK (<replaceable class="PARAMETER">condition</replaceable>) |
REFERENCES <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable class="PARAMETER">column</replaceable> ) ] [ MATCH FULL | MATCH PARTIAL ]
[ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ]
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
}
and <replaceable class="PARAMETER">table_constraint</replaceable> can be:
[ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ]
{ UNIQUE ( <replaceable class="PARAMETER">column_name</replaceable> [, ... ] ) |
PRIMARY KEY ( <replaceable class="PARAMETER">column_name</replaceable> [, ... ] ) |
CHECK ( <replaceable class="PARAMETER">condition</replaceable> ) |
FOREIGN KEY ( <replaceable class="PARAMETER">column_name</replaceable> [, ... ] ) REFERENCES <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable class="PARAMETER">column</replaceable> [, ... ] ) ]
[ MATCH FULL | MATCH PARTIAL ] [ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ]
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
}
</synopsis> </synopsis>
<refsect2 id="R2-SQL-CREATETABLE-1"> <refsect2 id="R2-SQL-CREATETABLE-1">
@ -43,19 +56,21 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable class="PARAMETER">table</replacea
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>TEMPORARY</term> <term>TEMPORARY or TEMP</term>
<listitem> <listitem>
<para> <para>
The table is created only for this session, and is If specified, the table is created only for this session, and is
automatically dropped on session exit. automatically dropped on session exit.
Existing permanent tables with the same name are not visible Existing permanent tables with the same name are not visible
while the temporary table exists. (in this session) while the temporary table exists.
Any indexes created on a temporary table are automatically
temporary as well.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><replaceable class="PARAMETER">table</replaceable></term> <term><replaceable class="PARAMETER">table_name</replaceable></term>
<listitem> <listitem>
<para> <para>
The name of the new table to be created. The name of the new table to be created.
@ -64,10 +79,10 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable class="PARAMETER">table</replacea
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><replaceable class="PARAMETER">column</replaceable></term> <term><replaceable class="PARAMETER">column_name</replaceable></term>
<listitem> <listitem>
<para> <para>
The name of a column. The name of a column to be created in the new table.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -84,53 +99,7 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable class="PARAMETER">table</replacea
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>DEFAULT <replaceable class="PARAMETER">value</replaceable></term> <term><replaceable class="PARAMETER">inherited_table</replaceable></term>
<listitem>
<para>
A default value for a column.
See the DEFAULT clause for more information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>column_constraint_clause</replaceable></term>
<listitem>
<para>
The optional column constraint clauses specify a list of
integrity constraints or tests which new or updated entries must
satisfy for an insert or update operation to succeed. Each
constraint must evaluate to a boolean expression. Although
<acronym>SQL92</acronym> requires the <replaceable
class="PARAMETER">column_constraint_clause</replaceable> to
refer to that column only, <productname>Postgres</productname>
allows multiple columns to be referenced within a single column
constraint. See the column constraint clause for more
information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>table_constraint_clause</replaceable></term>
<listitem>
<para>
The optional table CONSTRAINT clause specifies a
list of integrity constraints which new or updated entries must
satisfy for an insert or update operation to succeed. Each
constraint must evaluate to a boolean expression. Multiple
columns may be referenced within a single constraint. Only one
PRIMARY KEY clause may be specified for a table;
PRIMARY KEY <replaceable>column</replaceable> (a table
constraint) and PRIMARY KEY (a column constraint)
are mutually exclusive. See the table constraint clause for
more information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>INHERITS <replaceable class="PARAMETER">inherited_table</replaceable></term>
<listitem> <listitem>
<para> <para>
The optional INHERITS clause specifies a list of table The optional INHERITS clause specifies a list of table
@ -144,6 +113,72 @@ CREATE [ TEMPORARY | TEMP ] TABLE <replaceable class="PARAMETER">table</replacea
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">constraint_name</replaceable></term>
<listitem>
<para>
An optional name for a column or table constraint. If not specified,
the system generates a name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">value</replaceable></term>
<listitem>
<para>
A default value for a column.
See the DEFAULT clause for more information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">condition</replaceable></term>
<listitem>
<para>
CHECK clauses specify integrity constraints or tests which new or
updated rows must satisfy for an insert or update operation to
succeed. Each constraint must be an expression producing
a boolean result.
A condition appearing within a column definition should reference
that column's value only, while a condition appearing as a table
constraint may reference multiple columns.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">table</replaceable></term>
<listitem>
<para>
The name of an existing table to be referenced by a foreign
key constraint.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">column</replaceable></term>
<listitem>
<para>
The name of a column in an existing table to be referenced by a
foreign key constraint. If not specified, the primary key of
the existing table is assumed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">action</replaceable></term>
<listitem>
<para>
A keyword indicating the action to take when a foreign key
constraint is violated.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para> </para>
</refsect2> </refsect2>
@ -182,18 +217,6 @@ ERROR: Relation '<replaceable class="parameter">table</replaceable>' already ex
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: DEFAULT: type mismatched
</computeroutput></term>
<listitem>
<para>
If data type of default value doesn't match the
column definition's data type.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para> </para>
</refsect2> </refsect2>
@ -205,7 +228,7 @@ ERROR: DEFAULT: type mismatched
</title> </title>
<para> <para>
<command>CREATE TABLE</command> will enter a new table <command>CREATE TABLE</command> will enter a new, initially empty table
into the current database. The table will be "owned" by the user issuing the into the current database. The table will be "owned" by the user issuing the
command. command.
</para> </para>
@ -228,6 +251,13 @@ ERROR: DEFAULT: type mismatched
</note> </note>
</para> </para>
<para>
<command>CREATE TABLE</command> also automatically creates a data type
that represents the tuple type (structure type) corresponding to one
row of the table. Therefore, tables can't have the same name as any
existing datatype.
</para>
<para> <para>
The optional INHERITS The optional INHERITS
clause specifies a collection of table names from which this table clause specifies a collection of table names from which this table
@ -239,15 +269,6 @@ ERROR: DEFAULT: type mismatched
</para> </para>
<para> <para>
Each new table <replaceable class="PARAMETER">table</replaceable>
is automatically created as a type. Therefore, one or more rows
from the table are automatically a type and can be used in
<xref linkend="sql-altertable" endterm="sql-altertable-title">
or other <command>CREATE TABLE</command> statements.
</para>
<para>
The new table is created as a heap with no initial data.
A table can have no more than 1600 columns (in practice, the A table can have no more than 1600 columns (in practice, the
effective limit is lower because of tuple-length constraints). effective limit is lower because of tuple-length constraints).
A table cannot have the same name as a system catalog table. A table cannot have the same name as a system catalog table.
@ -263,179 +284,71 @@ ERROR: DEFAULT: type mismatched
DEFAULT <replaceable class="PARAMETER">value</replaceable> DEFAULT <replaceable class="PARAMETER">value</replaceable>
</synopsis> </synopsis>
</para> </para>
<refsect2 id="R2-SQL-DEFAULTCLAUSE-1">
<title>
Inputs
</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">value</replaceable></term>
<listitem>
<para> <para>
The possible values for the default value expression are: The DEFAULT clause assigns a default data value for the column whose
<itemizedlist> column definition it appears within. The value is any variable-free
<listitem> expression (note that sub-selects and cross-references to other
<simpara> columns in the current table are not supported).
a literal value
</simpara>
</listitem>
<listitem>
<simpara>
a user function
</simpara>
</listitem>
<listitem>
<simpara>
a niladic function
</simpara>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2 id="R2-SQL-DEFAULTCLAUSE-2">
<title>
Outputs
</title>
<para>
None.
</para>
</refsect2>
<refsect2 id="R2-SQL-DEFAULTCLAUSE-3">
<title>
Description
</title>
<para>
The DEFAULT clause assigns a default data value to a column
(via a column definition in the CREATE TABLE statement).
The data type of a default value must match the column definition's The data type of a default value must match the column definition's
data type. data type.
</para> </para>
<para> <para>
An INSERT operation that includes a column without a specified The DEFAULT expression will be used in any INSERT operation that does
default value will assign the NULL value to the column not specify a value for the column. If there is no DEFAULT clause,
if no explicit data value is provided for it. then the default is NULL.
Default <replaceable class="parameter">literal</replaceable> means
that the default is the specified constant value.
Default <replaceable class="parameter">niladic-function</replaceable>
or <replaceable class="parameter">user-function</replaceable> means
that the default
is the value of the specified function at the time of the INSERT.
</para>
<para>
There are two types of niladic functions:
<variablelist>
<varlistentry>
<term>niladic USER</term>
<listitem>
<variablelist>
<varlistentry>
<term>CURRENT_USER / USER</term>
<listitem>
<simpara>See CURRENT_USER function</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>SESSION_USER</term>
<listitem>
<simpara>See CURRENT_USER function</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>SYSTEM_USER</term>
<listitem>
<simpara>Not implemented</simpara>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>niladic datetime</term>
<listitem>
<variablelist>
<varlistentry>
<term>CURRENT_DATE</term>
<listitem>
<simpara>See CURRENT_DATE function</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>CURRENT_TIME</term>
<listitem>
<simpara>See CURRENT_TIME function</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>CURRENT_TIMESTAMP</term>
<listitem>
<simpara>See CURRENT_TIMESTAMP function</simpara>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</para> </para>
</refsect2> <refsect2 id="R2-SQL-DEFAULTCLAUSE-2">
<refsect2 id="R2-SQL-DEFAULTCLAUSE-4">
<title> <title>
Usage Usage
</title> </title>
<para> <para>
To assign a constant value as the default for the
columns <literal>did</literal> and <literal>number</literal>,
and a string literal to the column <literal>did</literal>:
<programlisting>
CREATE TABLE video_sales (
did VARCHAR(40) DEFAULT 'luso films',
number INTEGER DEFAULT 0,
total CASH DEFAULT '$0.0'
);
</programlisting>
</para>
<para>
To assign an existing sequence
as the default for the column <literal>did</literal>,
and a literal to the column <literal>name</literal>:
<programlisting> <programlisting>
CREATE TABLE distributors ( CREATE TABLE distributors (
did DECIMAL(3) DEFAULT NEXTVAL('serial'), name VARCHAR(40) DEFAULT 'luso films',
name VARCHAR(40) DEFAULT 'luso films' did INTEGER DEFAULT NEXTVAL('distributors_serial'),
modtime TIMESTAMP DEFAULT now()
); );
</programlisting> </programlisting>
The above assigns a literal constant default value for the column
<literal>name</literal>, and arranges for the default value of column
<literal>did</literal> to be generated by selecting the next value of a
sequence object. The default value of <literal>modtime</literal> will
be the time at which the row is inserted.
</para>
<para>
It is worth remarking that
<programlisting>
modtime TIMESTAMP DEFAULT 'now'
</programlisting>
would produce a result that is probably not the intended one: the
string <literal>'now'</literal> will be coerced to a timestamp value
immediately, and so the default value of <literal>modtime</literal> will
always be the time of table creation. This difficulty is avoided by
specifying the default value as a function call.
</para> </para>
</refsect2> </refsect2>
</refsect1> </refsect1>
<refsect1 id="R1-SQL-COLUMNCONSTRAINT-1"> <refsect1 id="R1-SQL-COLUMNCONSTRAINT-1">
<title id="R1-SQL-COLUMNCONSTRAINT-1-TITLE"> <title id="R1-SQL-COLUMNCONSTRAINT-1-TITLE">
Column CONSTRAINT Clause Column Constraints
</title> </title>
<para> <para>
<synopsis> <synopsis>
[ CONSTRAINT <replaceable class="parameter">name</replaceable> ] { [ [ CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> ] {
NULL | NOT NULL ] | UNIQUE | PRIMARY KEY | CHECK <replaceable NULL | NOT NULL | UNIQUE | PRIMARY KEY | CHECK <replaceable
class="parameter">constraint</replaceable> | REFERENCES class="parameter">condition</replaceable> |
<replaceable class="parameter">reftable</replaceable> REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> ) ]
(<replaceable class="parameter">refcolumn</replaceable>)
[ MATCH <replaceable class="parameter">matchtype</replaceable> ] [ MATCH <replaceable class="parameter">matchtype</replaceable> ]
[ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON DELETE <replaceable class="parameter">action</replaceable> ]
[ ON UPDATE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ]
[ [ NOT ] DEFERRABLE ] [ [ NOT ] DEFERRABLE ]
[ INITIALLY <replaceable class="parameter">checktime</replaceable> ] } [ INITIALLY <replaceable class="parameter">checktime</replaceable> ] }
[, ...]
</synopsis> </synopsis>
</para> </para>
@ -447,14 +360,10 @@ CREATE TABLE distributors (
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><replaceable class="parameter">name</replaceable></term> <term><replaceable class="parameter">constraint_name</replaceable></term>
<listitem> <listitem>
<para> <para>
An arbitrary name given to the integrity constraint. An arbitrary name given to a constraint clause.
If <replaceable class="parameter">name</replaceable> is not specified,
it is generated from the table and column names,
which should ensure uniqueness for
<replaceable class="parameter">name</replaceable>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -484,7 +393,7 @@ CREATE TABLE distributors (
<listitem> <listitem>
<para> <para>
The column must have unique values. In <productname>Postgres</productname> The column must have unique values. In <productname>Postgres</productname>
this is enforced by an implicit creation of a unique index on the table. this is enforced by automatic creation of a unique index on the column.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -493,9 +402,9 @@ CREATE TABLE distributors (
<term>PRIMARY KEY</term> <term>PRIMARY KEY</term>
<listitem> <listitem>
<para> <para>
This column is a primary key, which implies that uniqueness is This column is a primary key, which implies that other tables may rely
enforced by the system and that other tables may rely on this on this column as a unique identifier for rows. Both UNIQUE and
column as a unique identifier for rows. See PRIMARY KEY for more NOT NULL are implied by PRIMARY KEY. See PRIMARY KEY for more
information. information.
</para> </para>
</listitem> </listitem>
@ -503,11 +412,11 @@ CREATE TABLE distributors (
<varlistentry> <varlistentry>
<term> <term>
<replaceable class="parameter">constraint</replaceable> <replaceable class="parameter">condition</replaceable>
</term> </term>
<listitem> <listitem>
<para> <para>
The definition of the constraint. An arbitrary boolean-valued constraint condition.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -522,17 +431,14 @@ CREATE TABLE distributors (
<para> <para>
The optional constraint clauses specify constraints or tests which The optional constraint clauses specify constraints or tests which
new or updated entries must satisfy for an insert or update new or updated rows must satisfy for an insert or update
operation to succeed. Each constraint must evaluate to a boolean operation to succeed.
expression. Multiple attributes may be referenced within a single
constraint. The use of PRIMARY KEY as a table constraint is mutually
incompatible with PRIMARY KEY as a column constraint.
</para> </para>
<para> <para>
A constraint is a named rule: an SQL object which helps define A constraint is a named rule: an SQL object which helps define
valid sets of values by putting limits on the results of INSERT, valid sets of values by putting limits on the results of INSERT,
UPDATE or DELETE operations performed on a Base Table. UPDATE or DELETE operations performed on a table.
</para> </para>
<para> <para>
@ -615,7 +521,7 @@ ERROR: ExecAppend: Fail to add null value in not null attribute "<replaceable c
<para> <para>
Define two NOT NULL column constraints on the table Define two NOT NULL column constraints on the table
<classname>distributors</classname>, <classname>distributors</classname>,
one of which being a named constraint: one of which is explicitly given a name:
<programlisting> <programlisting>
CREATE TABLE distributors ( CREATE TABLE distributors (
@ -632,7 +538,7 @@ CREATE TABLE distributors (
UNIQUE Constraint UNIQUE Constraint
</title> </title>
<synopsis> <synopsis>
[ CONSTRAINT <replaceable class="parameter">name</replaceable> ] UNIQUE [ CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> ] UNIQUE
</synopsis> </synopsis>
<refsect3> <refsect3>
@ -641,10 +547,10 @@ CREATE TABLE distributors (
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>CONSTRAINT <replaceable class="parameter">name</replaceable></term> <term><replaceable class="parameter">constraint_name</replaceable></term>
<listitem> <listitem>
<para> <para>
An arbitrary label given to a constraint. An arbitrary name given to a constraint clause.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -718,9 +624,7 @@ ERROR: Cannot insert a duplicate key into a unique index.
</title> </title>
<para> <para>
Defines a UNIQUE column constraint for the table distributors. Defines a UNIQUE constraint for the <literal>name</literal> column:
UNIQUE column constraints can only be defined on one column
of the table:
<programlisting> <programlisting>
CREATE TABLE distributors ( CREATE TABLE distributors (
did DECIMAL(3), did DECIMAL(3),
@ -745,8 +649,7 @@ CREATE TABLE distributors (
The CHECK Constraint The CHECK Constraint
</title> </title>
<synopsis> <synopsis>
[ CONSTRAINT <replaceable class="parameter">name</replaceable> ] CHECK [ CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> ] CHECK ( <replaceable>condition</replaceable> )
( <replaceable>condition</replaceable> [, ...] )
</synopsis> </synopsis>
<refsect3 id="R3-SQL-CHECK-1"> <refsect3 id="R3-SQL-CHECK-1">
<title>Inputs</title> <title>Inputs</title>
@ -754,10 +657,10 @@ CREATE TABLE distributors (
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><replaceable class="parameter">name</replaceable></term> <term><replaceable class="parameter">constraint_name</replaceable></term>
<listitem> <listitem>
<para> <para>
An arbitrary name given to a constraint. An arbitrary name given to a constraint clause.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -788,7 +691,7 @@ CREATE TABLE distributors (
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><computeroutput> <term><computeroutput>
ERROR: ExecAppend: rejected due to CHECK constraint "<replaceable class="parameter">table_column</replaceable>". ERROR: ExecAppend: rejected due to CHECK constraint "<replaceable class="parameter">constraint_name</replaceable>".
</computeroutput></term> </computeroutput></term>
<listitem> <listitem>
<para> <para>
@ -808,14 +711,25 @@ ERROR: ExecAppend: rejected due to CHECK constraint "<replaceable class="parame
<refsect3> <refsect3>
<title>Description</title> <title>Description</title>
<para> <para>
The CHECK constraint specifies a restriction on allowed values The CHECK constraint specifies a generic restriction on allowed values
within a column. The CHECK constraint is also allowed as a table within a column. The CHECK constraint is also allowed as a table
constraint. constraint.
</para> </para>
<para> <para>
The SQL92 CHECK column constraints can only be defined on, and CHECK specifies a general boolean expression involving one or more
refer to, one column of the table. columns of a table. A new row will be rejected if the boolean
<productname>Postgres</productname> does not have this restriction. expression evaluates to FALSE when applied to the row's values.
</para>
<para>
Currently, CHECK expressions cannot contain sub-selects nor refer
to variables other than fields of the current row.
</para>
<para>
The SQL92 standard says that CHECK column constraints may only refer
to the column they apply to; only CHECK table constraints may refer
to multiple columns.
<productname>Postgres</productname> does not enforce this restriction.
It treats column and table CHECK constraints alike.
</para> </para>
</refsect3> </refsect3>
</refsect2> </refsect2>
@ -825,7 +739,7 @@ ERROR: ExecAppend: rejected due to CHECK constraint "<replaceable class="parame
PRIMARY KEY Constraint PRIMARY KEY Constraint
</title> </title>
<synopsis> <synopsis>
[ CONSTRAINT <replaceable class="PARAMETER">name</replaceable> ] PRIMARY KEY [ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ] PRIMARY KEY
</synopsis> </synopsis>
<refsect3> <refsect3>
@ -833,10 +747,10 @@ ERROR: ExecAppend: rejected due to CHECK constraint "<replaceable class="parame
<para> <para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>CONSTRAINT <replaceable class="PARAMETER">name</replaceable></term> <term><replaceable class="PARAMETER">constraint_name</replaceable></term>
<listitem> <listitem>
<para> <para>
An arbitrary name for the constraint. An arbitrary name given to a constraint clause.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -871,7 +785,8 @@ ERROR: Cannot insert a duplicate key into a unique index.
constraint. constraint.
</para> </para>
<para> <para>
Only one PRIMARY KEY can be specified for a table. Only one PRIMARY KEY can be specified for a table, whether as a
column constraint or a table constraint.
</para> </para>
</refsect3> </refsect3>
@ -903,7 +818,7 @@ ERROR: Cannot insert a duplicate key into a unique index.
REFERENCES Constraint REFERENCES Constraint
</title> </title>
<synopsis> <synopsis>
[ CONSTRAINT <replaceable class="parameter">name</replaceable> ] REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> ) ] [ CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> ] REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> ) ]
[ MATCH <replaceable class="parameter">matchtype</replaceable> ] [ MATCH <replaceable class="parameter">matchtype</replaceable> ]
[ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON DELETE <replaceable class="parameter">action</replaceable> ]
[ ON UPDATE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ]
@ -923,10 +838,10 @@ ERROR: Cannot insert a duplicate key into a unique index.
<para> <para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>CONSTRAINT <replaceable class="PARAMETER">name</replaceable></term> <term><replaceable class="PARAMETER">constraint_name</replaceable></term>
<listitem> <listitem>
<para> <para>
An arbitrary name for the constraint. An arbitrary name given to a constraint clause.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -958,7 +873,7 @@ ERROR: Cannot insert a duplicate key into a unique index.
default match type if none is specified. MATCH FULL will not default match type if none is specified. MATCH FULL will not
allow one column of a multi-column foreign key to be NULL allow one column of a multi-column foreign key to be NULL
unless all foreign key columns are NULL. The default MATCH type unless all foreign key columns are NULL. The default MATCH type
allows a some foreign key columns to be NULL while other parts allows some foreign key columns to be NULL while other parts
of the foreign key are not NULL. MATCH PARTIAL is currently not of the foreign key are not NULL. MATCH PARTIAL is currently not
supported. supported.
</para> </para>
@ -1184,15 +1099,14 @@ ERROR: <replaceable class="parameter">name</replaceable> referential integrity
<refsect1 id="R1-SQL-TABLECONSTRAINT-1"> <refsect1 id="R1-SQL-TABLECONSTRAINT-1">
<title> <title>
Table CONSTRAINT Clause Table Constraints
</title> </title>
<para> <para>
<synopsis> <synopsis>
[ CONSTRAINT name ] { PRIMARY KEY | UNIQUE } ( <replaceable class="parameter">column</replaceable> [, ... ] ) [ CONSTRAINT name ] { PRIMARY KEY | UNIQUE } ( <replaceable class="parameter">column</replaceable> [, ... ] )
[ CONSTRAINT name ] CHECK ( <replaceable>constraint</replaceable> ) [ CONSTRAINT name ] CHECK ( <replaceable>constraint</replaceable> )
[ CONSTRAINT name ] FOREIGN KEY ( <replaceable class="parameter">column</replaceable> [, ... ] ) [ CONSTRAINT name ] FOREIGN KEY ( <replaceable class="parameter">column</replaceable> [, ... ] )
REFERENCES <replaceable class="parameter">reftable</replaceable> REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> [, ... ] ) ]
(<replaceable class="parameter">refcolumn</replaceable> [, ...] )
[ MATCH <replaceable class="parameter">matchtype</replaceable> ] [ MATCH <replaceable class="parameter">matchtype</replaceable> ]
[ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON DELETE <replaceable class="parameter">action</replaceable> ]
[ ON UPDATE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ]
@ -1209,10 +1123,10 @@ ERROR: <replaceable class="parameter">name</replaceable> referential integrity
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>CONSTRAINT <replaceable class="parameter">name</replaceable></term> <term><replaceable class="parameter">constraint_name</replaceable></term>
<listitem> <listitem>
<para> <para>
An arbitrary name given to an integrity constraint. An arbitrary name given to a constraint clause.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1255,7 +1169,7 @@ ERROR: <replaceable class="parameter">name</replaceable> referential integrity
<para> <para>
A table constraint is an integrity constraint defined on one or A table constraint is an integrity constraint defined on one or
more columns of a base table. The four variations of "Table more columns of a table. The four variations of "Table
Constraint" are: Constraint" are:
<simplelist columns="1"> <simplelist columns="1">
<member>UNIQUE</member> <member>UNIQUE</member>
@ -1272,17 +1186,17 @@ ERROR: <replaceable class="parameter">name</replaceable> referential integrity
</title> </title>
<para> <para>
<synopsis> <synopsis>
[ CONSTRAINT <replaceable class="parameter">name</replaceable> ] UNIQUE ( <replaceable class="parameter">column</replaceable> [, ...] ) [ CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> ] UNIQUE ( <replaceable class="parameter">column</replaceable> [, ... ] )
</synopsis> </synopsis>
</para> </para>
<refsect3> <refsect3>
<title>Inputs</title> <title>Inputs</title>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>CONSTRAINT <replaceable class="parameter">name</replaceable></term> <term><replaceable class="parameter">constraint_name</replaceable></term>
<listitem> <listitem>
<para> <para>
An arbitrary name given to a constraint. An arbitrary name given to a constraint clause.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1346,12 +1260,12 @@ ERROR: <replaceable class="parameter">name</replaceable> referential integrity
</title> </title>
<para> <para>
Define a UNIQUE table constraint for the table distributors: Prevent duplicate rows in the table distributors:
<programlisting> <programlisting>
CREATE TABLE distributors ( CREATE TABLE distributors (
did DECIMAL(3), did DECIMAL(3),
name VARCHAR(40), name VARCHAR(40),
UNIQUE(name) UNIQUE(did,name)
); );
</programlisting> </programlisting>
</para> </para>
@ -1364,7 +1278,7 @@ CREATE TABLE distributors (
</title> </title>
<para> <para>
<synopsis> <synopsis>
[ CONSTRAINT <replaceable class="PARAMETER">name</replaceable> ] PRIMARY KEY ( <replaceable class="PARAMETER">column</replaceable> [, ...] ) [ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ] PRIMARY KEY ( <replaceable class="PARAMETER">column</replaceable> [, ... ] )
</synopsis> </synopsis>
</para> </para>
<refsect3> <refsect3>
@ -1373,10 +1287,10 @@ CREATE TABLE distributors (
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>CONSTRAINT <replaceable class="PARAMETER">name</replaceable></term> <term><replaceable class="PARAMETER">constraint_name</replaceable></term>
<listitem> <listitem>
<para> <para>
An arbitrary name for the constraint. An arbitrary name given to a constraint clause.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1445,7 +1359,7 @@ CREATE TABLE distributors (
REFERENCES Constraint REFERENCES Constraint
</title> </title>
<synopsis> <synopsis>
[ CONSTRAINT <replaceable class="parameter">name</replaceable> ] FOREIGN KEY ( <replaceable class="parameter">column</replaceable> [, ...] ) [ CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> ] FOREIGN KEY ( <replaceable class="parameter">column</replaceable> [, ... ] )
REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> [, ... ] ) ] REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> [, ... ] ) ]
[ MATCH <replaceable class="parameter">matchtype</replaceable> ] [ MATCH <replaceable class="parameter">matchtype</replaceable> ]
[ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON DELETE <replaceable class="parameter">action</replaceable> ]
@ -1454,9 +1368,9 @@ CREATE TABLE distributors (
[ INITIALLY <replaceable class="parameter">checktime</replaceable> ] [ INITIALLY <replaceable class="parameter">checktime</replaceable> ]
</synopsis> </synopsis>
<para> <para>
The REFERENCES constraint specifies a rule that a column value is The REFERENCES constraint specifies a rule that a column value or set
checked against the values of another column. REFERENCES can also be of column values is
specified as part of a FOREIGN KEY table constraint. checked against the values in another table.
</para> </para>
<refsect3 id="R3-SQL-REFERENCES-5"> <refsect3 id="R3-SQL-REFERENCES-5">
@ -1464,10 +1378,10 @@ CREATE TABLE distributors (
<para> <para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>CONSTRAINT <replaceable class="PARAMETER">name</replaceable></term> <term><replaceable class="PARAMETER">constraint_name</replaceable></term>
<listitem> <listitem>
<para> <para>
An arbitrary name for the constraint. An arbitrary name given to a constraint clause.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1491,7 +1405,7 @@ CREATE TABLE distributors (
<term><replaceable class="parameter">referenced column</replaceable> [, ... ]</term> <term><replaceable class="parameter">referenced column</replaceable> [, ... ]</term>
<listitem> <listitem>
<para> <para>
One or more column in the <replaceable class="parameter">reftable</replaceable> One or more columns in the <replaceable class="parameter">reftable</replaceable>
to check the data against. If this is not specified, the PRIMARY KEY of the to check the data against. If this is not specified, the PRIMARY KEY of the
<replaceable class="parameter">reftable</replaceable> is used. <replaceable class="parameter">reftable</replaceable> is used.
</para> </para>
@ -1855,25 +1769,16 @@ CREATE GLOBAL TEMPORARY TABLE <replaceable class="parameter">table</replaceable>
<para> <para>
For temporary tables, the CREATE GLOBAL TEMPORARY TABLE statement For temporary tables, the CREATE GLOBAL TEMPORARY TABLE statement
names a new table visible to other clients and defines the table's columns and names a new table visible to other clients and defines the table's columns
constraints. and constraints.
</para> </para>
<para> <para>
The optional ON COMMIT clause of CREATE TEMPORARY TABLE specifies The optional ON COMMIT clause of CREATE TEMPORARY TABLE specifies
whether or not the temporary table should be emptied of rows whether or not the temporary table should be emptied of rows
whenever COMMIT is executed. If the ON COMMIT clause is omitted, the whenever COMMIT is executed. If the ON COMMIT clause is omitted, SQL92
default option, ON COMMIT DELETE ROWS, is assumed. specifies that the default is ON COMMIT DELETE ROWS. However,
</para> <productname>Postgres</productname>' behavior is always like
<para> ON COMMIT PRESERVE ROWS.
To create a temporary table:
<programlisting>
CREATE TEMPORARY TABLE actors (
id DECIMAL(3),
name VARCHAR(40),
CONSTRAINT actor_id CHECK (id &lt; 150)
) ON COMMIT DELETE ROWS;
</programlisting>
</para> </para>
<refsect3 id="R3-SQL-UNIQUECLAUSE-1"> <refsect3 id="R3-SQL-UNIQUECLAUSE-1">
@ -1887,7 +1792,7 @@ CREATE TEMPORARY TABLE actors (
Table Constraint definition: Table Constraint definition:
<synopsis> <synopsis>
[ CONSTRAINT <replaceable>name</replaceable> ] UNIQUE ( <replaceable>column</replaceable> [, ...] ) [ CONSTRAINT <replaceable>constraint_name</replaceable> ] UNIQUE ( <replaceable>column</replaceable> [, ... ] )
[ { INITIALLY DEFERRED | INITIALLY IMMEDIATE } ] [ { INITIALLY DEFERRED | INITIALLY IMMEDIATE } ]
[ [ NOT ] DEFERRABLE ] [ [ NOT ] DEFERRABLE ]
</synopsis> </synopsis>
@ -1897,7 +1802,7 @@ CREATE TEMPORARY TABLE actors (
Column Constraint definition: Column Constraint definition:
<synopsis> <synopsis>
[ CONSTRAINT <replaceable>name</replaceable> ] UNIQUE [ CONSTRAINT <replaceable>constraint_name</replaceable> ] UNIQUE
[ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ] [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
[ [ NOT ] DEFERRABLE ] [ [ NOT ] DEFERRABLE ]
</synopsis> </synopsis>
@ -1910,11 +1815,12 @@ CREATE TEMPORARY TABLE actors (
</title> </title>
<para> <para>
The NULL "constraint" (actually a non-constraint) is a The NULL "constraint" (actually a non-constraint) is a
<productname>Postgres</productname> extension to SQL92 is <productname>Postgres</productname> extension to SQL92 that is
included for symmetry with the NOT NULL clause. Since it is the included for symmetry with the NOT NULL clause (and for compatibility
with some other RDBMSes). Since it is the
default for any column, its presence is simply noise. default for any column, its presence is simply noise.
<synopsis> <synopsis>
[ CONSTRAINT <replaceable>name</replaceable> ] NULL [ CONSTRAINT <replaceable>constraint_name</replaceable> ] NULL
</synopsis> </synopsis>
</para> </para>
</refsect3> </refsect3>
@ -1927,7 +1833,7 @@ CREATE TEMPORARY TABLE actors (
SQL92 specifies some additional capabilities for NOT NULL: SQL92 specifies some additional capabilities for NOT NULL:
<synopsis> <synopsis>
[ CONSTRAINT <replaceable>name</replaceable> ] NOT NULL [ CONSTRAINT <replaceable>constraint_name</replaceable> ] NOT NULL
[ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ] [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
[ [ NOT ] DEFERRABLE ] [ [ NOT ] DEFERRABLE ]
</synopsis> </synopsis>
@ -1973,7 +1879,7 @@ DEFAULT niladic_user_function | niladic_datetime_function | NULL
<para> <para>
An assertion is a special type of integrity constraint and shares An assertion is a special type of integrity constraint and shares
the same namespace as other constraints. However, an assertion is the same namespace as other constraints. However, an assertion is
not necessarily dependent on one particular base table as not necessarily dependent on one particular table as
constraints are, so SQL-92 provides the CREATE ASSERTION statement constraints are, so SQL-92 provides the CREATE ASSERTION statement
as an alternate method for defining a constraint: as an alternate method for defining a constraint:
</para> </para>
@ -1989,7 +1895,7 @@ CREATE ASSERTION <replaceable>name</replaceable> CHECK ( <replaceable>condition<
Domain constraint: Domain constraint:
<synopsis> <synopsis>
[ CONSTRAINT <replaceable>name</replaceable> ] CHECK <replaceable>constraint</replaceable> [ CONSTRAINT <replaceable>constraint_name</replaceable> ] CHECK <replaceable>constraint</replaceable>
[ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ] [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
[ [ NOT ] DEFERRABLE ] [ [ NOT ] DEFERRABLE ]
</synopsis> </synopsis>
@ -1999,7 +1905,7 @@ CREATE ASSERTION <replaceable>name</replaceable> CHECK ( <replaceable>condition<
Table constraint definition: Table constraint definition:
<synopsis> <synopsis>
[ CONSTRAINT <replaceable>name</replaceable> ] { PRIMARY KEY ( <replaceable class="parameter">column</replaceable>, ... ) | FOREIGN KEY <replaceable>constraint</replaceable> | UNIQUE <replaceable>constraint</replaceable> | CHECK <replaceable>constraint</replaceable> } [ CONSTRAINT <replaceable>constraint_name</replaceable> ] { PRIMARY KEY ( <replaceable class="parameter">column</replaceable>, ... ) | FOREIGN KEY <replaceable>constraint</replaceable> | UNIQUE <replaceable>constraint</replaceable> | CHECK <replaceable>constraint</replaceable> }
[ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ] [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
[ [ NOT ] DEFERRABLE ] [ [ NOT ] DEFERRABLE ]
</synopsis> </synopsis>
@ -2009,7 +1915,7 @@ CREATE ASSERTION <replaceable>name</replaceable> CHECK ( <replaceable>condition<
Column constraint definition: Column constraint definition:
<synopsis> <synopsis>
[ CONSTRAINT <replaceable>name</replaceable> ] { NOT NULL | PRIMARY KEY | FOREIGN KEY <replaceable>constraint</replaceable> | UNIQUE | CHECK <replaceable>constraint</replaceable> } [ CONSTRAINT <replaceable>constraint_name</replaceable> ] { NOT NULL | PRIMARY KEY | FOREIGN KEY <replaceable>constraint</replaceable> | UNIQUE | CHECK <replaceable>constraint</replaceable> }
[ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ] [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
[ [ NOT ] DEFERRABLE ] [ [ NOT ] DEFERRABLE ]
</synopsis> </synopsis>
@ -2051,8 +1957,7 @@ CREATE ASSERTION <replaceable>name</replaceable> CHECK ( <replaceable>condition<
<term>INITIALLY IMMEDIATE</term> <term>INITIALLY IMMEDIATE</term>
<listitem> <listitem>
<para> <para>
Check constraint only at the end of the transaction. This Check constraint after each statement. This is the default.
is the default
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -2060,7 +1965,7 @@ CREATE ASSERTION <replaceable>name</replaceable> CHECK ( <replaceable>condition<
<term>INITIALLY DEFERRED</term> <term>INITIALLY DEFERRED</term>
<listitem> <listitem>
<para> <para>
Check constraint after each statement. Check constraint only at the end of the transaction.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -2090,7 +1995,7 @@ affect a column or a table.
<para> <para>
table constraint definition: table constraint definition:
<synopsis> <synopsis>
[ CONSTRAINT <replaceable>name</replaceable> ] CHECK ( VALUE <replaceable>condition</replaceable> ) [ CONSTRAINT <replaceable>constraint_name</replaceable> ] CHECK ( VALUE <replaceable>condition</replaceable> )
[ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ] [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
[ [ NOT ] DEFERRABLE ] [ [ NOT ] DEFERRABLE ]
</synopsis> </synopsis>
@ -2099,7 +2004,7 @@ affect a column or a table.
<para> <para>
column constraint definition: column constraint definition:
<synopsis> <synopsis>
[ CONSTRAINT <replaceable>name</replaceable> ] CHECK ( VALUE <replaceable>condition</replaceable> ) [ CONSTRAINT <replaceable>constraint_name</replaceable> ] CHECK ( VALUE <replaceable>condition</replaceable> )
[ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ] [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
[ [ NOT ] DEFERRABLE ] [ [ NOT ] DEFERRABLE ]
</synopsis> </synopsis>
@ -2138,7 +2043,7 @@ ALTER DOMAIN cities
<para> <para>
Table Constraint definition: Table Constraint definition:
<synopsis> <synopsis>
[ CONSTRAINT <replaceable>name</replaceable> ] PRIMARY KEY ( <replaceable>column</replaceable> [, ...] ) [ CONSTRAINT <replaceable>constraint_name</replaceable> ] PRIMARY KEY ( <replaceable>column</replaceable> [, ... ] )
[ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ] [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
[ [ NOT ] DEFERRABLE ] [ [ NOT ] DEFERRABLE ]
</synopsis> </synopsis>
@ -2146,7 +2051,7 @@ ALTER DOMAIN cities
<para> <para>
Column Constraint definition: Column Constraint definition:
<synopsis> <synopsis>
[ CONSTRAINT <replaceable>name</replaceable> ] PRIMARY KEY [ CONSTRAINT <replaceable>constraint_name</replaceable> ] PRIMARY KEY
[ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ] [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
[ [ NOT ] DEFERRABLE ] [ [ NOT ] DEFERRABLE ]
</synopsis> </synopsis>