diff options
Diffstat (limited to 'doc/src/sgml/func/func-trigger.sgml')
| -rw-r--r-- | doc/src/sgml/func/func-trigger.sgml | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/doc/src/sgml/func/func-trigger.sgml b/doc/src/sgml/func/func-trigger.sgml new file mode 100644 index 00000000000..94b40adbdb8 --- /dev/null +++ b/doc/src/sgml/func/func-trigger.sgml @@ -0,0 +1,135 @@ + <sect1 id="functions-trigger"> + <title>Trigger Functions</title> + + <para> + While many uses of triggers involve user-written trigger functions, + <productname>PostgreSQL</productname> provides a few built-in trigger + functions that can be used directly in user-defined triggers. These + are summarized in <xref linkend="builtin-triggers-table"/>. + (Additional built-in trigger functions exist, which implement foreign + key constraints and deferred index constraints. Those are not documented + here since users need not use them directly.) + </para> + + <para> + For more information about creating triggers, see + <xref linkend="sql-createtrigger"/>. + </para> + + <table id="builtin-triggers-table"> + <title>Built-In Trigger Functions</title> + <tgroup cols="1"> + <thead> + <row> + <entry role="func_table_entry"><para role="func_signature"> + Function + </para> + <para> + Description + </para> + <para> + Example Usage + </para></entry> + </row> + </thead> + + <tbody> + <row> + <entry role="func_table_entry"><para role="func_signature"> + <indexterm> + <primary>suppress_redundant_updates_trigger</primary> + </indexterm> + <function>suppress_redundant_updates_trigger</function> ( ) + <returnvalue>trigger</returnvalue> + </para> + <para> + Suppresses do-nothing update operations. See below for details. + </para> + <para> + <literal>CREATE TRIGGER ... suppress_redundant_updates_trigger()</literal> + </para></entry> + </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <indexterm> + <primary>tsvector_update_trigger</primary> + </indexterm> + <function>tsvector_update_trigger</function> ( ) + <returnvalue>trigger</returnvalue> + </para> + <para> + Automatically updates a <type>tsvector</type> column from associated + plain-text document column(s). The text search configuration to use + is specified by name as a trigger argument. See + <xref linkend="textsearch-update-triggers"/> for details. + </para> + <para> + <literal>CREATE TRIGGER ... tsvector_update_trigger(tsvcol, 'pg_catalog.swedish', title, body)</literal> + </para></entry> + </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <indexterm> + <primary>tsvector_update_trigger_column</primary> + </indexterm> + <function>tsvector_update_trigger_column</function> ( ) + <returnvalue>trigger</returnvalue> + </para> + <para> + Automatically updates a <type>tsvector</type> column from associated + plain-text document column(s). The text search configuration to use + is taken from a <type>regconfig</type> column of the table. See + <xref linkend="textsearch-update-triggers"/> for details. + </para> + <para> + <literal>CREATE TRIGGER ... tsvector_update_trigger_column(tsvcol, tsconfigcol, title, body)</literal> + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + The <function>suppress_redundant_updates_trigger</function> function, + when applied as a row-level <literal>BEFORE UPDATE</literal> trigger, + will prevent any update that does not actually change the data in the + row from taking place. This overrides the normal behavior which always + performs a physical row update + regardless of whether or not the data has changed. (This normal behavior + makes updates run faster, since no checking is required, and is also + useful in certain cases.) + </para> + + <para> + Ideally, you should avoid running updates that don't actually + change the data in the record. Redundant updates can cost considerable + unnecessary time, especially if there are lots of indexes to alter, + and space in dead rows that will eventually have to be vacuumed. + However, detecting such situations in client code is not + always easy, or even possible, and writing expressions to detect + them can be error-prone. An alternative is to use + <function>suppress_redundant_updates_trigger</function>, which will skip + updates that don't change the data. You should use this with care, + however. The trigger takes a small but non-trivial time for each record, + so if most of the records affected by updates do actually change, + use of this trigger will make updates run slower on average. + </para> + + <para> + The <function>suppress_redundant_updates_trigger</function> function can be + added to a table like this: +<programlisting> +CREATE TRIGGER z_min_update +BEFORE UPDATE ON tablename +FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger(); +</programlisting> + In most cases, you need to fire this trigger last for each row, so that + it does not override other triggers that might wish to alter the row. + Bearing in mind that triggers fire in name order, you would therefore + choose a trigger name that comes after the name of any other trigger + you might have on the table. (Hence the <quote>z</quote> prefix in the + example.) + </para> + </sect1> |