sanerots (Chapter 20. Evert Scheer Chapter 20. Event Scheduler Prev Next Chapter 20. Event Scheduler Table of Contents 20.1, Event Scheduler Overview 20.2. Event Scheduler Syntax 20.2.1, CREATE EVENT Syntax 20.2.2. ALTER EVENT Syntax 20.2.3, DROP EVENT 20.3. Event Metadata This chapter describes the MySQL Event Scheduler, for which support was added in MySQL 5.1.6, and is divided into the following sections: ction 20.1, “Event Scheduler Overview" provides an introduction to and conceptual overview of MySQL Events Section 20.2, “Event Scheduler Syntax" discusses the SQL commands introduced in MySQL 5.16 for creating, altering, and dropping MySQL Events. Section 20.3, “Event Metadata” shows how to obtain information about events and how this information is stored by the MySQL Server. Section 20.5, “The Event Scheduler and MySQL Privileges” discusses the privileges required to work with events and the ramifications that events have with regard to privileges when executing. Section 20.6, “Event Scheduler Limitations and Restriction: limitations of MySQL’s Event Scheduler implementation. describes the restrictions and Additional Resources: + You may find the MySQL Event Scheduler User Forum of use when working with events. Here you can discuss the MySQL Event Scheduler with other MySQL users and the MySQL developers. 20.1. Event Scheduler Overview MySQL Events are tasks that run according to a schedule. Therefore, we sometimes refer to them as scheduled events. When you create an event, you are creating a named database object containing ‘one or more SQL statements to be executed at one or more regular intervals, beginning and ending ipsstwunw.s duke ediesldoesimysq-rtmarvovents Nl wrsanerots (Chapter 20. Evert Scheer at a specific date and time. Conceptually, this is similar to the idea of the Unix crontab (also known as a “cron job") or the Windows Task Scheduler. Scheduled tasks of this type are also sometimes known as “temporal triggers”, implying that these are objects that are triggered by the passage of time. While this is essentially correct, we prefer to use the term events in order to avoid confusion with triggers of the type discussed in Chapter 19, Triggers. Events should more specifically not be confused with ‘temporary triggers’. Whereas a trigger is a database object whose statements are executed in response to a specific type of event that occurs on a given table, a (scheduled) event is an object whose statements are executed in response to the passage of a specified time interval. While there is no provision in the SQL Standard for event scheduling, there are precedents in other database systems, and you may notice some similarities between these implementations and that found in the MySQL Server. MySQL Events have the following major features and properties: + In MySQL 5.1.12 and later, an event is uniquely identified by its name and the schema to which itis assigned, (Previously, an event was also unique to its definer.) + An event performs a specific action according to a schedule. This action consists of an SQL ‘statement, which can be a compound statement in a BEGIN END block if desired (see Section 18.2.5, "BEGIN... END Compound Statement Syntax’). An event's timing can be either one-time or recurrent. A one-time event executes one time only. A recurrent event repeats its action at a regular interval, and the schedule for a recurring event can be assigned a specific start day and time, end day and time, both, or neither. (By default, a recurring event's schedule begins as soon as it is created, and continues indefinitely, until it is disabled or dropped.) + Users can create, modify, and drop scheduled events using SQL statements intended for these purposes. Syntactically invalid event creation and modification statements fail with an appropriate error message. A user may include statements in an event's action which require privileges that the user does not actually have. The event creation or modification statement succeeds but the event's action fails. See Section 20.5. “The Event Scheduler and M Privileges" for details. + Many of the properties of an event can be set or modified using SQL statements. These properties include the event's name, timing, persistence (that is, whether it is preserved following the expiration of its schedule), status (enabled or disabled), action to be performed, and the schema to which it is assigned. See Section 20.2.2, “ALTER EVENT Syntax’ The definer of an event is the user who created the event, unless the event has been altered, in which case the definer is the user who issued the last ALTER EVENT statement effecting that event. An event can be modified by any user having the EVENT privilege on the database for which the event is defined. (Prior to MySQL 5.1.12, only an event's definer, or a user having Privileges on the mysql. event table, could modify a given event.) See Section 20.5, “The Event ‘Scheduler and MySQL Privileges’ + An event's action statement may include most SQL statements permitted within stored routines. Events are executed by a special event scheduler thread; when we refer to the Event Scheduler, we actually refer to this thread. When running, the event scheduler thread and its current state can be seen by users having the SUPER privilege in the output of stow PROCESSLIS?, as shown in the discussion that follows ipsstwunw.s duke ediesldoesimysq-rtmarvovents Nl ansanerots (Chapter 20. Evert Scheer The global variable event_scheduler determines whether the Event Scheduler is enabled and running on the server. Beginning with MySQL 5.1.12, it has one of these 3 values, which affect event scheduling as described here: + OFF: The Event Scheduler is stopped. The event scheduler thread does not run, is not shown in the output of stow PROCESSLIST, and no scheduled events are executed. OFF is the default value for event_scheduler, When the Event Scheduler is stopped (event_scheduler is oF), it can be started by setting the value of event_scheduler to on. (See next item.) + oN: The Event Scheduler is started; the event scheduler thread runs and executes all scheduled events. When the Event Scheduler is on, the event scheduler thread is listed in the output of How PROCESSLIST as a daemon process, and its state is represented as shown here: mysql> SHOW PROCESSLIST\G root. localhost : show processlist event_scheduler localhost Waiting for next activation Info: W 2 rows in set (0.00 sec) Event scheduling can be stopped by setting the value of event_scheduler to OFF, + DISABLED: This value renders the Event Scheduler non-operational. When the Event Scheduler is DISABLED, the event scheduler thread does not run (and so does not appear in the output of SHOW PROCESSLIST) When the server is runningevent_scheduler can be toggled between on and oF (using ser). Itis also possible to use 0 for oF, and 1 for on when setting this variable. Thus, any of the following 4 statements can be used in the myso2 client to turn on the Event Scheduler: SET GLOBAL event_scheduler = 0} SET @@global.event_scheduler = 01 SET 1 83 . Similarly, any of these 4 statements can be used to turn off the Event Scheduler: ipsstwunw.s duke ediesldoesimysq-rtmarvovents Nl anvsanerots (Chapter 20. Evert Scheer SET GLOBAL, event_schedu obal.event_scheduler = OFF; yent_scheduler = 0; obal.event_scheduler = 0; OFF; Although on and orF have numeric equivalents, the value displayed for event_scheduler by SELECT Of SHOW VARIABLES is always one of OFF, ON, of DISABLED. DISABLED has no numeric equivalent. For this reason, on and OFF are usually preferred over 1 and 0 when setting this variable. Note that attempting to set event_scheduler without specifying it as a global variable causes an error: mysql< SET @@event_sched OFF; ERROR 1229 (HYO00): Variable 'event_sche: e and should be set with SET GLOBAL ler is a GLOBAL Important: Itis not possible to enable or disable the Event Scheduler when the server is running That is, you can change the value of event_scheduler to DISABLED — or from DISABLED to one of the other permitted values for this option — only when the server is stopped. Attempting to do so when the server is running fails with an error. To disable the event scheduler, use one of the following two methods: «As. command-line option when starting the server: event-scheduler-DISABLED + Inthe server configuration file (my. cn, or my. ini on Windows systems), include the line where it will be read by the server (for example, ina [mysqld] section): event_scheduler=DISABLED To enable the Event Scheduler, restart the server without the --event-scheduler=DISABLED ‘command line option, or after removing or commenting out the line containing event_scheduler=DISABLED in the server configuration file, as appropriate. Alternatively, you can use ON (or 1) or OFF (or 0) in place of the DISABLED value when starting the server. Note: You can issue event-manipulation statements when event_scheduler is set to DISABLED. No warnings or errors are generated in such cases (provided that the statements are themselves valid). However, scheduled events cannot execute until this variable is set to on (or 1). Once this has been done, the event scheduler thread executes all events whose scheduling conditions are satisfied, In MySQL 5.1.11, event_scheduier behaved as follows: this variable could take one of the values 0 (or OFF), 1 (oF oN), of 2. Setting it to 0 turned event scheduling off, so that the event scheduler thread did not run; the event_scheduler variable could not be set to this value while the server was running. Setting it to 1 so that the event scheduler thread ran and executed scheduled events. In this state, the event scheduler thread appeared to be sleeping when viewed with sow PROCESSLIST, When event_scheduler was set to 2 (which was the default value), the Event Scheduler was considered to be “suspended”; the event scheduler thread ran and could be seen in the output of SHOW PROCESSLIST (where Suspended was displayed in the State column), but did not execute any scheduled events. The value of event_scheduler could be changed only between 1 (or on) and 2 while the server was running. Setting it to 0 (or OFF) required a server restart, as did changing its value from 0 (or OFF) to 1 (or ON) or 2. ipsstwunw.s duke ediesldoesimysq-rtmarvovents Nl anrans2016 Chapter 20. Evert Schedder Prior to MySQL 5.1.11, event_scheduler could take one of only the 2 values o|oFF or 1[on, and the default value was 0|oFr. It was also possible to start and stop the event scheduler thread while the MySQL server was running For more information concerning the reasons for these changes in behaviour, see Bug##17619. For SQL statements used to create, alter, and drop events, see Section 20.2, “Event Scheduler Syntax’ MySQL 5.1.6 and later provides an zvenrs table in the INFORMATION_scHEMA database. This table can be queried to obtian information about scheduled events which have been defined on the server. See Section 20.3, “Event Metadata’, and Section 22.20, “The INFORMATION SCHEMA EVENTS Table’, for more information. For information regarding event scheduling and the MySQL privilege system, see Section 20.5, “The Event h rand My L Privil - 20.2. Event Scheduler Syntax 20.2.1, CREATE EVENT Syntax 20.2.2. ALTER EVENT Syntax 20.2.3, DROP EVENT Syntax MySQL 5.1.6 and later provides several SQL statements for working with scheduled events: + New events are defined using the CREATE EVENT statement. See Section 20.2.1, “CREATE EVENT Syntax" + The definition of an existing event can be changed by means of the ALTER EVENT statement. See Section 20.2.2, "ALTER EVENT Syntax’ + When a scheduled event is no longer wanted or needed, it can be deleted from the server by its, definer using the DRoP EVENT statement. See Section 20.2.3, ‘DROP EVENT Syntax", (Whether an event persists past the end of its schedule also depends on its oN COMPLETION clause, if it has one. See Section 20.2.1, “CREATE EVENT Syntax”.) An event can be deleted by any user having the Even privilege for the database on which the event is defined. Prior to MySQL 5.12, a user other than the definer required privileges on the mysql. event table, See Section 20.5, “The Event Scheduler and MySQL Privileges". 20.2.1. CREATE EVENT Syntax (+ INTERVAL in ipsstwunw.s duke ediesldoesimysq-rtmarvovents Nl sisanerots (Chapter 20. Evert Scheer EVERY (STAR 1 [enps ¢- quantity (YEAR | QUARTER | MONTH | DAY | HOUR | MINUTE | WEEK | SECOND | YEAR MONTH | DAY HOUR | DAY MINUTE | DAY SECOND | HOUR MINUTE | HOUR SECOND | MINUT# SECOND) This statement creates and schedules a new event. The minimum requirements for a valid CREATE EVENT statement are as follows: + The keywords CREATE EVEN? plus an event name, which uniquely identifies the event in the current schema. (Prior to MySQL 5.1.12, the event name needed to be unique only among events created by the same user on a given database.) * An OW SCHEDULE clause, which determines when and how often the event executes. * Apo clause, which contains the SQL statement to be executed by an event. This is an example of a minimal CREATE EVENT statement: CREATE EVENT myevent ON SCHEDULE AP CURRENT TIMESTAMP + INTERVAL 1 HOUR D0 UPDATE myschema.mytable SET mycol = mycol + 1; The previous statement creates an event named myevent. This event executes once — one hour following its creation — by running an SQL statement that increments the value of the myschema mmytable table's mycol column by 1 The event_name must be a valid MySQL identifier with a maximum length of 64 characters. It may be delimited using back ticks, and may be qualified with the name of a database schema. An event is associated with both a MySQL user (the definer) and a schema, and its name must be unique among names of events within that schema, In general, the rules governing event names are the same as those for names of stored routines. See tion 9,2, “Identifiers”. If no schema is indicated as part of event_name, then the default (current) schema is assumed, The definer is always the current MySQL user. (Prior to MySQL 5.1.12, it was possible for two different users to create different events having the same name on the same database schema.) Note: MySQL uses case-insensitive comparisons when checking for the uniqueness of event names. This means that, for example, you cannot have two events named myevent and Myzvent in the same database schema IF No? EXISTS functions in the much the same fashion with CREATE EVENT as it does when used with a CREATE TABLE statement; if an event named event_name already exists in the same schema, no action is taken, and no error results. (However, a warning is generated.) The ON SCHEDULE clause determines when, how often, and for how long the sq1_statement defined for the event repeats. This clause takes one of two forms: ipsstwunw.s duke ediesldoesimysq-rtmarvovents Nl a7sanerots (Chapter 20. Evert Scheer ears amp is used for a one-time event. It specifies that the event executes one time only at the date and time, given as the ¢. amp, which must include both the date and time, or must be an expression that resolves to a datetime value. You may use a value which is of either the DATETIME or TIMESTAMP type for this purpose. The ¢ imest.amp must also be in the future — you cannot schedule an event to take place in the past. Trying to do so fails with an error, as shown here: mysql> SELECT Now (); | Now.) 1 row in set (0.04 sec) mysql> cl TE EVENT e to SCHEDULE AT '2006-02-10 23:59:00" IN! NTO t 8 (MOM (Is ERROR 1522 (HYOOO): Activation (AT) time is in the past CREATE EVENT statements which are themselves invalid — for whatever reason — fail with an error. You may use CURRENT_TIMESTAMP to specify the current date and time. In such a case, the event acts as soon as it is created. In order to create an event which occurs at some point in the future relative to the current date and time — such as that expressed by the phrase “three weeks from now” — you can use the optional clause + INTERVAL incerval. The interval portion consists of two parts, a quantity and a unit of time, and follows the same syntax rules that govern intervals used in the DATE_ADD () function (see Section 12.5, *Date and Time Functions", The units keywords are also the same, except that you cannot use any units involving microseconds when defining an event You can also combine intervals. For example, AT CURRENT_TIMESTAMP + INTERVAL 3 WEEK + INTERVAL 2 DAY is equivalent to “three weeks and two days from now’. Each portion of such a clause must begin with + INTERVAL. + For actions which are to be repeated at a regular interval, you can use an Every clause. The EVERY keyword is followed by an interval as described in the previous dicussion of the AT keyword. (+ INTERVAL is not used with EVERY.) For example, EVERY 6 WEEK means “every six week It is not possible to combine + INTERVAL clauses in a single EVERY clause; however, you can use the same complex time units allowed ina + INTERVAL. For example, “every two minutes and ten seconds" can be expressed as EVERY '2:10' MINUTE_SECOND. An every clause may also contain an optional srarrs clause. sTaRTs is followed by a imestanp value which indicates when the action should begin repeating, and may also use + INTERVAL inte:val in order to specify an amount of time “from now’. For example, EVERY 3 MONTH STARTS CURRENT TIMESTAMP + 1 WEEK means “every three months, beginning one week from now’. Similarly, you can express “every two weeks, beginning six hours and fifteen minutes from now” as EVERY 2 WEEK STARTS CURRENT_TIMESTAMP + '6:15' HOUR_MINUTE, Not specifying STARTS is the same as using STARTS CURRENT_TIMESTAMP — ipsstwunw.s duke ediesldoesimysq-rtmarvovents Nl m7sanerots (Chapter 20. Evert Scheer that is, the action specified for the event begins repeating immediately upon creation of the event An EVERY clause may also contain an optional ENDS clause. The ENDS keyword is followed by a *imestanp value which tells MySQL when the event should stop repeating. You may also use + INTERVAL interval with ENDS; for instance, EVERY 12 HOUR STARTS CURRENT_TIMESTAMP + INTERVAL 30 MINUTE ENDS CURRENT TIMESTAMP + INTERVAL 4 WEEK is equivalent to “every twelve hours, beginning thirty minutes from now, and ending four weeks from now’. Not using ENDS means that the event continues executing indefinitely. ENDS supports the same syntax for complex time units as STARTS does. You may use STARTS, ENDS, both, or neither in an EVERY clause. Note: Where STARTS or ENDS is given as a datetime value, it is taken to mean local time on the server. However, the values for both of these are currently reported using Universal Time in the INFORMATION SCHEMA. EVENTS and mysql. event tables, as well as in the output from sHow EVENTS, This is not intended behaviour and your application should not rely on it, as itis subject to change (Bug#16420). For additional information, see Section 22.20. “The INFORMATION SCHEMA EVENTS Table’. The on SCHEDULE clause may use expressions involving builtin MySQL functions and user variables to obtain any of the timestamp or interval values which it contains. You may not use stored routines or user-defined functions in such expressions, nor may you use any table references; however, you may use SELECT FROM DUAL. This is true for both CREATE EVENT and ALTER EVENT statements. Beginning with MySQL 5.1.13, references to stored routines, user-defined functions, and tables in such cases is specifically disallowed, and fail with an error (see Bug#22830), Normally, once an event has expired, it is immediately dropped. You can override this behavior by specifying ON COMPLETION PRESERVE. Using ON COMPLETION NOT PRESERVE merely makes the default non-persistent behavior explicit. You can create an event but keep it from being active using the DISABLE keyword, Alternatively, you may use ENABLE to make explicit the default status, which is active. This is most useful in conjunction with ALTER EVENT (see Section 20.2.2, ‘ALTER EVENT Syntax’). You may supply a comment for an event using a CoMMENT clause. comment may be any string of up to 64 characters that you wish to use for describing the event. The comment text, being a string literal, must be surrounded by quotation marks. The Do clause specifies an action carried by the event, and consists of an SQL statement. Nearly any valid MySQL statement which can be used in a stored routine can also be used as the action statement for a scheduled event. (See Section J.1, “Restrictions on Stored Routines and Triggers”) For example, the following event ¢_hourly deletes all rows from the sessions table once per hour, where this table is part of the site activity schema: REATE EVENT © hourly ON SCHEDU! EVERY 1 comme bo DELETE OR ars out sessions table each hour.' ROM site activity.sessions; ipsstwunw.s duke ediesldoesimysq-rtmarvovents Nl a7sanerots (Chapter 20. Evert Scheer MySQL stores the sqi_mode system variable setting that is in effect at the time an event is created, and always executes the event with this setting in force, regardless of the current server SQL mode. ACREATE EVENT statement that contains an ALTER EVENT statement in its Do clause appears to succeed; however, when the server attempts to execute the resulting scheduled event, the execution fails with an error. Note: The suow statement and sExzcr statements that merely return a result set have no effect when used in an event; the output from these is not sent to the MySQL Monitor, nor is it stored anywhere. However, you can use statements such as SELECT INTO and INSERT ... SELECT that store a result. (See the next example in this section for an instance of the latter.) Any reference in the Do clause to a table in other than the same database schema to which the event belongs must be qualified with the name of the schema in which the table occurs. (In MySQL 5.1.6, all tables referenced in event Do clauses had to include a reference to the database.) As with stored routines, you can use multiple statements in the Do clause by bracketing them with the BEGIN and END keywords, as shown here: DELIMITER CREATE EVENT e daily ON SCHEDU EVERY 1 ‘saves total number of sessions then clears the table each day." ERT INTO site acti SELECT CURRENT TIMESTA FROM site DELETE FROM s. -totals (when, total) » COUNT (*) y-sessions; y-sessions; mM Note the use of the DELIMITER statement to change the statement delimiter, as with stored routines. ‘See Section 18,2,1, “CREATE PROCEDURE and CREATE TION More complex compound statements, such as those used in stored routines, are possible in an event. This example uses local variables, an error handler, and a flow control construct: DELIMITER CREATE EVENT e ON SCHEDULE EVERY 5 SECOND Bo BEGIN DECLARE v INTEGER; DECLARE CONTINUE FANDLER FOR SQLEXC! ON BEGIN ERT INTO tl VALUES (0); ATE t2 SET sl +1; ipsshwurw.s duke ediesldoesimysq-rtmarvovents Nl a7sanerots (Chapter 20. Evert Scheer se v= v4]; BND WHILE? END DELIMITER ; There is no way to pass parameters directly to or from event stored routine with parameters: \owever, it is possible to invoke a CREATE EVENT e call _myproc ON SCHEDULE ‘AT CURRENT_TIMESTAMP + DO CALL myproc(S, 27)¢ In addition, if the event's definer has the sup privilege, that event may read and write global variables. As granting this privilege entails a potential for abuse, extreme care must be taken in doing 50. Generally, any statements which are valid in stored routines may be used for action statements executed by events, For more information about statements allowable within stored routines, see Section 18.2, “Stored Routine Syntax". You can create an event as part of a stored routine, but an event cannot be created by another event, 20.2.2. ALTER EVENT Syntax ALTER BVEN’ ‘ON SCH RENAME TO new_event_namel ‘ON COMPLETION [NOT] PRESERVE: ENABLE COMMENT The aLTER EVENT statement is used to change one or more of the characteristics of an existing event without the need to drop and recreate it. The syntax for each of the ON SCHEDULE, ON COMPLETION, COMMENT, ENABLE / DISABLE, and Do clauses is exactly the same as when used with CREATE EVENT. (See Section 20.2.1, "CREATE EVENT Syntax’,) Beginning with MySQL 5.1.12, any user can alter an event defined on a database for which that user has the EVENT privilege. When a user executes a successful ALTER EVENT statement, that user becomes the definer for the effected event. (In MySQL 5.1.11 and earlier, an event could be altered only by its definer, or by a user having the SUPER privilege.) ALTER EVENT works only with an existing event: mysql> ALTER EVENT ne_such event I > oN > EVERY '2:3' DAY HOU! ERROR (#Y000): Unknown event 'no_such_evei In each of the following examples, assume that the event named myevent is defined as shown here: ipsstwunw.s duke ediesldoesimysq-rtmarvovents Nl 107sanerots (Chapter 20. Evert Scheer CREATE EVENT myevent ON SCHEDULE EVERY 6 HOUR COMMENT "A sample comme po UPDATE myschema.mytable SBT mycol = mycol + 1; The following statement changes the schedule for myevent from once every six hours starting immediately to once every twelve hours, starting four hours from the time the statement is run: myevent ON SCHEDU EVERY 12 HOUR STARTS CURRENT_TIMESTAMP + 4 HOUR; To disable myevent, use this ALTER EVENT statement: EVENT myeve DISAE The oN SCHEDULE clause may use expressions involving built-in MySQL functions and user variables to obtain any of the timestamp or interval! values which it contains. You may not use stored routines or user-defined functions in such expressions, nor may you use any table references; however, you may use SELECT FROM DUAL. This is true for both ALTER EVENT and CREATE EVENT statements. Beginning with MySQL 5.1.13, references to stored routines, user-defined functions, and tables in such cases is specifically disallowed, and fail with an error (see Bug#22830), AN ALTER EVENT statement that contains another ALTER EVENT statement in its Do clause appears to succeed; however, when the server attempts to execute the resulting scheduled event, the execution fails with an error. Itis possible to change multiple characteristics of an event in a single statement. This example changes the SQL statement executed by myevent to one that deletes all records from mytable; it also changes the schedule for the event such that it executes once, one day after this ALTER EVENT statement is run. ABLE myevent: ON SCHEDULE ‘AT CURRENT TIMESTAMP + INTERVAL 1 DAY bo TRUNCATE TABLE myschena.mytable; To rename an event, use the ALTER EVENT statement's RENAME TO clause, as shown here: BV: RENAME The previous statement renames the event myevent to yourevent. (Note: There is no RENAME EVENT statement.) You can also move an event to a different schema using ALTER EVENT ... RENAME TO ... and me notation, as shown here: T oldschema.myevent RENAME TO newschema mmyeve ipssiwurw.s duke ediesIdoesimysq-rtmarvovents Nl wTsanerots (Chapter 20. Evert Scheer In order to execute the previous statement, the user executing it must have the EVENT privilege on both the oldschema and newschema database schemas. Itis necessary to include only those options in an ALTER EVENT statement which correspond to characteristics that you actually wish to change; options which are omitted retain their existing values. This includes any default values for CREATE EVENT Such aS ENABLE. 20.2.3. DROP EVENT Syntax DROP EVENT [IF EXISTS] event_name This statement drops the event named event name. The event immediately ceases being active, and is deleted completely from the server. If the event does not exist, the error ERROR 1517 (HY000): Unknown event 'event_name" results. You can override this and cause the statement to fail silently by using IF EXrsTs. Beginning with MySQL 5.1.12, an event can be dropped by any user having the EVENT privilege on the database schema to which the event to be dropped belongs. (In MySQL 5.1.11 and earlier, an ‘event could be dropped only by its definer, or by a user having the supER privilege.) 20.3. Event Metadata Information about events can be obtained as follows: * Querying the EVENTS table of the INFORMATION_SCHEMA database. See Section 22.20, “The INFORMATION SCHEMA EVENTS Tabl * Using the sHow EVENTS statement. See Section 13.5.4.15, “SHOW EVENTS". * Using the sHow CREATE EVENT statement. See Section 13.5.4.7, “SHOW CREATE EVENT’, + Arecord of events executed on the server can be read from the MySQL Server's error log (see ion 20,5, “The Event Scheduler and MySQL Privileges" for an example). 20.4. Event Scheduler Status Information about the state of the Event Scheduler for debugging and troubleshooting purposes can be obtained as follows: + In MySQL 5.1.11 -debug builds, you can use the sHow SCHEDULER STATUS statement; see tion 13.5.4.25, “SHOW SCHEDULER STATUS Syntax" Important: This statement was removed in MySQL 5.1.12. We intend to implement an SQL statement providing similar functionality in a future MySQL release. + Beginning with MySQL 5.1.12, event scheduler status information can be obtained by running the mysqladmin debug (see Section 8.9, ‘nysaladnin — Client for Administering a MySQL. ipsstwunw.s duke ediesldoesimysq-rtmarvovents Nl varsanerots (Chapter 20. Evert Scheer Server’); after running this command, the error log contains output relating to the Event ‘Scheduler, similar to what is shown here: Events status HLA = last Locked At IUA = WoC = Waiting On Condition Unlocked At Event scheduler s : INTTIA’ SIZED nit_scheduler:313 Workers o Executed : 0 Data locked: NO : 0000-00-00 0 20.5. The Event Scheduler and MySQL Privileges To enable or disable the execution of scheduled events, it is necessary to set the value of the global event_scheduler variable. This requires the SUPER privilege. MySQL 5.1.6 introduces a privilege governing the creation, modification, and deletion of events, the EVENT privilege. This privilege can be bestowed using GRANT. For example, this GRANT statement confers the EVENT privilege for the schema named myschema on the user jon@ghidora: GRANT EVEN) * 10 ghidora; (We assume that this user account already exists, and that we wish for it to remain unchanged otherwise.) To grant this same user the EVENT privilege on all schemas would require the following statement: GRANT EVENT ON *.* TO jon@ghidora; The EveNr privilege has schema-level scope. Therefore, trying to grant it on a single table results in an error as shown: tysq1> GRANT EVENT ON myschema.mytable TO jon@ghidora; PRROR 1144 (42000): Illegal GRANT/REVOKE command; please consult the manual to see which privileges can be used It is important to understand that an event is executed with the privileges of its definer, and that it cannot perform any actions for which its definer does not have the requisite privileges. For example, Suppose that jon@ghidora has the EVENT privilege for myschema. Suppose also that this user has ipsstworw.s duke edesldoesimysq-rtmarvovents Nl sa7ant82016 (Chapter 20. Evert Scheer the SELECT privilege for myschema, but no other privileges for this schema. It is possible for jon@ghidora to create a new event such as this one: CREATE EVENT ¢_store_ts ON SCHEDULE EVERY 10 SECOND po INSERT INTO myschema.mytable VALUES (UNIX_TIMESTAMP()); The user waits for a minute or so, and then performs a SELECT * FROM mytable; query, expecting to see several new rows in the table. instead, he finds that the table is empty. Since he does not have the INSER? privilege for the table in question, the event has no effect. If you inspect the MySQL error log (hostname. err), you can see that the event is executing, but the action it is attempting to perform fails, as indicated by Retcode=0: 060209 22:39:44 [Note] EVEX EXECUTING event newdb.e [EXPR:10] 060209 22:39:44 [Note] EVEX EXECUTED event newdb.e [EXPR:10]. RetCode=0 060209 22:39:54 [Note] EVEX EXECUTING event newdb.e [EXPR:10] 060209 22:39:54 [Note] EVEX EXECUTED event newdb.e [EXPR:10]. RetCode=0 060209 22:40:04 [Note] EVEX EXECUTING event newdb.e [EXPR:10] 060209 22:40:04 [Note] VEX EXECUTED event newdb.e [EXPR:10]. RetCode=0 Since this user very likely does not have access to the error log, he can verify whether the event's action statement is valid by running it himself: mysql> INSERT INTO myschema-mytable VALUES (UNIX_? ERROR 1142 (42000): INSERT command denied to user "jon'@'ghidora' for table ‘mytable! AME ()) Inspection of the INFORMATION_SCHEMA.EVENTS table shows that e_store_ts exists and is enabled, but its LAST_EXECUTED column is NULL: mysql> SELECT * FROM INFORMATION. -EVENTS > WHERE EVENT_NAME="e_store_ts' > AND EVENT_SCHEMA="myschema'\G EVENT_CATALOG: NULL EVENT_SCHEMA: myschema EVENT NAME: ¢ store ts DEFINER: jon@ghidora EVENT_BODY: 59%, EVENT_DEFINITION: INSERT INTO myschema.mytable VALUES (UNIX_TIMESTAMP ()) EVENT_TYPE: RECURRING EXECUTE_AT: NULL INTERVAL_VALUE: 5 INTERVAL_FTELD: INTERVAL _SECOND SQE_MODE: NUL, STARTS: 0000-00-00 00:00:00 ENDS: 0000-00-00 00:00:00 STATUS: ENABLED ON_COMPLETION: NOT PRESERVE CREATED: LAST_ALTERED uast_xgcurgp: ipsstwunw.s duke ediesldoesimysq-rtmarvovents Nl wirsanerots (Chapter 20. Evert Scheer rENT_COMMENT 1 row in set (0.00 sec) (Note: Prior to MySQL 5.1.12, there was no EVENT_DEFINITION column, and EVENT_BoDY contained the SQL statement or statements to be executed. See Section 22.20, “The INFORMATION SCHEMA EVENTS Table’, for more information.) To rescind the EVEN? privilege, use the REVOKE statement. In this example, the EvENT privilege on the schema myschema is removed from the jon@ghidora user account: REVOKE EVENT ON myschema.* FROM jon@ghidora; Important: Revoking the EVENT privilege from a user account does not delete or disable any events that may have been created by that account For example, suppose that that user jon@ghidora has been granted the EVENT and INSERT privileges on the myschema schema. This user then creates the following event: REATE EVENT e_insert ON SCHEDULE EVERY 7 SECOND bo INSERT INTO myschema.mytable; After this event has been created, root revokes the EVENT privilege for jon@ghidora. However, ¢_insert continues to execute, inserting a new row into mytable each seven seconds. Event definitions are stored in the mysql. event table, which was added in MySQL 5.1.6. To drop an event created by another user account, the MySQL root user (or another user with the necessary privileges) can delete rows from this table. For example, to remove the event e_insert shown previously, root can use the following statement: E FROM mys’ = db = 'myschena’ AND definer = '"jon@ghidora' AND name = 'e insert'; Itis very important to match the event name, database schema name, and user account when deleting rows from the mysql .event table. This is because the same user can create different events of the same name in different schemas. Note: The namespace for scheduled events changed in MySQL 5.1.12. Prior to that MySQL version, different users could create different events having the same name in the same database; in MySQL 5.1.12 and later, that is no longer the case. When upgrading to MySQL 5.1.12 or later from MySQL 5.1.11 or earlier, it is extremely important to make sure that no events in the same database share the ‘same name, prior to performing the upgrade. Users’ event privileges are stored in the Event_priv columns of the mysql.user and mysql.db tables. In both cases, this column holds one of the values 'y' or 'y’. 'n’is the default. mysql.user.Event_privis set to 'y' for a given user only if that user has the global EveNr privilege (that is, if the privilege was bestowed using GRANT EVENT ON *.*), For a schema-level EVENT privilege, GRANT creates a row in mysql .db and sets that row’s Db column to the name of the schema, the User column to the name of the user, and the Event_priv column to ‘y'. There should ipsstwunw.s duke ediesldoesimysq-rtmarvovents Nl 187sanerots (Chapter 20. Evert Scheer never be any need to manipulate these tables directly, since the GRANT EVENT and REVOKE EVENT statement perform the required operations on them. MySQL 5.1.6 introduces five status variables providing counts of event-related operations (but not of statements executed by events — see Section 20.6, "Event Scheduler Limitations and Restrictions”) These are: * Com_create event: The number of CREATE EVENT statements executed since the last server restart. * Com_altex event: The number of ALTER EVENT statements executed since the last server restart. ‘+ Com_drop_event: The number of DRoP EVENT statements executed since the last server restart. ‘+ Com_show_create_event: The number of SHOW CREATE EVENT statements executed since the last server restart. + Com_show_events: The number of SHOW EVENTS statements executed since the last server restart. You can view current values for all of these at one time by running the statement suow STATUS LIKE ‘Sevents'; 20.6. Event Scheduler Limitations and Restrictions This section lists restrictions and limitations applying to event scheduling in MySQL. In MySQL 5.1.6, any table referenced in an event's action statement must be fully qualified with the name of the schema in which it occurs (that is, a8 schema name. table name). An event may not be created, altered, or dropped by a trigger, stored routine, or another event. An event also may not create, alter, or drop triggers or stored routines. (Bua#16409, Buai#18896) Event timings using the intervals YEAR, QUARTER, MONTH, and YEAR_MONTH are resolved in months; those using any other interval are resolved in seconds. There is no way to cause events scheduled to occur at the same second to execute in a given order. In addition — due to rounding, the nature of threaded applications, and the fact that a non-zero length of time is required to create events and to signal their execution — events may be delayed by as much as 1 or 2 seconds. However, the time shown in the INFORMATION_SCHEMA. EVENTS table's LAST_EXECUTED column or the mysql.event table's 1ast_executed column is always accurate to within one second of the time the event was actually executed. (See also Bug#16522.) Execution of event statements have no affect on the server's statement counts such as Com_select and Com_insert that are displayed by stow STATUS, Prior to MySQL 5.1.12, you could not view another user's events in the INFORMATION_SCHEMA. EVENTS table. In other words, any query made against this table was treated as though it contained the condition DEFINER = CURRENT_USER() in the WHERE clause, Events cannot be created with a start time that is in the past. ipsstwunw.s duke ediesldoesimysq-rtmarvovents Nl 107sanerots (Chapter 20. Evert Scheer Events do not support times later than the end of the Unix Epoch; this is approximately the end of the year 2037. Prior to MySQL 5.1.8, handling in scheduled events of dates later than this was buggy; starting with MySQL 5.1.8, such dates are specifically disallowed by the Event Scheduler. (Bug#16396) In MySQL 5.1.6, INFORMATION SCHEMA. EVENTS shows NULL in the SL_MoDE column. Beginning with MySQL 5.1.7, the sot, MopE displayed is that in effect when the event was created. In MySQL 5.1.6, the only way to drop or alter an event created by a user who was not the definer of that event was by manipulation of the mysql..event system table by the MySQL xoot user or by another user with privileges on this table. Beginning with MySQL 5.1.7, DROP USER drops all events for which that user was the definer; also beginning with MySQL 5.1.7 DROP SCHEMA drops all events associated with the dropped schema, As with stored routines, events are not migrated to the new schema by the RENAME SCHEMA (or RENAME DATABASE) statement. See Section 13.1.15, “RENAME DATABASE Syntax", Beginning with MySQL 5.1.8, event names are handled in case-insensitive fashion. For example, this means that you cannot have two events in the same database (and — prior to MySQL 5.1.12 — with the same definer) with the names anzvent and anzvent. Important: If you have events created in MySQL 5.1.7 or earlier, which are assigned to the same database and have the same definer, and whose names differ only with respect to lettercase, then you must rename these events to respect case-sensitive handling before upgrading to MySQL 5.1.8 or later. References to stored routines, user-defined functions, and tables in the oN SCHEDULE clauses of CREATE EVENT and ALTER EVENT statements are not supported. Beginning with MySQL 5.1.13, these sorts of references are disallowed. (See Bug#22830 for more information.) Prev. Next Chapter 19. Triggers Home Chapter 21. Views ipsstwunw.s duke ediesldoesimysq-rtmarvovents Nl wr