begriffs open source - ai-pg/blob - full-docs/txt/contrib-spi.txt

   1
   2 F.41. spi — Server Programming Interface features/examples #
   3
   4    F.41.1. refint — Functions for Implementing Referential Integrity
   5    F.41.2. autoinc — Functions for Autoincrementing Fields
   6    F.41.3. insert_username — Functions for Tracking Who Changed a Table
   7    F.41.4. moddatetime — Functions for Tracking Last Modification Time
   8
   9    The spi module provides several workable examples of using the Server
  10    Programming Interface (SPI) and triggers. While these functions are of
  11    some value in their own right, they are even more useful as examples to
  12    modify for your own purposes. The functions are general enough to be
  13    used with any table, but you have to specify table and field names (as
  14    described below) while creating a trigger.
  15
  16    Each of the groups of functions described below is provided as a
  17    separately-installable extension.
  18
  19 F.41.1. refint — Functions for Implementing Referential Integrity #
  20
  21    check_primary_key() and check_foreign_key() are used to check foreign
  22    key constraints. (This functionality is long since superseded by the
  23    built-in foreign key mechanism, of course, but the module is still
  24    useful as an example.)
  25
  26    check_primary_key() checks the referencing table. To use, create an
  27    AFTER INSERT OR UPDATE trigger using this function on a table
  28    referencing another table. Specify as the trigger arguments: the
  29    referencing table's column name(s) which form the foreign key, the
  30    referenced table name, and the column names in the referenced table
  31    which form the primary/unique key. To handle multiple foreign keys,
  32    create a trigger for each reference.
  33
  34    check_foreign_key() checks the referenced table. To use, create an
  35    AFTER DELETE OR UPDATE trigger using this function on a table
  36    referenced by other table(s). Specify as the trigger arguments: the
  37    number of referencing tables for which the function has to perform
  38    checking, the action if a referencing key is found (cascade — to delete
  39    the referencing row, restrict — to abort transaction if referencing
  40    keys exist, setnull — to set referencing key fields to null), the
  41    triggered table's column names which form the primary/unique key, then
  42    the referencing table name and column names (repeated for as many
  43    referencing tables as were specified by first argument). Note that the
  44    primary/unique key columns should be marked NOT NULL and should have a
  45    unique index.
  46
  47    Note that if these triggers are executed from another BEFORE trigger,
  48    they can fail unexpectedly. For example, if a user inserts row1 and
  49    then the BEFORE trigger inserts row2 and calls a trigger with the
  50    check_foreign_key(), the check_foreign_key() function will not see row1
  51    and will fail.
  52
  53    There are examples in refint.example.
  54
  55 F.41.2. autoinc — Functions for Autoincrementing Fields #
  56
  57    autoinc() is a trigger that stores the next value of a sequence into an
  58    integer field. This has some overlap with the built-in “serial column”
  59    feature, but it is not the same. The trigger will replace the field's
  60    value only if that value is initially zero or null (after the action of
  61    the SQL statement that inserted or updated the row). Also, if the
  62    sequence's next value is zero, nextval() will be called a second time
  63    in order to obtain a non-zero value.
  64
  65    To use, create a BEFORE INSERT (or optionally BEFORE INSERT OR UPDATE)
  66    trigger using this function. Specify two trigger arguments: the name of
  67    the integer column to be modified, and the name of the sequence object
  68    that will supply values. (Actually, you can specify any number of pairs
  69    of such names, if you'd like to update more than one autoincrementing
  70    column.)
  71
  72    There is an example in autoinc.example.
  73
  74 F.41.3. insert_username — Functions for Tracking Who Changed a Table #
  75
  76    insert_username() is a trigger that stores the current user's name into
  77    a text field. This can be useful for tracking who last modified a
  78    particular row within a table.
  79
  80    To use, create a BEFORE INSERT and/or UPDATE trigger using this
  81    function. Specify a single trigger argument: the name of the text
  82    column to be modified.
  83
  84    There is an example in insert_username.example.
  85
  86 F.41.4. moddatetime — Functions for Tracking Last Modification Time #
  87
  88    moddatetime() is a trigger that stores the current time into a
  89    timestamp field. This can be useful for tracking the last modification
  90    time of a particular row within a table.
  91
  92    To use, create a BEFORE UPDATE trigger using this function. Specify a
  93    single trigger argument: the name of the column to be modified. The
  94    column must be of type timestamp or timestamp with time zone.
  95
  96    There is an example in moddatetime.example.