文档首页/ 云数据库 GaussDB/ 开发指南（主备版_3.x）/ 存储过程/ 高级包/ 二次封装接口(推荐)/ DBE_SCHEDULER
更新时间：2024-05-07 GMT+08:00
查看PDF
分享

DBE_SCHEDULER

接口介绍

高级功能包DBE_SCHEDULER支持通过调度（schedule）和程序（program）更加灵活的创建定时任务。支持的所有接口请见表1。

表1 DBE_SCHEDULER

接口名称

描述

DBE_SCHEDULER.CREATE_JOB

创建定时任务。

DBE_SCHEDULER.DROP_JOB

删除定时任务。

DROP_SINGLE_JOB

删除单个定时任务。

DBE_SCHEDULER.SET_ATTRIBUTE

设置对象属性。

DBE_SCHEDULER.RUN_JOB

运行定时任务。

DBE_SCHEDULER.RUN_BACKEND_JOB

后台运行定时任务。

DBE_SCHEDULER.RUN_FOREGROUND_JOB

前台运行定时任务。

DBE_SCHEDULER.STOP_JOB

停止定时任务。

DBE_SCHEDULER.STOP_SINGLE_JOB

停止单个定时任务。

DBE_SCHEDULER.GENERATE_JOB_NAME

生成定时任务名。

DBE_SCHEDULER.CREATE_PROGRAM

创建程序。

DBE_SCHEDULER.DEFINE_PROGRAM_ARGUMENT

定义程序参数。

DBE_SCHEDULER.DROP_PROGRAM

删除程序。

DBE_SCHEDULER.DROP_SINGLE_PROGRAM

删除单个程序。

DBE_SCHEDULER.SET_JOB_ARGUMENT_VALUE

设置定时任务参数值。

DBE_SCHEDULER.CREATE_SCHEDULE

创建调度。

DBE_SCHEDULER.DROP_SCHEDULE

删除调度。

DBE_SCHEDULER.DROP_SINGLE_SCHEDULE

删除单个调度。

DBE_SCHEDULER.CREATE_JOB_CLASS

创建定时任务类。

DBE_SCHEDULER.DROP_JOB_CLASS

删除定时任务类。

DBE_SCHEDULER.DROP_SINGLE_JOB_CLASS

删除单个定时任务类。

DBE_SCHEDULER.GRANT_USER_AUTHORIZATION

赋予用户特殊权限。

DBE_SCHEDULER.REVOKE_USER_AUTHORIZATION

撤销用户特殊权限。

DBE_SCHEDULER.CREATE_CREDENTIAL

创建证书。

DBE_SCHEDULER.DROP_CREDENTIAL

销毁证书。

DBE_SCHEDULER.ENABLE

启用对象。

DBE_SCHEDULER.ENABLE_SINGLE

启动单个对象。

DBE_SCHEDULER.DISABLE

停用对象。

DBE_SCHEDULER.DISABLE_SINGLE

停用单个对象。

DBE_SCHEDULER.EVAL_CALENDAR_STRING

分析Calendar格式字符串。

DBE_SCHEDULER.EVALUATE_C...

分析Calendar格式字符串。
  • DBE_SCHEDULER.CREATE_JOB

    创建一个定时任务。

    DBE_SCHEDULER.CREATE_JOB函数原型可以分为4种：

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
    		 
    -- 内联调度和程序的定时任务
DBE_SCHEDULER.CREATE_JOB(
job_name TEXT,
job_type TEXT,
job_action TEXT,
number_of_arguments INTEGER             DEFAULT 0,
start_date TIMESTAMP WITH TIME ZONE     DEFAULT NULL,
repeat_interval TEXT                    DEFAULT NULL,
end_date TIMESTAMP WITH TIME ZONE       DEFAULT NULL,
job_class TEXT            DEFAULT 'DEFAULT_JOB_CLASS',
enabled BOOLEAN                         DEFAULT FALSE,
auto_drop BOOLEAN                       DEFAULT TRUE,
comments TEXT                           DEFAULT NULL,
credential_name TEXT                    DEFAULT NULL,
destination_name TEXT                   DEFAULT NULL
)

-- 引用创建好的调度和程序的定时任务
DBE_SCHEDULER.CREATE_JOB(
job_name TEXT,
program_name TEXT,
schedule_name TEXT,
job_class TEXT            DEFAULT 'DEFAULT_JOB_CLASS',
enabled BOOLEAN                         DEFAULT FALSE,
auto_drop BOOLEAN                       DEFAULT TRUE,
comments TEXT                           DEFAULT NULL,
job_style TEXT                          DEFAULT 'REGULAR',
credential_name TEXT                    DEFAULT NULL,
destination_name TEXT                   DEFAULT NULL
)

-- 引用创建好的程序，内联调度的定时任务
DBE_SCHEDULER.CREATE_JOB(
job_name text,
program_name TEXT,
start_date TIMESTAMP WITH TIME ZONE     DEFAULT NULL,
repeat_interval TEXT                    DEFAULT NULL,
end_date TIMESTAMP WITH TIME ZONE       DEFAULT NULL,
job_class TEXT            DEFAULT 'DEFAULT_JOB_CLASS',
enabled BOOLEAN                         DEFAULT FALSE,
auto_drop BOOLEAN                       DEFAULT TRUE,
comments TEXT                           DEFAULT NULL,
job_style TEXT                          DEFAULT 'REGULAR',
credential_name TEXT                    DEFAULT NULL,
destination_name TEXT                   DEFAULT NULL
)

-- 引用创建好的调度，内联程序的定时任务
DBE_SCHEDULER.CREATE_JOB(
job_name TEXT,
schedule_name TEXT,
job_type TEXT,
job_action TEXT,
number_of_arguments INTEGER             DEFAULT 0,
job_class TEXT             DEFAULT 'DEFAULT_JOB_CLASS',
enabled BOOLEAN                         DEFAULT FALSE,
auto_drop BOOLEAN                       DEFAULT TRUE,
comments TEXT                           DEFAULT NULL,
credential_name TEXT                    DEFAULT NULL,
destination_name TEXT                   DEFAULT NULL
)

    利用DBE_SCHEDULER创建的定时任务不会与DBE_TASK中的定时任务相冲突。

    DBE_SCHEDULER创建的定时任务会生成对应的job_id，但是在使用过程中这个id并没有实际意义。

    表2 DBE_SCHEDULER.CREATE_JOB接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    job_name

    text

    IN

    否

    定时任务名称。

    job_type

    text

    IN

    否
    定时任务内联程序类型，可用类型为：
    • 'PLSQL_BLOCK'：匿名存储过程快。
    • 'STORED_PROCEDURE'：保存的存储过程。
    • 'EXTERNAL_SCRIPT'：外部脚本。

    job_action

    text

    IN

    否

    定时任务内联程序执行内容。

    number_of_arguments

    integer

    IN

    否

    定时任务内联程序参数个数。

    program_name

    text

    IN

    否

    定时任务引用程序名称。

    start_date

    timestamp with time zone

    IN

    是

    定时任务内联调度起始时间。

    repeat_interval

    text

    IN

    是

    定时任务内联调度任务周期。

    end_date

    timestamp with time zone

    IN

    是

    定时任务内联调度失效时间。

    schedule_name

    text

    IN

    否

    定时任务引用调度名称。

    job_class

    text

    IN

    否

    定时任务类名。

    enabled

    boolean

    IN

    否

    定时任务启用状态。

    auto_drop

    boolean

    IN

    否

    定时任务自动删除。

    comments

    text

    IN

    是

    备注。

    job_style

    text

    IN

    否

    定时任务行为模式，仅支持‘REGULAR'。

    credential_name

    text

    IN

    是

    定时任务证书名。

    destination_name

    text

    IN

    是

    定时任务目标名。
    示例： 
    1
2
3
    		 
    CALL DBE_SCHEDULER.create_job(job_name=>'job1', program_name=>'program1', schedule_name=>'schedule1');
CALL DBE_SCHEDULER.create_job(job_name=>'job1', job_type=>'STORED_PROCEDURE', job_action=>'select pg_sleep(1);');
CALL DBE_SCHEDULER.create_job('job1', 'program1', '2021-07-20', 'interval ''3 minute''', '2121-07-20', 'DEFAULT_JOB_CLASS', false, false,'test', 'style', NULL, NULL);

    创建'EXTERNAL_SCRIPT'类型的定时任务需要管理员赋予相关的权限和证书，且需要数据库启动用户对该外部脚本有读取权限才可以正常生效。

  • DBE_SCHEDULER.DROP_JOB

    删除定时任务。

    DBE_SCHEDULER.DROP_JOB函数原型为：

    1
2
3
4
5
6
    		 
    DBE_SCHEDULER.drop_job(
job_name text,
force boolean                           default false,
defer boolean                           default false,
commit_semantics text      default 'STOP_ON_FIRST_ERROR'
)

    DBE_SCHEDULER.DROP_JOB可以指定一个、多个任务，或指定任务类进行定时任务删除。

    表3 DBE_SCHEDULER.DROP_JOB接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    job_name

    text

    IN

    否

    定时任务或定时任务类名称，可以指定一个或多个，当指定多个定时任务时需要利用逗号隔开

    force

    boolean

    IN

    否

    删除定时任务行为标记位

    true：尝试先停止当前定时任务，再进行删除

    false：如果定时任务正在运行会删除失败

    defer

    boolean

    IN

    否

    删除定时任务行为标记位

    true：允许定时任务完成后再进行删除

    commit_semantics

    text

    IN

    否

    提交规则：

    'STOP_ON_FIRST_ERROR'：在第一个报错之前的删除操作会提交

    'TRANSACTIONAL'：事物级提交，报错前的删除操作会回滚

    'ABSORB_ERRORS'：尝试越过报错，将成功的删除操作提交
    示例： 
    1
    		 
    CALL DBE_SCHEDULER.drop_job('job1', true, false, 'STOP_ON_FIRST_ERROR');

    commit_semantic中的'TRANSACTIONAL'选项必须在force为false的情况下才会生效。

  • DBE_SCHEDULER.DROP_SINGLE_JOB

    删除一个定时任务。

    DBE_SCHEDULER.DROP_SINGLE_JOB函数原型为：

    1
2
3
4
5
    		 
    DBE_SCHEDULER.drop_single_job(
job_name text,
force boolean                           default false,
defer boolean                           default false
)
  • DBE_SCHEDULER.SET_ATTRIBUTE

    修改定时任务属性。

    DBE_SCHEDULER.SET_ATTRIBUTE函数4种原型为：

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
    		 
    DBE_SCHEDULER.set_attribute(
name                    text,
attribute               text,
value                   boolean
)

DBE_SCHEDULER.set_attribute(
name                    text,
attribute               text,
value                   text
)

DBE_SCHEDULER.set_attribute(
name                    text,
attribute               text,
value                   timestamp
)

DBE_SCHEDULER.set_attribute(
name                    text,
attribute               text,
value                   timestamp with time zone
)

DBE_SCHEDULER.set_attribute(
name text,
attribute text,
value text,
value2 text                             default NULL
)

    name在这里可以指定任何DBE_SCHEDULE内部的对象。

    表4 DBE_SCHEDULER.SET_ATTRIBUTE接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    name

    text

    IN

    否

    对象名。

    attribute

    text

    IN

    否

    属性名。

    value

    boolean/date/timestamp/timestamp with time zone/text

    IN

    否
    属性值，可选属性如下：
    • 定时任务相关：job_type, job_action, number_of_arguments, start_date, repeat_interval, end_date, job_class, enabled, auto_drop, comments, credential_name, destination_name, program_name, schedule_name, job_style。
    • 程序相关：program_action, program_type, number_of_arguments, comments。
    • 调度相关：start_date, repeat_interval, end_date, comments。

    value2

    text

    IN

    是

    额外属性值。保留参数位，目前尚不支持拥有额外属性值的目标属性。
    示例： 
    1
2
    		 
    CALL DBE_SCHEDULER.set_attribute('program1', 'number_of_arguments', 0);
CALL DBE_SCHEDULER.set_attribute('program1', 'program_type', 'STORED_PROCEDURE');

    不要使用DBE_SCHEDULER.SET_ATTRIBUTE来将参数置空。

    对象名不能通过DBE_SCHEDULER.SET_ATTRIBUTE来更改。

  • DBE_SCHEDULER.RUN_JOB

    运行定时任务。

    DBE_SCHEDULER.RUN_JOB函数原型为：

    1
2
3
4
    		 
    DBE_SCHEDULER.run_job(
job_name text,
use_current_session boolean             default true
)

    DBE_SCHEDULER.RUN_JOB主要用于立即运行定时作业，独立于定时任务本身的调度，甚至可以同时运行。

    表5 DBE_SCHEDULER.RUN_JOB接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    job_name

    text

    IN

    否

    定时任务名称，可以指定一个或多个，当指定多个定时任务时需要利用逗号隔开

    use_current_session

    boolean

    IN

    否

    运行定时任务标志位：

    true：使用当前会话运行，主要用于查看定时任务是否可以正常运行

    false：后台拉起定时任务，运行结果会打印到日志中
    示例： 
    1
    		 
    CALL DBE_SCHEDULER.run_job('job1', false);

    use_current_session不能用于打印执行结果。

  • DBE_SCHEDULER.RUN_BACKEND_JOB

    后台运行定时任务。

    DBE_SCHEDULER.RUN_BACKEND_JOB函数原型为：

    1
2
3
    		 
    DBE_SCHEDULER.run_backend_job(
job_name text
)
  • DBE_SCHEDULER.RUN_FOREGROUND_JOB

    当前会话运行定时任务。

    仅支持运行external 类型任务。

    返回值：text。

    DBE_SCHEDULER.RUN_FOREGROUND_JOB函数原型为：

    1
2
3
    		 
    DBE_SCHEDULER.run_foreground_job(
job_name text
)return text
  • DBE_SCHEDULER.STOP_JOB

    终止定时任务。

    DBE_SCHEDULER.STOP_JOB函数原型为：

    1
2
3
4
5
    		 
    DBE_SCHEDULER.stop_job(
job_name text,
force boolean                           default false,
commit_semantics text                   default 'STOP_ON_FIRST_ERROR'
)
    表6 DBE_SCHEDULER.STOP_JOB接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    job_name

    text

    IN

    否

    定时任务或定时任务类名称，可以指定一个或多个，当指定多个定时任务时需要利用逗号隔开。

    force

    boolean

    IN

    否
    删除定时任务行为标记位：
    • true：调度器会发送终止信号立即结束任务线程。
    • false：调度器会尝试利用打断信号终止定时任务线程。

    commit_semantics

    text

    IN

    否
    提交规则：
    • 'STOP_ON_FIRST_ERROR'：在第一个报错之前的打断操作会提交。
    • 'ABSORB_ERRORS'：尝试越过报错，将成功的打断操作提交。
  • DBE_SCHEDULER.STOP_SINGLE_JOB

    终止单个定时任务。

    DBE_SCHEDULER.STOP_SINGLE_JOB函数原型为：

    1
2
3
4
    		 
    DBE_SCHEDULER.stop_single_job(
job_name text,
force boolean                           default false
)
  • DBE_SCHEDULER.GENERATE_JOB_NAME

    生成定时任务名称。

    DBE_SCHEDULER.GENERATE_JOB_NAME函数原型为：

    1
2
3
    		 
    DBE_SCHEDULER.generate_job_name(
prefix text                             default 'JOB$_'
)return text

首次执行DBE_SCHEDULER.GENERATE_JOB_NAME会在public下创建一个临时序列用于保存当前名称的序号。由于普通用户没有在public下create权限，因此如果普通用户为当前db下第一次调用该函数，会失败，需要授权该普通用户在public下的create权限，或者使用有该权限的用户调用该接口以创建临时序列。

  • DBE_SCHEDULER.CREATE_PROGRAM

    创建程序。

    DBE_SCHEDULER.CREATE_PROGRAM函数原型为：

    1
2
3
4
5
6
7
8
    		 
    DBE_SCHEDULER.create_program(
program_name text,
program_type text,
program_action text,
number_of_arguments integer             default 0,
enabled boolean                         default false,
comments text                           default NULL
)
  • DBE_SCHEDULER.DEFINE_PROGRAM_ARGUMENT

    定义程序参数。

    修正带默认值default_value字段的接口默认转换成小写行为，现字符大小写做出区分。

    DBE_SCHEDULER.DEFINE_PROGRAM_ARGUMENT函数原型为：

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
    		 
    DBE_SCHEDULER.define_program_argument(
program_name text,
argument_position integer,
argument_name text                      default NULL,
argument_type text,
out_argument boolean                    default false
)

-- 带有默认值 --
DBE_SCHEDULER.define_program_argument(
program_name text,
argument_position integer,
argument_name text                      default NULL,
argument_type text,
default_value text,
out_argument boolean                    default false
)

  • DBE_SCHEDULER.DROP_PROGRAM

    删除程序。

    DBE_SCHEDULER.DROP_PROGRAM函数原型为：

    1
2
3
4
    		 
    DBE_SCHEDULER.drop_program(
program_name text,
force boolean                           default false
)
  • DBE_SCHEDULER.DROP_SINGLE_PROGRAM

    删除单个程序。

    DBE_SCHEDULER.DROP_SINGLE_PROGRAM函数原型为：

    1
2
3
4
    		 
    DBE_SCHEDULER.drop_single_program(
program_name text,
force boolean                           default false
)
  • DBE_SCHEDULER.SET_JOB_ARGUMENT_VALUE

    设置定时任务参数值。argument_value字段支持赋空入参。

    DBE_SCHEDULER.SET_JOB_ARGUMENT_VALUE函数原型为：

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    		 
    DBE_SCHEDULER.set_job_argument_value(
job_name text,
argument_position integer,
argument_value text
)

DBE_SCHEDULER.set_job_argument_value(
job_name text,
argument_name text,
argument_value text
)

  • DBE_SCHEDULER.CREATE_SCHEDULE

    创建调度。

    DBE_SCHEDULER.CREATE_SCHEDULE函数原型为：

    1
2
3
4
5
6
7
    		 
    DBE_SCHEDULER.create_schedule(
schedule_name text,
start_date timestamp with time zone     default NULL,
repeat_interval text,
end_date timestamp with time zone       default NULL,
comments text                           default NULL
)

  • DBE_SCHEDULER.DROP_SCHEDULE

    删除调度。

    DBE_SCHEDULER.DROP_SCHEDULE函数原型为：

    1
2
3
4
    		 
    DBE_SCHEDULER.drop_schedule(
schedule_name text,
force boolean                           default false
)
  • DBE_SCHEDULER.DROP_SINGLE_SCHEDULE

    删除单个调度。

    DBE_SCHEDULER.DROP_SINGLE_SCHEDULE函数原型为：

    1
2
3
4
    		 
    DBE_SCHEDULER.drop_single_schedule(
schedule_name text,
force boolean                           default false
)
  • DBE_SCHEDULER.CREATE_JOB_CLASS

    创建定时任务类。

    DBE_SCHEDULER.CREATE_JOB_CLASS函数原型为：

    1
2
3
4
5
6
7
8
    		 
    DBE_SCHEDULER.create_job_class(
job_class_name text,
resource_consumer_group text            default NULL,
service text                            default NULL,
logging_level integer                   default 0,
log_history integer                     default NULL,
comments text                           default NULL
)

  • DBE_SCHEDULER.DROP_JOB_CLASS

    删除定时任务类。

    DBE_SCHEDULER.DROP_JOB_CLASS函数原型为：

    1
2
3
4
    		 
    DBE_SCHEDULER.drop_job_class(
job_class_name text,
force boolean                           default false
)
  • DBE_SCHEDULER.DROP_SINGLE_JOB_CLASS

    删除单个定时任务类。

    DBE_SCHEDULER.DROP_SINGLE_JOB_CLASS函数原型为：

    1
2
3
4
    		 
    DBE_SCHEDULER.drop_single_job_class(
job_class_name text,
force boolean                           default false
)
  • DBE_SCHEDULER.GRANT_USER_AUTHORIZATION

    为数据库用户提供定时任务权限。调用该函数的用户需要具有SYSADMIN权限。

    DBE_SCHEDULER.GRANT_USER_AUTHORIZATION函数原型为：

    1
2
3
4
    		 
    DBE_SCHEDULER.grant_user_authorization(
username                text,
privilege               text
)

  • DBE_SCHEDULER.REVOKE_USER_AUTHORIZATION

    撤销数据库用户的定时任务权限。调用该函数的用户需要具有SYSADMIN权限。

    DBE_SCHEDULER.REVOKE_USER_AUTHORIZATION函数原型为：

    1
2
3
4
    		 
    DBE_SCHEDULER.revoke_user_authorization(
username                text,
privilege               text
)

  • DBE_SCHEDULER.CREATE_CREDENTIAL

    创建授权证书。调用该函数的用户需要具有SYSADMIN权限。

    DBE_SCHEDULER.CREATE_CREDENTIAL函数原型为：

    1
2
3
4
5
6
7
8
    		 
    DBE_SCHEDULER.create_credential(
credential_name         text,
username                text,
password                text            default NULL,
database_role           text            default NULL,
windows_domain          text            default NULL,
comments                text            default NULL
)

DBE_SCHEDULER.CREATE_CREDENTIAL的password字段请传NULL或者'******',该参数仅做兼容性，不代表实际含义。禁止使用安装用户对应的os用户名创建证书。

  • DBE_SCHEDULER.DROP_CREDENTIAL

    销毁授权证书。调用该函数的用户需要具有SYSADMIN权限。

    DBE_SCHEDULER.DROP_CREDENTIAL函数原型为：

    1
2
3
4
    		 
    DBE_SCHEDULER.drop_credential(
credential_name  text,
force            boolean default false      
)

  • DBE_SCHEDULER.ENABLE

    启用对象。

    DBE_SCHEDULER.ENABLE函数原型为：

    1
2
3
4
    		 
    DBE_SCHEDULER.enable(
name text,
commit_semantics text                   default 'STOP_ON_FIRST_ERROR'
)

  • DBE_SCHEDULER.ENABLE_SINGLE

    启用单个对象。

    DBE_SCHEDULER.ENABLE_SINGLE函数原型为：

    1
2
3
    		 
    DBE_SCHEDULER.enable_single(
name text
)
  • DBE_SCHEDULER.DISABLE

    禁用对象。

    DBE_SCHEDULER.DISABLE函数原型为：

    1
2
3
4
5
    		 
    DBE_SCHEDULER.disable(
name text,
force boolean                           default false,
commit_semantics text                   default 'STOP_ON_FIRST_ERROR'
)

  • DBE_SCHEDULER.DISABLE_SINGLE

    禁用单个对象。

    DBE_SCHEDULER.DISABLE_SINGLE函数原型为：

    1
2
3
4
    		 
    DBE_SCHEDULER.disable_single(
name text,
force boolean                           default false
)
  • DBE_SCHEDULER.EVAL_CALENDAR_STRING

    分析调度任务周期。

    返回值类型：timestamp with time zone

    DBE_SCHEDULER.EVAL_CALENDAR_STRING函数原型为：

    1
2
3
4
5
    		 
    DBE_SCHEDULER.evaluate_calendar_string(
IN calendar_string text,
IN start_date timestamp with time zone,
IN return_date_after timestamp with time zone
)return timestamp with time zone
  • DBE_SCHEDULER.EVALUATE_CALENDAR_STRING

    分析调度任务周期。

    DBE_SCHEDULER.EVALUATE_CALENDAR_STRING函数原型为：

    1
2
3
4
5
6
    		 
    DBE_SCHEDULER.evaluate_calendar_string(
IN calendar_string text,
IN start_date timestamp with time zone,
IN return_date_after timestamp with time zone,
OUT next_run_date timestamp with time zone
)return timestamp with time zone