Re: Constraint trigger doc patch

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(at)postgresql(dot)org so that your
> message can get through to the mailing list cleanly

--
Bruce Momjian bruce(at)momjian(dot)us
EnterpriseDB http://www.enterprisedb.com

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