MySQL :: MySQL 9.0 参考手册 :: 15.1.13 CREATE EVENT 语句

版本 9.0

8.4 当前
8.0
5.7

8.0 日语

MySQL 9.0 参考手册 / ... / CREATE EVENT 语句

15.1.13 CREATE EVENT 语句

CREATE
    [DEFINER = user]
    EVENT
    [IF NOT EXISTS]
    event_name
    ON SCHEDULE schedule
    [ON COMPLETION [NOT] PRESERVE]
    [ENABLE | DISABLE | DISABLE ON {REPLICA | 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}

此语句创建并调度一个新事件。除非启用了事件调度程序，否则该事件不会运行。有关检查事件调度程序状态并在必要时启用它的信息，请参见第 27.5.2 节“事件调度程序配置”。

CREATE EVENT 需要对要在其中创建事件的模式具有 EVENT 权限。如果存在 DEFINER 子句，则所需的权限取决于 user 值，如第 27.7 节“存储对象访问控制” 中所述。

有效 CREATE EVENT 语句的最低要求如下：

关键字 CREATE EVENT 加上事件名称，该名称在数据库模式中唯一标识该事件。
一个 ON SCHEDULE 子句，用于确定事件的执行时间和频率。
一个 DO 子句，其中包含要由事件执行的 SQL 语句。

这是一个最简单的 CREATE EVENT 语句的示例：

CREATE EVENT myevent
    ON SCHEDULE AT CURRENT_TIMESTAMP + INTERVAL 1 HOUR
    DO
      UPDATE myschema.mytable SET mycol = mycol + 1;

上一条语句创建了一个名为 myevent 的事件。此事件将在创建后一小时执行一次，执行的 SQL 语句会将 myschema.mytable 表的 mycol 列的值增加 1。

event_name 必须是有效的 MySQL 标识符，最大长度为 64 个字符。事件名称不区分大小写，因此在同一架构中不能有两个名为 myevent 和 MyEvent 的事件。通常，事件名称的规则与存储例程名称的规则相同。请参阅第 11.2 节“架构对象名称”。

事件与架构相关联。如果 event_name 中未指定架构，则假定为默认（当前）架构。要在特定架构中创建事件，请使用 schema_name.event_name 语法限定事件名称。

DEFINER 子句指定在事件执行时用于检查访问权限的 MySQL 帐户。如果存在 DEFINER 子句，则 user 值应为指定为 'user_name'@'host_name' 的 MySQL 帐户、CURRENT_USER 或 CURRENT_USER()。允许的 user 值取决于您拥有的权限，如第 27.7 节“存储对象访问控制” 中所述。另请参阅该部分以获取有关事件安全的更多信息。

如果省略 DEFINER 子句，则默认定义者是执行 CREATE EVENT 语句的用户。这与显式指定 DEFINER = CURRENT_USER 相同。

在事件体中，CURRENT_USER 函数返回用于在事件执行时检查权限的帐户，该帐户是 DEFINER 用户。有关事件内用户审核的信息，请参阅第 8.2.23 节“基于 SQL 的帐户活动审核”。

IF NOT EXISTS 对于 CREATE EVENT 的含义与 CREATE TABLE 相同：如果在同一架构中已存在名为 event_name 的事件，则不执行任何操作，也不会产生错误。（但是，在这种情况下会生成警告。）

ON SCHEDULE 子句确定为事件定义的 event_body 何时、多久重复一次以及重复多长时间。此子句采用以下两种形式之一

AT timestamp 用于一次性事件。它指定事件仅在 timestamp 给定的日期和时间执行一次，timestamp 必须同时包含日期和时间，或者必须是解析为日期时间值的表达式。为此，您可以使用 DATETIME 或 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());
Query OK, 0 rows affected, 1 warning (0.00 sec)

mysql> SHOW WARNINGS\G
*************************** 1. row ***************************
  Level: Note
   Code: 1588
Message: Event execution time is in the past and ON COMPLETION NOT
         PRESERVE is set. The event was dropped immediately after
         creation.
```
本身无效的 CREATE EVENT 语句（无论出于何种原因）都会失败并报错。
您可以使用 CURRENT_TIMESTAMP 指定当前日期和时间。在这种情况下，事件会在创建后立即生效。
要创建一个在相对于当前日期和时间的未来某个时间点发生的事件（例如““三周后””所表达的事件），可以使用可选子句 + INTERVAL interval。interval 部分由时间量和时间单位两部分组成，并遵循时间间隔中描述的语法规则，但定义事件时不能使用任何涉及微秒的单位关键字。对于某些时间间隔类型，可以使用复杂的时间单位。例如，““两分钟零十秒””可以表示为 + INTERVAL '2:10' MINUTE_SECOND。
您还可以组合时间间隔。例如，AT CURRENT_TIMESTAMP + INTERVAL 3 WEEK + INTERVAL 2 DAY 等价于““三周零两天后””。此类子句的每个部分都必须以 + INTERVAL 开头。
要按固定间隔重复操作，请使用 EVERY 子句。EVERY 关键字后跟一个 interval，如前面讨论 AT 关键字时所述。（+ INTERVAL 不与 EVERY 一起使用。）例如，EVERY 6 WEEK 表示““每六周””。
尽管 + INTERVAL 子句在 EVERY 子句中不允许使用，但您可以使用 + INTERVAL 中允许的相同复杂时间单位。
EVERY 子句可以包含一个可选的 STARTS 子句。STARTS 后跟一个 timestamp 值，该值指示操作应何时开始重复，并且还可以使用 + INTERVAL interval 指定““从现在开始””的时间量。例如，EVERY 3 MONTH STARTS CURRENT_TIMESTAMP + INTERVAL 1 WEEK 表示““每三个月，从现在开始的一周后开始””。类似地，您可以将““每两周，从现在开始的六小时十五分钟后开始””表示为 EVERY 2 WEEK STARTS CURRENT_TIMESTAMP + INTERVAL '6:15' HOUR_MINUTE。不指定 STARTS 与使用 STARTS CURRENT_TIMESTAMP 相同，也就是说，为事件指定的操作在创建事件后立即开始重复。
EVERY 子句可以包含一个可选的 ENDS 子句。ENDS 关键字后跟一个 timestamp 值，该值告诉 MySQL 事件应何时停止重复。您还可以将 + INTERVAL interval 与 ENDS 一起使用；例如，EVERY 12 HOUR STARTS CURRENT_TIMESTAMP + INTERVAL 30 MINUTE ENDS CURRENT_TIMESTAMP + INTERVAL 4 WEEK 等价于““每十二个小时，从现在开始的三十分钟后开始，到从现在开始的四周后结束””。不使用 ENDS 表示事件将无限期地继续执行。
ENDS 支持与 STARTS 相同的复杂时间单位语法。
您可以在 EVERY 子句中使用 STARTS、ENDS、两者都使用或两者都不使用。
如果重复事件在其调度间隔内未终止，则可能会导致事件的多个实例同时执行。如果这是不可取的，则应建立一种机制来防止同时出现多个实例。例如，您可以使用 GET_LOCK() 函数，或者使用行锁或表锁。

ON SCHEDULE 子句可以使用涉及内置 MySQL 函数和用户变量的表达式来获取其包含的任何 timestamp 或 interval 值。您不能在此类表达式中使用存储函数或可加载函数，也不能使用任何表引用；但是，您可以使用 SELECT FROM DUAL。这对于 CREATE EVENT 和 ALTER EVENT 语句都是如此。在这种情况下，明确禁止引用存储函数、可加载函数和表，并且会失败并报错（请参阅错误 #22830）。

ON SCHEDULE 子句中的时间使用当前会话 time_zone 值进行解释。这将成为事件时区；也就是说，用于事件调度并在事件执行期间生效的时区。这些时间将转换为 UTC，并与事件时区一起存储在内部。这使得事件执行能够按照定义进行，而无需考虑服务器时区或夏令时效果的任何后续更改。有关事件时间表示的更多信息，请参阅第 27.5.4 节“事件元数据”。另请参阅第 15.7.7.19 节“SHOW EVENTS 语句” 和第 28.3.14 节“INFORMATION_SCHEMA EVENTS 表”。

通常，事件过期后会立即删除。您可以通过指定 ON COMPLETION PRESERVE 来覆盖此行为。使用 ON COMPLETION NOT PRESERVE 只是使默认的非持久行为变得明确。

您可以创建一个事件，但可以使用 DISABLE 关键字阻止其处于活动状态。或者，您可以使用 ENABLE 明确默认状态，即活动状态。这与 ALTER EVENT 一起使用时最有用（请参阅第 15.1.3 节“ALTER EVENT 语句”）。

第三个值也可以出现在 ENABLE 或 DISABLE 的位置；DISABLE ON REPLICA 用于设置副本上事件的状态，以指示该事件是在复制源服务器上创建并复制到副本的，但在副本上不执行。请参阅第 19.5.1.16 节“已调用功能的复制”。

DISABLE ON REPLICA 替换了 DISABLE ON SLAVE，后者已被弃用，因此将在未来版本的 MySQL 中删除。

您可以使用 COMMENT 子句为事件提供注释。comment 可以是您希望用于描述事件的任何字符串，最长为 64 个字符。注释文本是字符串文字，因此必须用引号引起来。

DO 子句指定事件执行的操作，并由一条 SQL 语句组成。几乎所有可以在存储例程中使用的有效 MySQL 语句都可以用作计划事件的操作语句。（请参阅第 27.9 节“对存储程序的限制”。）例如，以下事件 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 模式是什么。

包含 DO 子句中嵌套 ALTER EVENT 语句的 CREATE EVENT 语句表面上可以成功执行；但是，当服务器尝试执行生成的计划事件时，执行会失败并报错。

注意

诸如 SELECT 或 SHOW 之类的仅仅返回结果集的语句在事件中使用时无效；这些语句的输出不会发送到 MySQL 监视器，也不会存储在任何地方。但是，您可以使用诸如 SELECT ... INTO 和 INSERT INTO ... SELECT 之类的存储结果的语句。（有关后者的实例，请参见本节中的下一个示例。）

事件所属的模式是 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 命令更改语句分隔符。请参阅第 27.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);

在 MySQL 9.0 中，可以准备 CREATE EVENT 语句，但语句文本不能包含任何占位符 (?)。解决此限制的一种方法是组合语句的文本，准备它，并在存储过程中执行它；CREATE EVENT 语句的可变部分可以作为参数传递给存储过程。我们将在以下示例中对此进行演示，该示例假设数据库 d 中已经存在一个表 t，如下所示

USE d;

CREATE TABLE t (
  c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
  c2 VARCHAR(20),
  c3 INT
);

我们希望创建一个事件，以在创建时确定的时间间隔将行插入此表中，类似于由以下语句定义的事件

CREATE EVENT e 
  ON SCHEDULE EVERY interval SECOND
  STARTS CURRENT_TIMESTAMP + INTERVAL 10 SECOND
  ENDS CURRENT_TIMESTAMP + INTERVAL 2 MINUTE
  ON COMPLETION PRESERVE
  DO
    INSERT INTO d.t1 VALUES ROW(NULL, NOW(), FLOOR(RAND()*100));

我们不能使用 ? 作为 interval 的占位符，但我们可以将参数值传递给存储过程，如下所示

delimiter |

CREATE PROCEDURE sp(n INT)
BEGIN
  SET @s1 = "CREATE EVENT e ON SCHEDULE EVERY ";
  SET @s2 = " SECOND
       STARTS CURRENT_TIMESTAMP + INTERVAL 10 SECOND
       ENDS CURRENT_TIMESTAMP + INTERVAL 2 MINUTE
       ON COMPLETION PRESERVE
       DO
       INSERT INTO d.t VALUES ROW(NULL, NOW(), FLOOR(RAND()*100))";
  
  SET @s = CONCAT(@s1, n, @s2);
  PREPARE ps FROM @s;
  EXECUTE ps;
  DEALLOCATE PREPARE ps;
END |

delimiter ;

mysql> TABLE t;
Empty set (0.00 sec)

mysql> CALL sp(5);
Query OK, 0 rows affected (0.01 sec)

# Wait 2 minutes...

mysql> TABLE t;
+----+---------------------+------+
| c1 | c2                  | c3   |
+----+---------------------+------+
|  1 | 2024-06-12 15:53:36 |   41 |
|  2 | 2024-06-12 15:53:41 |   84 |
|  3 | 2024-06-12 15:53:46 |   71 |
|  4 | 2024-06-12 15:53:51 |   78 |
|  5 | 2024-06-12 15:53:56 |   53 |
|  6 | 2024-06-12 15:54:01 |    6 |
|  7 | 2024-06-12 15:54:06 |   48 |
|  8 | 2024-06-12 15:54:11 |   98 |
|  9 | 2024-06-12 15:54:16 |   22 |
| 10 | 2024-06-12 15:54:21 |   88 |
| 11 | 2024-06-12 15:54:26 |   53 |
| 12 | 2024-06-12 15:54:31 |   75 |
| 13 | 2024-06-12 15:54:36 |   93 |
| 14 | 2024-06-12 15:54:41 |   13 |
| 15 | 2024-06-12 15:54:46 |   62 |
| 16 | 2024-06-12 15:54:51 |   47 |
| 17 | 2024-06-12 15:54:56 |   22 |
| 18 | 2024-06-12 15:55:01 |   47 |
| 19 | 2024-06-12 15:55:06 |   43 |
| 20 | 2024-06-12 15:55:11 |   50 |
| 21 | 2024-06-12 15:55:16 |   98 |
| 22 | 2024-06-12 15:55:21 |   15 |
| 23 | 2024-06-12 15:55:26 |   56 |
+----+---------------------+------+
23 rows in set (0.00 sec)

使用参数值 5 调用 sp（如下所示）并在事件 e 完成运行之前等待 2 分钟后，我们可以看到表 t 每 5 秒更新一次。由于 e 是使用 ON COMPLETION PRESERVE 创建的，因此我们可以在信息架构 EVENTS 表中看到它，并验证它是否按预期创建

mysql> SELECT EVENT_NAME, EVENT_SCHEMA, EVENT_DEFINITION, EVENT_TYPE 
     > FROM INFORMATION_SCHEMA.EVENTS WHERE EVENT_NAME='e'\G
*************************** 1. row ***************************
      EVENT_NAME: e
    EVENT_SCHEMA: d
EVENT_DEFINITION: INSERT INTO d.t VALUES ROW(NULL, NOW(), FLOOR(RAND()*100))
      EVENT_TYPE: RECURRING
1 row in set (0.00 sec)

如果事件的定义者具有足够的权限来设置全局系统变量（请参阅第 7.1.9.1 节“系统变量权限”），则该事件可以读取和写入全局变量。由于授予此类权限可能会导致滥用，因此必须格外小心。

通常，存储例程中有效的任何语句都可以用于事件执行的操作语句。有关存储例程中允许使用的语句的更多信息，请参阅第 27.2.1 节“存储例程语法”。无法在存储例程中创建事件，也无法通过另一个事件创建事件。