diff options
Diffstat (limited to 'doc/src/sgml/contrib-spi.sgml')
| -rw-r--r-- | doc/src/sgml/contrib-spi.sgml | 139 |
1 files changed, 139 insertions, 0 deletions
diff --git a/doc/src/sgml/contrib-spi.sgml b/doc/src/sgml/contrib-spi.sgml new file mode 100644 index 0000000..e7cae4e --- /dev/null +++ b/doc/src/sgml/contrib-spi.sgml @@ -0,0 +1,139 @@ +<!-- doc/src/sgml/contrib-spi.sgml --> + +<sect1 id="contrib-spi" xreflabel="spi"> + <title>spi — Server Programming Interface features/examples</title> + + <indexterm zone="contrib-spi"> + <primary>SPI</primary> + <secondary>examples</secondary> + </indexterm> + + <para> + The <application>spi</application> module provides several workable examples + of using the <link linkend="spi">Server Programming Interface</link> + (<acronym>SPI</acronym>) and triggers. While these functions are of + some value in + their own right, they are even more useful as examples to modify for + your own purposes. The functions are general enough to be used + with any table, but you have to specify table and field names (as described + below) while creating a trigger. + </para> + + <para> + Each of the groups of functions described below is provided as a + separately-installable extension. + </para> + + <sect2 id="contrib-spi-refint"> + <title>refint — Functions for Implementing Referential Integrity</title> + + <para> + <function>check_primary_key()</function> and + <function>check_foreign_key()</function> are used to check foreign key constraints. + (This functionality is long since superseded by the built-in foreign + key mechanism, of course, but the module is still useful as an example.) + </para> + + <para> + <function>check_primary_key()</function> checks the referencing table. + To use, create a <literal>BEFORE INSERT OR UPDATE</literal> trigger using this + function on a table referencing another table. Specify as the trigger + arguments: the referencing table's column name(s) which form the foreign + key, the referenced table name, and the column names in the referenced table + which form the primary/unique key. To handle multiple foreign + keys, create a trigger for each reference. + </para> + + <para> + <function>check_foreign_key()</function> checks the referenced table. + To use, create a <literal>BEFORE DELETE OR UPDATE</literal> trigger using this + function on a table referenced by other table(s). Specify as the trigger + arguments: the number of referencing tables for which the function has to + perform checking, the action if a referencing key is found + (<literal>cascade</literal> — to delete the referencing row, + <literal>restrict</literal> — to abort transaction if referencing keys + exist, <literal>setnull</literal> — to set referencing key fields to null), + the triggered table's column names which form the primary/unique key, then + the referencing table name and column names (repeated for as many + referencing tables as were specified by first argument). Note that the + primary/unique key columns should be marked NOT NULL and should have a + unique index. + </para> + + <para> + There are examples in <filename>refint.example</filename>. + </para> + </sect2> + + <sect2 id="contrib-spi-autoinc"> + <title>autoinc — Functions for Autoincrementing Fields</title> + + <para> + <function>autoinc()</function> is a trigger that stores the next value of + a sequence into an integer field. This has some overlap with the + built-in <quote>serial column</quote> feature, but it is not the same: + <function>autoinc()</function> will override attempts to substitute a + different field value during inserts, and optionally it can be + used to increment the field during updates, too. + </para> + + <para> + To use, create a <literal>BEFORE INSERT</literal> (or optionally <literal>BEFORE + INSERT OR UPDATE</literal>) trigger using this function. Specify two + trigger arguments: the name of the integer column to be modified, + and the name of the sequence object that will supply values. + (Actually, you can specify any number of pairs of such names, if + you'd like to update more than one autoincrementing column.) + </para> + + <para> + There is an example in <filename>autoinc.example</filename>. + </para> + + </sect2> + + <sect2 id="contrib-spi-insert-username"> + <title>insert_username — Functions for Tracking Who Changed a Table</title> + + <para> + <function>insert_username()</function> is a trigger that stores the current + user's name into a text field. This can be useful for tracking + who last modified a particular row within a table. + </para> + + <para> + To use, create a <literal>BEFORE INSERT</literal> and/or <literal>UPDATE</literal> + trigger using this function. Specify a single trigger + argument: the name of the text column to be modified. + </para> + + <para> + There is an example in <filename>insert_username.example</filename>. + </para> + + </sect2> + + <sect2 id="contrib-spi-moddatetime"> + <title>moddatetime — Functions for Tracking Last Modification Time</title> + + <para> + <function>moddatetime()</function> is a trigger that stores the current + time into a <type>timestamp</type> field. This can be useful for tracking + the last modification time of a particular row within a table. + </para> + + <para> + To use, create a <literal>BEFORE UPDATE</literal> + trigger using this function. Specify a single trigger + argument: the name of the column to be modified. + The column must be of type <type>timestamp</type> or <type>timestamp with + time zone</type>. + </para> + + <para> + There is an example in <filename>moddatetime.example</filename>. + </para> + + </sect2> + +</sect1> |