<!-- doc/src/sgml/contrib-spi.sgml -->

<sect1 id="contrib-spi" xreflabel="spi">
 <title>spi</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>
  <title>refint &mdash; 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.
   This module will be removed in <productname>PostgreSQL</productname> 20.)
  </para>

  <note>
   <para>
    <filename>refint</filename> requires a
    <link linkend="ddl-schemas-patterns">secure schema usage pattern</link> and
    data types where the equality operator is named <literal>=</literal>.
   </para>
  </note>

  <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>

  <note>
   <para>
    The <emphasis>referenced</emphasis> table name and column name arguments to
    <function>check_primary_key()</function> are copied as-is into internally
    generated SQL statements and therefore must be double-quoted by the user as
    necessary in the <command>CREATE TRIGGER</command> command.  See
    <xref linkend="sql-syntax-identifiers"/> for more information about quoting
    SQL identifiers.  Conversely, the <emphasis>referencing</emphasis> table
    column name arguments should not be double quoted.  See the following mock
    example of proper use of <function>check_primary_key()</function>:
<programlisting>
CREATE TRIGGER mytrigger
BEFORE INSERT OR UPDATE ON referencing_table
FOR EACH ROW EXECUTE PROCEDURE
check_primary_key (
    'column A', 'column B',         -- referencing table columns
    'myschema."referenced table"',  -- referenced table
    '"column A"', '"column B"'      -- referenced table columns
);
</programlisting>
   </para>
  </note>

  <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> &mdash; to delete the referencing row,
   <literal>restrict</literal> &mdash; to abort transaction if referencing keys
   exist, <literal>setnull</literal> &mdash; to set referencing key fields to null),
   the referenced 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>

  <note>
   <para>
    The <emphasis>referencing</emphasis> table name and column name arguments
    to <function>check_foreign_key()</function> are copied as-is into
    internally generated SQL statements and therefore must be double-quoted by
    the user as necessary in the <command>CREATE TRIGGER</command> command.
    See <xref linkend="sql-syntax-identifiers"/> for more information about
    quoting SQL identifiers.  Conversely, the <emphasis>referenced</emphasis>
    table column name arguments should not be double quoted.  See the following
    mock example of proper use of <function>check_foreign_key()</function>:
<programlisting>
CREATE TRIGGER mytrigger
BEFORE DELETE OR UPDATE ON referenced_table
FOR EACH ROW EXECUTE PROCEDURE
check_foreign_key (
    1,                              -- number of referencing tables
    'cascade',                      -- action
    'column A', 'column B',         -- referenced table columns
    'myschema."referencing table"', -- referencing table
    '"column A"', '"column B"'      -- referencing table columns
);
</programlisting>
   </para>
  </note>

  <para>
   There are examples in <filename>refint.example</filename>.
  </para>
 </sect2>

 <sect2>
  <title>autoinc &mdash; 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>
  <title>insert_username &mdash; 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>
  <title>moddatetime &mdash; 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>
