summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/contrib-spi.sgml
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-04 12:17:33 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-04 12:17:33 +0000
commit5e45211a64149b3c659b90ff2de6fa982a5a93ed (patch)
tree739caf8c461053357daa9f162bef34516c7bf452 /doc/src/sgml/contrib-spi.sgml
parentInitial commit. (diff)
downloadpostgresql-15-5e45211a64149b3c659b90ff2de6fa982a5a93ed.tar.xz
postgresql-15-5e45211a64149b3c659b90ff2de6fa982a5a93ed.zip
Adding upstream version 15.5.upstream/15.5
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/src/sgml/contrib-spi.sgml')
-rw-r--r--doc/src/sgml/contrib-spi.sgml139
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..fed6f24
--- /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</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.)
+ </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> &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 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>
+ <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>