CREATE
    [DEFINER = user]
    EVENT
    [IF NOT EXISTS]
    event_name
    ON SCHEDULE schedule
    [ON COMPLETION [NOT] PRESERVE]
    [ENABLE | DISABLE | DISABLE ON SLAVE]
    [COMMENT 'string']
    DO event_body;

schedule: {
    AT timestamp [+ INTERVAL interval] ...
  | EVERY interval
    [STARTS timestamp [+ INTERVAL interval] ...]
    [ENDS timestamp [+ INTERVAL interval] ...]
}

interval:
    quantity {YEAR | QUARTER | MONTH | DAY | HOUR | MINUTE |
              WEEK | SECOND | YEAR_MONTH | DAY_HOUR | DAY_MINUTE |
              DAY_SECOND | HOUR_MINUTE | HOUR_SECOND | MINUTE_SECOND}

Это утверждение создает и планирует новое событие. Событие не выполняется, если планировщик событий не включён. Для получения информации о проверке состояния планировщика событий и его включении при необходимости, см. Раздел 23.4.2, «Настройка планировщика событий».

CREATE EVENT требует привилегии EVENT для схемы, в которой должно быть создано событие. Если присутствует фраза DEFINER, требуемые привилегии зависят от значения user, как обсуждается в Разделе 23.6, «Управление доступом к хранимым объектам».

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

Вот пример минимального заявления CREATE EVENT:

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 символа. Имена событий не чувствительны к регистру, поэтому вы не можете иметь два события с именами myevent и MyEvent в одной и той же схеме. В общем случае правила, регулирующие имена событий, такие же, как и для имён хранимых процедур. См. Раздел 9.2, «Имена объектов схемы».

Событие связано со схемой. Если схема не указана в качестве части event_name, предполагается использовать схему по умолчанию (текущую). Чтобы создать событие в определённой схеме, квалифицируйте имя события с помощью схемы, используя синтаксис schema_name.event_name.

Фраза DEFINER указывает учётную запись MySQL, которая используется при проверке привилегий во время выполнения события. Если присутствует фраза DEFINER, значение user должно быть учётной записью MySQL, указанной как 'user_name'@'host_name', CURRENT_USER или CURRENT_USER(). Разрешенные значения user зависят от имеющихся у вас привилегий, как обсуждалось в Разделе 23.6, «Управление доступом к хранимым объектам». Также см. этот раздел для дополнительной информации о безопасности событий.

Если фраза DEFINER опущена, дефолтный определяющий элемент — пользователь, который выполняет утверждение CREATE EVENT. Это эквивалентно явному указанию DEFINER = CURRENT_USER.

В теле события функция CURRENT_USER возвращает учётную запись, используемую для проверки привилегий во время выполнения события, которая является пользователем DEFINER. Для получения информации об аудировании пользователей в событиях, см. Раздел 6.2.18, «Аудит активности учётных записей на основе SQL».

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

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

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

Временные значения в клаузе ON SCHEDULE интерпретируются с использованием текущего значения переменной сессии time_zone. Это становится часовым поясом события; то есть, часовой пояс, используемый для планирования событий и действующий во время выполнения события. Эти значения времени преобразуются в UTC и хранятся вместе с часовым поясом события в таблице mysql.event. Это позволяет выполнять события в соответствии с заданными параметрами независимо от последующих изменений часового пояса сервера или эффектов перехода на летнее время. Дополнительную информацию о представлении временных значений событий см. в разделе 23.4.4 «Данные о событиях». Также см. раздел 13.7.5.18 «Команда SHOW EVENTS» и раздел 24.3.8 «Таблица INFORMATION_SCHEMA EVENTS».

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

Вы можете создать событие, но предотвратить его активацию, используя ключевое слово DISABLE. В качестве альтернативы, вы можете использовать ENABLE, чтобы явно указать состояние по умолчанию, которое является активным. Это наиболее полезно в сочетании с ALTER EVENT (см. раздел 13.1.2 «Команда ALTER EVENT»).

Третье значение может также появиться вместо ENABLE или DISABLE; DISABLE ON SLAVE устанавливается для статуса события на реплике, чтобы указать, что событие было создано на источнике и реплицировано на реплику, но не выполняется на реплике. См. раздел 16.4.1.16 «Репликация вызываемых функций».

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

Клауза DO определяет действие, выполняемое событием, и состоит из оператора SQL. Почти любой допустимый оператор MySQL, который может быть использован в хранимой процедуре, также может быть использован в качестве оператора действия для запланированного события. (См. раздел 23.8 «Ограничения для хранимых программ».) Например, следующее событие 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;

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

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

Схема, к которой принадлежит событие, является схемой по умолчанию для ссылок на таблицы в клаузе 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 (time, total)
          SELECT CURRENT_TIMESTAMP, COUNT(*)
            FROM site_activity.sessions;
        DELETE FROM site_activity.sessions;
      END |

delimiter ;

В этом примере используется команда delimiter для изменения разделителя операторов. См. раздел 23.1 «Определение хранимых программ».

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

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 + INTERVAL 1 DAY
    DO CALL myproc(5, 27);

Если у определяющего событие пользователя есть права на установку глобальных переменных системы (см. раздел 5.1.8.1 «Права на переменные системы»), то событие может считывать и записывать глобальные переменные. Поскольку предоставление таких привилегий подразумевает потенциальную возможность злоупотребления, необходимо проявлять крайнюю осторожность при их предоставлении.

Как правило, любые операторы, допустимые в хранимых процедурах, могут использоваться в операторах действия, выполняемых событиями. Дополнительную информацию об операторах, разрешённых в хранимых процедурах, см. в разделе 23.2.1 «Синтаксис хранимых процедур». Вы можете создать событие как часть хранимой процедуры, но событие не может быть создано другим событием.