From 0fe21ad8aab03172d4ac2e790479f17edcd3dbbe Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Wed, 3 Jul 2013 21:06:20 -0400 Subject: [PATCH] doc: Add event trigger C API documentation From: Dimitri Fontaine --- doc/src/sgml/event-trigger.sgml | 224 +++++++++++++++++++++++++++++++- 1 file changed, 218 insertions(+), 6 deletions(-) diff --git a/doc/src/sgml/event-trigger.sgml b/doc/src/sgml/event-trigger.sgml index 7343227d28..8950bfde2f 100644 --- a/doc/src/sgml/event-trigger.sgml +++ b/doc/src/sgml/event-trigger.sgml @@ -37,21 +37,27 @@ The ddl_command_start event occurs just before the execution of a CREATE, ALTER, or DROP - command. As an exception, however, this event does not occur for + command. No check whether the affected object exists or doesn't exist is + performed before the event trigger fires. + As an exception, however, this event does not occur for DDL commands targeting shared objects — databases, roles, and tablespaces - — or for command targeting event triggers themselves. The event trigger + — or for commands targeting event triggers themselves. The event trigger mechanism does not support these object types. ddl_command_start also occurs just before the execution of a SELECT INTO command, since this is equivalent to - CREATE TABLE AS. The ddl_command_end - event occurs just after the execution of this same set of commands. + CREATE TABLE AS. + + + + The ddl_command_end event occurs just after the execution of + this same set of commands. The sql_drop event occurs just before the ddl_command_end event trigger for any operation that drops - database objects. To list the objects that have been dropped, use the set - returning function pg_event_trigger_dropped_objects() from your + database objects. To list the objects that have been dropped, use the + set-returning function pg_event_trigger_dropped_objects() from the sql_drop event trigger code (see ). Note that the trigger is executed after the objects have been deleted from the @@ -76,6 +82,7 @@ + Event triggers are created using the command . In order to create an event trigger, you must first create a function with the special return type event_trigger. This function need not (and may not) return a value; the return type serves merely as @@ -607,4 +614,209 @@ + + Writing Event Trigger Functions in C + + + event trigger + in C + + + + This section describes the low-level details of the interface to an + event trigger function. This information is only needed when writing + event trigger functions in C. If you are using a higher-level language + then these details are handled for you. In most cases you should + consider using a procedural language before writing your event triggers + in C. The documentation of each procedural language explains how to + write an event trigger in that language. + + + + Event trigger functions must use the version 1 function + manager interface. + + + + When a function is called by the event trigger manager, it is not passed + any normal arguments, but it is passed a context pointer + pointing to a EventTriggerData structure. C functions can + check whether they were called from the event trigger manager or not by + executing the macro: + +CALLED_AS_EVENT_TRIGGER(fcinfo) + + which expands to: + +((fcinfo)->context != NULL && IsA((fcinfo)->context, EventTriggerData)) + + If this returns true, then it is safe to cast + fcinfo->context to type EventTriggerData + * and make use of the pointed-to + EventTriggerData structure. The function must + not alter the EventTriggerData + structure or any of the data it points to. + + + + struct EventTriggerData is defined in + commands/event_trigger.h: + + +typedef struct EventTriggerData +{ + NodeTag type; + const char *event; /* event name */ + Node *parsetree; /* parse tree */ + const char *tag; /* command tag */ +} EventTriggerData; + + + where the members are defined as follows: + + + + type + + + Always T_EventTriggerData. + + + + + + tg_event + + + Describes the event for which the function is called, one of + "ddl_command_start", "ddl_command_end", + "sql_drop". + See for the meaning of these + events. + + + + + + parsetree + + + A pointer to the parse tree of the command. Check the PostgreSQL + source code for details. The parse tree structure is subject to change + without notice. + + + + + + tag + + + The command tag associated with the event for which the event trigger + is run, for example "CREATE FUNCTION". + + + + + + + + An event trigger function must return a NULL pointer + (not an SQL null value, that is, do not + set isNull true). + + + + + A Complete Event Trigger Example + + + Here is a very simple example of an event trigger function written in C. + (Examples of triggers written in procedural languages can be found in + the documentation of the procedural languages.) + + + + The function noddl raises an exception each time it is called. + The event trigger definition associated the function with + the ddl_command_start event. The effect is that all DDL + commands (with the exceptions mentioned + in ) are prevented from running. + + + + This is the source code of the trigger function: +context; + + ereport(ERROR, + (errcode(ERRCODE_INSUFFICIENT_PRIVILEGE), + errmsg("command \"%s\" denied", trigdata->tag))); + + PG_RETURN_NULL(); +} +]]> + + + + After you have compiled the source code (see ), + declare the function and the triggers: + +CREATE FUNCTION noddl() RETURNS event_trigger + AS 'noddl' LANGUAGE C; + +CREATE EVENT TRIGGER noddl ON ddl_command_start + EXECUTE PROCEDURE noddl(); + + + + + Now you can test the operation of the trigger: + +=# \dy + List of event triggers + Name | Event | Owner | Enabled | Procedure | Tags +-------+-------------------+-------+---------+-----------+------ + noddl | ddl_command_start | dim | enabled | noddl | +(1 row) + +=# CREATE TABLE foo(id serial); +ERROR: command "CREATE TABLE" denied + + + + + In this situation, in order to be able to run some DDL commands when you + need to do so, you have to either drop the event trigger or disable it. It + can be convenient to disable the trigger for only the duration of a + transaction: + +BEGIN; +ALTER EVENT TRIGGER noddl DISABLE; +CREATE TABLE foo (id serial); +ALTER EVENT TRIGGER noddl ENABLE; +COMMIT; + + (Recall that DDL commands on event triggers themselves are not affected by + event triggers.) + + -- 2.40.0