更新时间:2026-10-21 GMT+08:00
分享

CREATE EVENT

功能描述

创建一个定时任务。定时任务是一种在数据库中定义的特殊对象,与表或者其他数据库对象关联;当满足指定事件条件时,自动触发并执行预定义的操作或语句。

注意事项

  • 仅在B兼容模式数据库(即sql_compatibility = 'B')下支持使用定时任务相关操作。
  • 用户操作(创建、修改以及删除)定时任务时,非SYSADMIN用户需要被SYSADMIN用户赋予操作定时任务的权限。定时任务操作权限与高级包DBE_SCHEDULER中创建定时任务赋权操作一致。
  • 定时任务时间间隔表达式目前虽然已经兼容浮点数语法(如:interval 0.5 minute),但在计算时会将浮点数进行取整,因此不建议时间间隔表达式使用浮点数形式。
  • 定时任务中,待执行语句范围是除安全相关操作以外的任意SQL语句,但对于某些具有约束的SQL语句会执行失败。例如:不支持通过复合语句创建数据库。
  • 定时任务待执行语句不支持的安全相关操作范围主要包括:
    • 使用加密函数。
    • 创建/设置用户、创建/设置GROUP。
    • 连接数据库。
    • 函数加密等。
  • 定时任务指定DEFINER选项在以下场景下会指定失败:
    • 操作定时任务的用户不具有SYSADMIN权限。
    • 当前用户与被指定DEFINER不一致时:
      • 指定DEFINER为初始用户。
      • 指定DEFINER为运维管理员、监控管理员。
      • 开启三权分立,enableSeparationOfDuty=on。
  • 当定时任务的待执行语句中进行涉及用户密码相关操作时,系统表中会记录密码的明文,因此不建议用户在定时任务的待执行语句中进行涉及用户密码的相关操作。
  • 定时任务创建完成后如果执行失败,失败原因可以通过SHOW EVENTS;或在PG_JOB表中查看。

语法格式

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;

参数说明

  • DEFINER = user

    定时任务待执行语句在执行时使用的权限。默认情况下,使用当前创建定时任务者的权限,当明确指定时,使用被指定用户的用户权限。

    仅具有SYSADMIN权限的用户可以指定该关键字。

  • event_name

    创建的定时任务的名称。同一数据库中下,不支持创建同名的定时任务,可通过指定IF NOT EXISTS关键字进行避免创建同名定时任务。

  • ON SCHEDULE schedule
    定时任务执行时刻。定时任务可以设置为执行一次,也可以设置执行多次。schedule具体格式如下:
    1
    2
    3
    4
    5
    6
    { 
        AT timestamp [{+ INTERVAL interval} [...]]
      | EVERY interval
        [{STARTS timestamp} [{+ INTERVAL interval} [...]]]
        [{ENDS timestamp} [{+ INTERVAL interval} [...]]]
    }
    

    其中,interval表示时间间隔,由数字和单位组成(如:1 YEAR)。具体格式如下:

    quantity 
             {YEAR | MONTH | DAY | HOUR | MINUTE | SECOND |
              YEAR TO MONTH | DAY TO HOUR | DAY TO MINUTE |
              DAY TO SECOND | HOUR TO MINUTE | HOUR TO SECOND | 
              MINUTE TO SECOND}

    当设置兼容性参数b_format_version = '5.7'以及b_format_dev_version = 's1'时,interval的取值可以使用下划线(_)代替TO,如:YEAR_MONTH、DAY_HOUR。

    • AT timestamp [+ INTERVAL interval]:表示设置定时任务只在指定的时间间隔点执行一次。
    • EVERY interval:表示设置定时任务在每隔指定的时间间隔后重复执行。
      • STARTS timestamp [+ INTERVAL interval]:用户可以为可重复执行的定时任务指定起始时间,即定时任务从指定的时刻开始执行。未指定时,默认从当前时刻开始执行。
      • ENDS timestamp [+ INTERVAL interval]:用户可以为可重复执行的定时任务指定结束时间,即定时任务从指定的时刻停止执行。未指定时,默认为3999-12-31 16:00:00。
  • ON COMPLETION [NOT] PRESERVE

    可选,定时任务在执行完毕后,是否自动从数据库系统表中删除该任务。未指定该选项时,一旦定时任务执行完毕,系统表中就会立刻删除该定时任务,与显式指定ON COMPLETION NOT PRESERVE选项效果相同。用户可以通过设置ON COMPLETION PRESERVE进行覆盖默认行为。

  • ENABLE | DISABLE | DISABLE ON SLAVE

    创建定时任务后,定时任务默认处于ENABLE状态,即到达规定时间立即执行待执行的语句。用户可以使用DISABLE关键字,改变定时任务的活动状态。

    DISABLE ON SLAVE效果与DISABLE相同。

  • COMMENT 'string'

    用户可以为定时任务添加注释,注释内容可在GS_JOB_ATTRIBUTE表中查看。

  • DO

    定时任务待执行的语句。

示例

--创建并切换至测试数据库。
gaussdb=# CREATE DATABASE test_event WITH DBCOMPATIBILITY = 'B';
gaussdb=# \c test_event

--创建表。
test_event=# CREATE TABLE t_ev(num int);

--创建一个执行一次的定时任务,五秒后执行一次,执行完后定时任务自动删除。
test_event=# CREATE EVENT IF NOT EXISTS event_e1 ON SCHEDULE AT sysdate + interval 5 second DO INSERT INTO t_ev VALUES(0);

--五秒后查询表。
test_event=# SELECT * FROM t_ev;
 num 
-----
   0
(1 row)

--创建一个每隔一分钟执行一次的定时任务。
test_event=# CREATE EVENT IF NOT EXISTS event_e2 ON SCHEDULE EVERY 1 minute DO INSERT INTO t_ev VALUES(1);

--每隔一分钟查询表,会看到新增一条数据。
test_event=# SELECT * FROM t_ev;
 num 
-----
   0
   1
   1
(3 rows)

--删除定时任务。
test_event=# DROP EVENT event_e2;

--删除表。
test_event=# DROP TABLE t_ev;

--切换回初始数据库,并删除测试数据库。请用真实的数据库名替换postgres。
test_event=#\c postgres
gaussdb=# DROP DATABASE test_event;

相关文档