Re: Constraint trigger doc patch - Mailing list pgsql-patches

Patch applied.  Thanks.  Your documentation changes can be viewed in
five minutes using links on the developer's page,
http://www.postgresql.org/developer/testing.


---------------------------------------------------------------------------


Michael Glaesemann wrote:
> (Fifth attempt: diff inline)
> (And a fourth attempt, from another account...)
> (Third time's the charm?)
> (Resent as I sent this yesterday but haven't seen it on the list yet
> or in the online archives. Apologies if it ends up double-posting.)
>
> Please find attached a doc patch for CREATE CONSTRAINT TRIGGER. The
> documentation here has always been sparse, as the command isn't
> intended for general use. However, in its current form its a bit
> *too* sparse. For example, it mentions constraint attributes but
> doesn't say what those might be or where to look for information for
> details. The patch lists attribute options and provides references to
> where those options are described.
>
> When looking in gram.y while trying to figure out what exactly was
> meant by "actual constraint specification", I discovered
> OptConstrFromTable. I assume this means Optional Constraint From
> Table and it looks like it's used to specify the referenced table a
> foreign key constraint. I couldn't figure out how to meaningfully use
> it and have left the description purposefully vague.
>
> I don't have a working DocBook tool chain on my system, so I haven't
> been able to check if it builds properly. I tried to be conscientious
> about my formatting, but some SGML bugs may have crept in.
>
> Thanks!
>
> Michael Glaesemann
> grzm myrealbox com
>
> Index: doc/src/sgml/ref/create_constraint.sgml
> ===================================================================
> RCS file: /projects/cvsroot/pgsql/doc/src/sgml/ref/
> create_constraint.sgml,v
> retrieving revision 1.14
> diff -c -r1.14 create_constraint.sgml
> *** doc/src/sgml/ref/create_constraint.sgml    16 Sep 2006 00:30:17
> -0000    1.14
> --- doc/src/sgml/ref/create_constraint.sgml    7 Oct 2006 03:53:18 -0000
> ***************
> *** 21,29 ****
>     <refsynopsisdiv>
>    <synopsis>
>    CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</
> replaceable>
> !     AFTER <replaceable class="parameter">events</replaceable> ON
> !     <replaceable class="parameter">tablename</replaceable>
> <replaceable class="parameter">constraint</replaceable> <replaceable
> class="parameter">attributes</replaceable>
> !     FOR EACH ROW EXECUTE PROCEDURE <replaceable
> class="parameter">funcname</replaceable> ( <replaceable
> class="parameter">args</replaceable> )
>    </synopsis>
>     </refsynopsisdiv>
>
> --- 21,32 ----
>     <refsynopsisdiv>
>    <synopsis>
>    CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</
> replaceable>
> !     AFTER <replaceable class="parameter">event [ OR ... ]</
> replaceable>
> !     ON <replaceable class="parameter">table_name</replaceable>
> !     [ FROM <replaceable class="parameter">referenced_table_name</
> replaceable> ]
> !     { NOT DEFERRABLE | [ DEFERABBLE ] { INITIALLY IMMEDIATE |
> INITIALLY DEFERRED } }
> !     FOR EACH ROW
> !     EXECUTE PROCEDURE <replaceable class="parameter">funcname</
> replaceable> ( <replaceable class="parameter">arguments</replaceable> )
>    </synopsis>
>     </refsynopsisdiv>
>
> ***************
> *** 33,102 ****
>      <para>
>       <command>CREATE CONSTRAINT TRIGGER</command> is used within
>       <command>CREATE TABLE</command>/<command>ALTER TABLE</command>
> and by
> !    <application>pg_dump</application>  to  create  the  special
> triggers  for
> !    referential  integrity.
>       It is not intended for general use.
>      </para>
>     </refsect1>
>
>     <refsect1>
> !    <title>Parameters</title>
> !
> !     <variablelist>
> !      <varlistentry>
> !       <term><replaceable class="PARAMETER">name</replaceable></term>
> !       <listitem>
> !        <para>
> !     The name of the constraint trigger.
> !        </para>
> !       </listitem>
> !      </varlistentry>
> !
> !      <varlistentry>
> !       <term><replaceable class="PARAMETER">events</replaceable></term>
> !       <listitem>
> !        <para>
> !     The event categories for which this trigger should be fired.
> !        </para>
> !       </listitem>
> !      </varlistentry>
> !
> !      <varlistentry>
> !       <term><replaceable class="PARAMETER">tablename</replaceable></
> term>
> !       <listitem>
> !        <para>
> !     The name (possibly schema-qualified) of the table in which
> !     the triggering events occur.
> !        </para>
> !       </listitem>
> !      </varlistentry>
> !
> !      <varlistentry>
> !       <term><replaceable class="PARAMETER">constraint</
> replaceable></term>
> !       <listitem>
> !        <para>
> !     Actual constraint specification.
> !        </para>
> !       </listitem>
> !      </varlistentry>
> !
> !      <varlistentry>
> !       <term><replaceable class="PARAMETER">attributes</
> replaceable></term>
> !       <listitem>
> !        <para>
> !     The constraint attributes.
> !        </para>
> !       </listitem>
> !      </varlistentry>
> !
> !      <varlistentry>
> !       <term><replaceable class="PARAMETER">funcname</replaceable>
> (<replaceable class="PARAMETER">args</replaceable>)</term>
> !       <listitem>
> !        <para>
> !     The function to call as part of the trigger processing.
> !        </para>
> !       </listitem>
> !      </varlistentry>
> !     </variablelist>
>     </refsect1>
>    </refentry>
> --- 36,128 ----
>      <para>
>       <command>CREATE CONSTRAINT TRIGGER</command> is used within
>       <command>CREATE TABLE</command>/<command>ALTER TABLE</command>
> and by
> !    <application>pg_dump</application> to create the special
> triggers for
> !    referential integrity.
>       It is not intended for general use.
>      </para>
>     </refsect1>
>
>     <refsect1>
> !   <title>Parameters</title>
> !
> !   <variablelist>
> !    <varlistentry>
> !     <term><replaceable class="PARAMETER">name</replaceable></term>
> !     <listitem>
> !      <para>
> !       The name of the constraint trigger. The actual name of the
> !       created trigger will be of the form
> !       <literal>RI_ConstraintTrigger_0000<literal> (where 0000 is
> some number
> !       assigned by the server).
> !       Use this assigned name is when dropping the constraint.
> !      </para>
> !     </listitem>
> !    </varlistentry>
> !
> !    <varlistentry>
> !     <term><replaceable class="PARAMETER">events</replaceable></term>
> !     <listitem>
> !      <para>
> !       One of <literal>INSERT</literal>, <literal>UPDATE</literal>, or
> !       <literal>DELETE</literal>; this specifies the event that will
> fire the
> !       trigger. Multiple events can be specified using
> <literal>OR<literal>.
> !      </para>
> !     </listitem>
> !    </varlistentry>
> !
> !    <varlistentry>
> !     <term><replaceable class="PARAMETER">table_name</replaceable></
> term>
> !     <listitem>
> !      <para>
> !       The (possibly schema-qualified) name of the table in which
> !       the triggering events occur.
> !      </para>
> !     </listitem>
> !    </varlistentry>
> !
> !    <varlistentry>
> !     <term><replaceable class="PARAMETER">referenced_table_name</
> replaceable></term>
> !     <listitem>
> !      <para>
> !       The (possibly schema-qualified) name of the table referenced
> by the
> !       constraint. Used by foreign key constraints triggers.
> !      </para>
> !     </listitem>
> !    </varlistentry>
> !
> !    <varlistentry>
> !     <term><literal>DEFERRABLE</literal></term>
> !     <term><literal>NOT DEFERRABLE</literal></term>
> !     <term><literal>INITIALLY IMMEDIATE</literal></term>
> !     <term><literal>INITIALLY DEFERRED</literal></term>
> !     <listitem>
> !      <para>
> !       See the <xref linkend="SQL-CREATETABLE" endterm="SQL-
> CREATETABLE-TITLE">
> !       documentation for details of these constraint options.
> !      </para>
> !     </listitem>
> !    </varlistentry>
> !
> !    <varlistentry>
> !     <term><replaceable class="PARAMETER">funcname</replaceable>
> (<replaceable class="PARAMETER">args</replaceable>)</term>
> !     <listitem>
> !      <para>
> !       The function to call as part of the trigger processing. See
> <xref
> !       linkend="SQL-CREATETRIGGER" endterm="SQL-CREATETRIGGER-
> TITLE"> for
> !       details.
> !      </para>
> !     </listitem>
> !    </varlistentry>
> !   </variablelist>
>     </refsect1>
> +
> +  <refsect1 id="SQL-CREATECONSTRAINT">
> +   <title>Compatibility</title>
> +   <para>
> +    <command>CREATE CONTRAINT TRIGGER</command> is a
> +    <productname>PostgreSQL</productname> extension of the
> <acronym>SQL</>
> +    standard.
> +   </para>
> +  </refsect1>
> +
>    </refentry>
>
>
> ---------------------------(end of broadcast)---------------------------
> TIP 1: if posting/reading through Usenet, please send an appropriate
>        subscribe-nomail command to majordomo@postgresql.org so that your
>        message can get through to the mailing list cleanly

--
  Bruce Momjian   bruce@momjian.us
  EnterpriseDB    http://www.enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +