CREATE EVENT [IF NOT EXISTS] event_name

ON SCHEDULE schedule

[ON COMPLETION [NOT] PRESERVE] [ENABLE | DISABLE]

[COMMENT 'comment']

DO sql_statement;

schedule:

AT timestamp [+ INTERVAL interval]

| EVERY interval [STARTS timestamp]

[ENDS timestamp]

interval:

quantity {YEAR | QUARTER | MONTH | DAY | HOUR |

MINUTE | WEEK | SECOND | YEAR_MONTH | DAY_HOUR |

DAY_MINUTE | DAY_SECOND | HOUR_MINUTE | HOUR_SECOND |

MINUTE_SECOND}

Эта инструкция создает и планирует новое событие. Минимальные требования для допустимой инструкции CREATE EVENT следующие:

Ключевые слова CREATE EVENT плюс имя события, которое уникально идентифицирует событие в текущей схеме.

До MySQL 5.1.12 имя события должно было быть уникальным только среди событий, созданных тем же самым пользователем в этой базе данных.

Предложение ON SCHEDULE, которое определяет, когда и как часто событие выполняется.

Предложение DO, которое содержит инструкцию SQL, которая будет выполнена событием.

Это пример минимальной инструкцииCREATE EVENT myevent

ON SCHEDULE AT CURRENT_TIMESTAMP + INTERVAL 1 HOUR

DO UPDATE myschema.mytable SET mycol = mycol + 1;

Предыдущая инструкция создает событие myevent. Это событие выполняется один раз в час после создания, выполняя инструкцию SQL, которая увеличивает значение столбца mycol таблицы myschema.mytable на 1.

Имя event_name должно быть допустимым идентификатором MySQL с максимальной длиной в 64 символа. Это может быть разграничено, используя обратные импульсы сигнала времени, и может быть квалифицировано с именем схемы базы данных. Событие связано с пользователем MySQL (definer) и схемой, так что имя должно быть уникальным среди имен событий внутри этой схемы. Вообще, правила, управляющие именами событий, такие же, как для имен сохраненных подпрограмм, поскольку события по сути и являются такими подпрограммами, только особыми.

Если никакая схема не обозначена как часть event_name, то принята заданная по умолчанию схема. Definer всегда текущий пользователь MySQL.

До MySQL 5.1.12 было возможно для двух различных пользователей создать различные события, имеющие то же самое имя в той же самой схеме базы данных.

Обратите внимание: MySQL использует сравнения без учета регистра при прверке уникальности имен события. Это означает, что, например, Вы не можете иметь два события events named myevent и MyEvent в той же самой схеме базы данных.

Функция IF NOT EXISTS с инструкцией CREATE EVENT работает полностью аналогично варианту с CREATE TABLE: если событие event_name уже существует в той же самой схеме, никаких действий не предпринимается, и никакой ошибки не будет. Однако, предупреждение будет сгенерировано.

Предложение ON SCHEDULE определяет, когда, как часто и как долго sql_statement определено для повторения события. Это предложение берет одну из двух форм:

AT timestamp используется для одноразового события. Это определяет, что событие выполняется только однократно, а именно в дату и время, заданные как timestamp, причем надо указать вместе дату и время, либо задать выражение, которое раскрывается в однозначный тип datetime. Вы можете использовать значение, которое имеет тип DATETIME или TIMESTAMP для этой цели. Указанный timestamp должен также быть в будущем. Вы не можете планировать событие, которое должно было произойти в прошлом. Попытка это сделать приведет к ошибке:

mysql> SELECT NOW();

+---------------------+

| NOW() |

+---------------------+

| 2006-02-10 23:59:01 |

+---------------------+

1 row in set (0.04 sec)

mysql> CREATE EVENT e_totals

– > ON SCHEDULE AT '2006-02-10 23:59:00'

– > DO INSERT INTO test.totals VALUES (NOW());

ERROR 1522 (HY000): Activation (AT) time is in the past

Инструкции CREATE EVENT, которые являются самостоятельно недопустимыми по любой причине, также завершаются ошибкой.

Вы можете использовать CURRENT_TIMESTAMP, чтобы определить текущую дату и время. В таком случае событие действует, как только оно будет полностью создано.

Чтобы создавать событие, которое происходит в некоторой отметке в будущем относительно текущей даты и времени Вы можете использовать факультативное предложение + INTERVAL interval. Часть interval состоит из двух кусков: количества и модуля времени, и следует тем же самым правилам синтаксиса, которые управляют интервалами, используемыми в функции DATE_ADD(). Ключевые слова модулей также те же самые за исключением того, что Вы не можете использовать любые модули, включающие микросекунды, при определении события.

Вы можете также объединять интервалы. Например, AT CURRENT_TIMESTAMP + INTERVAL 3 WEEK + INTERVAL 2 DAY эквивалентно "три недели и два дня с этого времени". Каждая часть такого предложения должна начинаться с + INTERVAL.

Для действий, которые должны быть повторены в регулярном интервале, Вы можете использовать предложение EVERY. Ключевое слово EVERY сопровождается интервалом, как описано выше. (+ INTERVAL не используется с EVERY). Например, EVERY 6 WEEK означает "каждые шесть недель".

Невозможно объединить предложения + INTERVAL в одиночном предложении EVERY. Однако, Вы можете использовать те же самые сложные модули времени, позволенные в + INTERVAL. Например, каждые две минуты и десять секунд можно задать как EVERY '2:10' MINUTE_SECOND.

Предложение EVERY может также содержать факультативное предложение STARTS. Оно сопровождается значением timestamp, которое указывает, когда действие должно начать повторяться, и может также использовать + INTERVAL interval, чтобы определить количество времени с этого момента. Например, EVERY 3 MONTH STARTS CURRENT_TIMESTAMP + 1 WEEK означает "каждые три месяца, начиная спустя одну неделю с этого времени". Точно так же Вы можете выражать "каждые две недели, начиная через шесть часов и пятнадцать минут с этого времени" с помощью EVERY 2 WEEK STARTS CURRENT_TIMESTAMP + '6:15' HOUR_MINUTE. Не определение STARTS аналогично STARTS CURRENT_TIMESTAMP, то есть действие, определенное для события, начинает повторяться немедленно после создания события.

Предложение EVERY может также содержать факультативное предложение ENDS. Это ключевое слово сопровождается значением timestamp, которое сообщает MySQL, когда событие должно перестать повторяться. Вы можете также использовать + INTERVAL interval с ENDS. Например: EVERY 12 HOUR STARTS CURRENT_TIMESTAMP + INTERVAL 30 MINUTE ENDS CURRENT_TIMESTAMP + INTERVAL 4 WEEK означает "каждые двенадцать часов, начиная спустя тридцать минут с этого времени, и заканчивая через четыре недели тоже с этого времени". Не использование ENDS означает, что событие продолжает выполняться неопределенно долго.

ENDS поддерживает тот же самый синтаксис для сложных модулей времени, что и STARTS. Вы можете использовать STARTS, ENDS вместе или порознь (либо вовсе не использовать их) в предложении EVERY.

Обратите внимание: где STARTS или ENDS заданы как значение datetime, используется местное время на сервере. Однако, значения для обоих значений в настоящее время сообщены, используя Universal Time в таблицах INFORMATION_SCHEMA.EVENTS и mysql.event, также как в выводе SHOW EVENTS. Это неправильное поведение, и Ваша прикладная программа не должна полагаься на это, поскольку ситуация изменится ().

Предложение ON SCHEDULE может использовать выражения, включающие встроенные функции MySQL и переменные пользователя, чтобы получить любое значение timestamp или interval. Вы не можете использовать сохраненные подпрограммы или определяемые пользователем функции в таких выражениях, и при этом Вы не можете использовать любые ссылки на таблицы, однако, Вы можете SELECT FROM DUAL. Это истинно для инструкций CREATE EVENT и ALTER EVENT. Начиная с MySQL 5.1.13, ссылки на сохраненные подпрограммы, определяемые пользователем функции и таблицы в таких случаях специально отвергнуты и вызывают сбой с ошибкой ().

Обычно, как только событие истекло, оно немедленно уничтожается. Вы можете отменять это поведение, определяя ON COMPLETION PRESERVE. Использование ON COMPLETION NOT PRESERVE просто делает заданное по умолчанию поведение явным.

Вы можете создавать событие и сохранить его неактивным для дальнейшего неспешного потребления, используя ключевое слово DISABLE. В качестве альтернативы Вы можете использовать ENABLE, чтобы сделать явным заданное по умолчанию состояние, которое является активным. Это наиболее полезно вместе с ALTER EVENT.

Вы можете обеспечивать комментарий для события, используя предложение COMMENT. Здесь comment может быть любой строкой до 64 символов, которые Вы желаете использовать для описания события. Текст комментария, являющийся строковым литералом, должен быть окружен кавычками.

Предложение DO определяет действие, которое несет событие, и состоит из инструкции SQL. Почти любая допустимая инструкция MySQL, которая может использоваться в сохраненной подпрограмме, может также использоваться как инструкция действия для планируемого события. Например, следующее событие e_hourly удаляет все строки из таблицы sessions раз в час, если только эта таблица часть схемы site_activity:

CREATE EVENT e_hourly ON SCHEDULE

EVERY 1 HOUR COMMENT 'Clears out sessions table each hour.'

DO DELETE FROM site_activity.sessions;

Инструкция CREATE EVENT, которая содержит инструкцию ALTER EVENT в предложении DO, появляется, однако, когда сервер пытается выполнить возникающее в результате планируемое событие, получается сбой выполнения с ошибкой.

Обратите внимание: инструкции SHOW и SELECT, которые просто возвращают набор результатов, не имеют никакого эффекта, когда используются в событии, вывод из них не будет послан MySQL Monitor. Однако, Вы можете использовать инструкции типа SELECT INTO и INSERT … SELECT, которые сохраняют результат.

Любая ссылка в предложении DO к таблице в другой схеме базы данных должна быть квалифицирована с именем схемы, в которой таблица находится. В MySQL 5.1.6 все таблицы, вызванные в предложениях DO событий должны были включать ссылку на базу данных.

Как и в случае с сохраненными подпрограммами, Вы можете использовать много инструкций в предложении DO заключением их в слова BEGIN и END, как показано здесь:

DELIMITER |

CREATE EVENT e_daily ON SCHEDULE

EVERY 1 DAY

COMMENT 'Saves total number of sessions then clears the table each day.'

DO BEGIN

INSERT INTO site_activity.totals (when, total)

SELECT CURRENT_TIMESTAMP, COUNT(*)

FROM site_activity.sessions;

DELETE FROM site_activity.sessions;

END |

DELIMITER ;

Обратите внимание на использование инструкции DELIMITER, чтобы изменить операторный разделитель, как с сохраненными подпрограммами.

Более сложные составные инструкции, типа тех, что используюся в сохраненных подпрограммах, возможны в событии. Этот пример использует локальные переменные, драйвер ошибки и конструкцию управления потоком данных:

DELIMITER |

CREATE EVENT e ON SCHEDULE

EVERY 5 SECOND DO BEGIN

DECLARE v INTEGER;

DECLARE CONTINUE HANDLER FOR SQLEXCEPTION BEGIN END;

SET v = 0;

WHILE v < 5 DO

INSERT INTO t1 VALUES (0);

UPDATE t2 SET s1 = s1 + 1;

SET v = v + 1;

END WHILE;

END |

DELIMITER ;

Не имеется никакого способа передать параметры непосредственно событию, однако, возможно вызвать сохраненную подпрограмму с параметрами:

CREATE EVENT e_call_myproc ON SCHEDULE

AT CURRENT_TIMESTAMP + 1 DAY

DO CALL myproc(5, 27);

Кроме того, если definer события имеет привилегию SUPER, то событие может читать и записывать глобальные переменные. Так как предоставление этой привилегии влечет за собой потенциал для неправильного обращения, критическая осторожность должна быть проявлена.

Вообще, любые инструкции, которые являются допустимыми в сохраненных подпрограммах, могут использоваться для инструкций действия, выполненных событиями. Вы можете создавать событие как часть сохраненной подпрограммы, но событие не может быть создано другим событием.