create_table.sgml

PostgreSQL7.4.6 for Linux

     </para>

     <para>
      For the purpose of a unique constraint, null values are not
      considered equal.
     </para>

     <para>
      Each unique table constraint must name a set of columns that is
      different from the set of columns named by any other unique or
      primary key constraint defined for the table.  (Otherwise it
      would just be the same constraint listed twice.)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>PRIMARY KEY</> (column constraint)</term>
    <term><literal>PRIMARY KEY ( <replaceable class="PARAMETER">column_name</replaceable> [, ... ] )</> (table constraint)</term>
    <listitem>
     <para>
      The primary key constraint specifies that a column or columns of a table
      may contain only unique (non-duplicate), nonnull values.
      Technically, <literal>PRIMARY KEY</literal> is merely a
      combination of <literal>UNIQUE</> and <literal>NOT NULL</>, but
      identifying a set of columns as primary key also provides
      metadata about the design of the schema, as a primary key
      implies that other tables
      may rely on this set of columns as a unique identifier for rows.
     </para>

     <para>
      Only one primary key can be specified for a table, whether as a
      column constraint or a table constraint.
     </para>

     <para>
      The primary key constraint should name a set of columns that is
      different from other sets of columns named by any unique
      constraint defined for the same table.
     </para>
    </listitem>
   </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 new or updated rows must satisfy for an
      insert or update operation to succeed.  A check constraint
      specified as a column constraint should reference that column's
      value only, while an expression appearing in a table constraint
      may reference multiple columns.
     </para>

     <para>
      Currently, <literal>CHECK</literal> expressions cannot contain
      subqueries nor refer to variables other than columns of the
      current row.
     </para>
    </listitem>
   </varlistentry>


   <varlistentry>
    <term><literal>REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> ) ] [ MATCH <replaceable class="parameter">matchtype</replaceable> ] [ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ]</literal> (column constraint)</term>

   <term><literal>FOREIGN KEY ( <replaceable class="parameter">column</replaceable> [, ... ] )
    REFERENCES <replaceable class="parameter">reftable</replaceable> [ ( <replaceable class="parameter">refcolumn</replaceable> [, ... ] ) ] 
    [ MATCH <replaceable class="parameter">matchtype</replaceable> ]
    [ ON DELETE <replaceable class="parameter">action</replaceable> ] 
    [ ON UPDATE <replaceable class="parameter">action</replaceable> ]</literal>
    (table constraint)</term>

    <listitem>
     <para>
      Theses clauses specify a foreign key constraint, which specifies
      that a group of one or more columns of the new table must only
      contain values which match against values in the referenced
      column(s) <replaceable class="parameter">refcolumn</replaceable>
      of the referenced table <replaceable
      class="parameter">reftable</replaceable>.  If <replaceable
      class="parameter">refcolumn</replaceable> is omitted, the
      primary key of the <replaceable
      class="parameter">reftable</replaceable> is used.  The
      referenced columns must be the columns of a unique or primary
      key constraint in the referenced table.
     </para>

     <para>
      A value inserted into these columns is matched against the
      values of the referenced table and referenced columns using the
      given match type.  There are three match types: <literal>MATCH
      FULL</>, <literal>MATCH PARTIAL</>, and <literal>MATCH
      SIMPLE</literal>, which is also the default.  <literal>MATCH
      FULL</> will not allow one column of a multicolumn foreign key
      to be null unless all foreign key columns are null.
      <literal>MATCH SIMPLE</literal> allows some foreign key columns
      to be null while other parts of the foreign key are not
      null. <literal>MATCH PARTIAL</> is not yet implemented.
     </para>

     <para>
      In addition, when the data in the referenced columns is changed,
      certain actions are performed on the data in this table's
      columns.  The <literal>ON DELETE</literal> clause specifies the
      action to perform when a referenced row in the referenced table is
      being deleted.  Likewise, the <literal>ON UPDATE</literal>
      clause specifies the action to perform when a referenced column
      in the referenced table is being updated to a new value. If the
      row is updated, but the referenced column is not actually
      changed, no action is done.  There are the following possible
      actions for each clause:

      <variablelist>
       <varlistentry>
        <term><literal>NO ACTION</literal></term>
        <listitem>
         <para>
          Produce an error indicating that the deletion or update
          would create a foreign key constraint violation.  This is
          the default action.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><literal>RESTRICT</literal></term>
        <listitem>
         <para>
          Same as <literal>NO ACTION</literal> except that this action
          will not be deferred even if the rest of the constraint is
          deferrable and deferred.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><literal>CASCADE</literal></term>
        <listitem>
         <para>
          Delete any rows referencing the deleted row, or update the
          value of the referencing column to the new value of the
          referenced column, respectively.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><literal>SET NULL</literal></term>
        <listitem>
         <para>
          Set the referencing column values to null.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><literal>SET DEFAULT</literal></term>
        <listitem>
         <para>
          Set the referencing column values to their default value.
         </para>
        </listitem>
       </varlistentry>
      </variablelist>
     </para>

     <para>
      If primary key column is updated frequently, it may be wise to
      add an index to the foreign key column so that <literal>NO
      ACTION</literal> and <literal>CASCADE</literal> actions
      associated with the foreign key column can be more efficiently
      performed.
     </para>
    </listitem>
   </varlistentry>
   
   <varlistentry>
    <term><literal>DEFERRABLE</literal></term>
    <term><literal>NOT DEFERRABLE</literal></term>
    <listitem>
     <para>
      This controls whether the constraint can be deferred.  A
      constraint that is not deferrable will be checked immediately
      after every command.  Checking of constraints that are
      deferrable may be postponed until the end of the transaction
      (using the <xref linkend="sql-set-constraints" endterm="sql-set-constraints-title"> command).
      <literal>NOT DEFERRABLE</literal> is the default.  Only foreign
      key constraints currently accept this clause.  All other
      constraint types are not deferrable.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>INITIALLY IMMEDIATE</literal></term>
    <term><literal>INITIALLY DEFERRED</literal></term>
    <listitem>
     <para>
      If a constraint is deferrable, this clause specifies the default
      time to check the constraint.  If the constraint is
      <literal>INITIALLY IMMEDIATE</literal>, it is checked after each
      statement. This is the default.  If the constraint is
      <literal>INITIALLY DEFERRED</literal>, it is checked only at the
      end of the transaction.  The constraint check time can be
      altered with the <xref linkend="sql-set-constraints" endterm="sql-set-constraints-title"> command.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>ON COMMIT</literal></term>
    <listitem>
     <para>
      The behavior of temporary tables at the end of a transaction
      block can be controlled using <literal>ON COMMIT</literal>. 
      The three options are:

      <variablelist>
       <varlistentry>
        <term><literal>PRESERVE ROWS</literal></term>
        <listitem>
         <para>
	  No special action is taken at the ends of transactions.
	  This is the default behavior.
         </para>
     	</listitem>
       </varlistentry>
           
       <varlistentry>
        <term><literal>DELETE ROWS</literal></term>
        <listitem>
         <para>
          All rows in the temporary table will be deleted at the
          end of each transaction block.  Essentially, an automatic
	  <xref linkend="sql-truncate"> is done at each commit.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><literal>DROP</literal></term>
        <listitem>
         <para>
          The temporary table will be dropped at the end of the current
	  transaction block.
         </para>
        </listitem>
       </varlistentry>
      </variablelist>
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>    

 <refsect1 id="SQL-CREATETABLE-notes">
  <title>Notes</title>

  <itemizedlist>
   <listitem>
    <para>
     Whenever an application makes use of OIDs to identify specific
     rows of a table, it is recommended to create a unique constraint
     on the <structfield>oid</> column of that table, to ensure that
     OIDs in the table will indeed uniquely identify rows even after
     counter wraparound.  Avoid assuming that OIDs are unique across
     tables; if you need a database-wide unique identifier, use the
     combination of <structfield>tableoid</> and row OID for the
     purpose.  (It is likely that future <productname>PostgreSQL</>
     releases will use a separate OID counter for each table, so that
     it will be <emphasis>necessary</>, not optional, to include
     <structfield>tableoid</> to have a unique identifier
     database-wide.)
    </para>

    <tip>
     <para>
      The use of <literal>WITHOUT OIDS</literal> is not recommended
      for tables with no primary key, since without either an OID or a
      unique data key, it is difficult to identify specific rows.
     </para>
    </tip>
   </listitem>

   <listitem>
    <para>
     <productname>PostgreSQL</productname> automatically creates an
     index for each unique constraint and primary key constraint to
     enforce the uniqueness.  Thus, it is not necessary to create an
     explicit index for primary key columns.  (See <xref
     linkend="sql-createindex" endterm="sql-createindex-title"> for more information.)
    </para>
   </listitem>

   <listitem>
    <para>
     Unique constraints and primary keys are not inherited in the
     current implementation.  This makes the combination of
     inheritance and unique constraints rather dysfunctional.
    </para>
   </listitem>
  </itemizedlist>
 </refsect1>


 <refsect1 id="SQL-CREATETABLE-examples">
  <title>Examples</title>