doc/src/sgml/ref/set_constraints.sgml

   1 <!-- $PostgreSQL$ -->
   2 <refentry id="SQL-SET-CONSTRAINTS">
   3  <refmeta>
   4   <refentrytitle id="SQL-SET-CONSTRAINTS-title">SET CONSTRAINTS</refentrytitle>
   5   <refmiscinfo>SQL - Language Statements</refmiscinfo>
   6  </refmeta>
   7
   8  <refnamediv>
   9   <refname>SET CONSTRAINTS</refname>
  10   <refpurpose>set constraint checking modes for the current transaction</refpurpose>
  11  </refnamediv>
  12
  13  <indexterm zone="sql-set-constraints">
  14   <primary>SET CONSTRAINTS</primary>
  15  </indexterm>
  16
  17  <refsynopsisdiv>
  18 <synopsis>
  19 SET CONSTRAINTS { ALL | <replaceable class="parameter">name</replaceable> [, ...] } { DEFERRED | IMMEDIATE }
  20 </synopsis>
  21  </refsynopsisdiv>
  22
  23  <refsect1>
  24   <title>Description</title>
  25
  26   <para>
  27    <command>SET CONSTRAINTS</command> sets the behavior of constraint
  28    checking within the current transaction. <literal>IMMEDIATE</literal>
  29    constraints are checked at the end of each
  30    statement. <literal>DEFERRED</literal> constraints are not checked until
  31    transaction commit.  Each constraint has its own
  32    <literal>IMMEDIATE</literal> or <literal>DEFERRED</literal> mode.
  33   </para>
  34
  35   <para>
  36    Upon creation, a constraint is given one of three
  37    characteristics: <literal>DEFERRABLE INITIALLY DEFERRED</literal>,
  38    <literal>DEFERRABLE INITIALLY IMMEDIATE</literal>, or
  39    <literal>NOT DEFERRABLE</literal>. The third
  40    class is always <literal>IMMEDIATE</literal> and is not affected by the
  41    <command>SET CONSTRAINTS</command> command.  The first two classes start
  42    every transaction in the indicated mode, but their behavior can be changed
  43    within a transaction by <command>SET CONSTRAINTS</command>.
  44   </para>
  45
  46   <para>
  47    <command>SET CONSTRAINTS</command> with a list of constraint names changes
  48    the mode of just those constraints (which must all be deferrable).  The
  49    current schema search path is used to find the first matching name if
  50    no schema name is specified.  <command>SET CONSTRAINTS ALL</command>
  51    changes the mode of all deferrable constraints.
  52   </para>
  53
  54   <para>
  55    When <command>SET CONSTRAINTS</command> changes the mode of a constraint
  56    from <literal>DEFERRED</literal>
  57    to <literal>IMMEDIATE</literal>, the new mode takes effect
  58    retroactively: any outstanding data modifications that would have
  59    been checked at the end of the transaction are instead checked during the
  60    execution of the <command>SET CONSTRAINTS</command> command.
  61    If any such constraint is violated, the <command>SET CONSTRAINTS</command>
  62    fails (and does not change the constraint mode).  Thus, <command>SET
  63    CONSTRAINTS</command> can be used to force checking of constraints to
  64    occur at a specific point in a transaction.
  65   </para>
  66
  67   <para>
  68    Currently, only foreign key constraints are affected by this
  69    setting. Check and unique constraints are always effectively
  70    not deferrable. Triggers that are declared as <quote>constraint
  71    triggers</> are also affected.
  72   </para>
  73  </refsect1>
  74
  75  <refsect1>
  76   <title>Notes</title>
  77
  78   <para>
  79    This command only alters the behavior of constraints within the
  80    current transaction. Thus, if you execute this command outside of a
  81    transaction block
  82    (<command>BEGIN</command>/<command>COMMIT</command> pair), it will
  83    not appear to have any effect.
  84   </para>
  85  </refsect1>
  86
  87  <refsect1>
  88   <title>Compatibility</title>
  89
  90   <para>
  91    This command complies with the behavior defined in the SQL
  92    standard, except for the limitation that, in
  93    <productname>PostgreSQL</productname>, it only applies to
  94    foreign-key constraints.
  95   </para>
  96
  97  </refsect1>
  98 </refentry>