这里说明 pg_cron 插件的简介及使用方法。
一、概述
pg_cron 是数据库内的定时任务调度插件，使用标准 cron 表达式定时执行 SQL 命令，可用于定时清理数据、定时统计、周期性维护等场景。
二、支持版本
| PostgreSQL 版本 | 内核版本 |
| PostgreSQL 10 | v10.23_r1.20及以上 |
| PostgreSQL 11 | v11.22_r1.35及以上 |
| PostgreSQL 12 | v12.22_r1.37及以上 |
| PostgreSQL 13 | v13.22_r1.32及以上 |
| PostgreSQL 14 | v14.22_r1.42及以上 |
| PostgreSQL 15 | v15.14_r1.27及以上 |
| PostgreSQL 16 | v16.10_r1.22及以上 |
| PostgreSQL 17 | v17.10_r1.22及以上 |
| PostgreSQL 18 | v18.3_r1.6及以上 |
注意：说明：
注意：你可在控制台实例详情页查看当前实例的内核版本，或执行 SHOW tencentdb_version; 查询。
三、插件简介
pg_cron 在数据库内以后台进程方式运行，定时任务的调度信息存储在 cron.job 表中。任务到点执行时，pg_cron 会按任务中记录的命令在目标数据库执行，并将每次运行的结果记录到 cron.job_run_details 表中。
四、环境准备
pg_cron 是需要预加载的插件，使用前请确认实例已加载该插件：
1. 在控制台参数设置的 shared_preload_libraries 参数中勾选 pg_cron，保存后重启实例。参数设置方法可参考 设置实例参数。
2. 连接到 cron.database_name 参数指定的数据库（默认 postgres），执行以下语句创建扩展：
postgres=> CREATE EXTENSION pg_cron;CREATE EXTENSION
注意：说明：
注意：pg_cron 的扩展只能在 cron.database_name 参数指定的数据库中创建，否则会报错。
五、创建任务
以下示例先创建一张测试表，用于演示定时插入任务：
postgres=> CREATE TABLE cron_demo(ts timestamptz DEFAULT now());CREATE TABLE
六、基础创建
使用 cron.schedule 函数创建任务，第一个参数为 cron 表达式，第二个参数为要执行的命令：
postgres=> SELECT cron.schedule('* * * * *', 'INSERT INTO cron_demo DEFAULT VALUES;'); schedule———- 1(1 row)
返回值为任务 ID（jobid）。上述语句表示每分钟执行一次插入操作。
七、指定任务名创建
你也可以为任务指定一个名称，便于后续管理：
postgres=> SELECT cron.schedule('five-min', '*/5 * * * *', 'SELECT now();'); schedule———- 2(1 row)
八、cron 表达式说明
cron 表达式由5个字段组成，依次表示：分钟、小时、日期、月份、星期：
| 字段 | 取值范围 | 说明 |
| 分钟 | 0 – 59 | 每分钟用 *，每5分钟用 */5 |
| 小时 | 0 – 23 | 每小时用 *，凌晨2点用 2 |
| 日期 | 1 – 31 | 每天用 *，每月1号用 1 |
| 月份 | 1 – 12 | 每月用 *，1月用 1 |
| 星期 | 0 – 7 | 0和7均表示周日 |
九、查看任务
查询 cron.job 表查看已创建的任务：
postgres=> SELECT jobid, jobname, schedule, command, username, active FROM cron.job ORDER BY jobid; jobid | jobname | schedule | command | username | active——-+———-+————-+—————————————+———-+——– 1 | | * * * * * | INSERT INTO cron_demo DEFAULT VALUES; | root | t 2 | five-min | */5 * * * * | SELECT now(); | root | t(2 rows)
cron.job 表主要字段说明：
| 字段 | 说明 |
| jobid | 任务 ID，创建时自动分配 |
| jobname | 任务名称，创建时指定 |
| schedule | cron 表达式 |
| command | 要执行的命令 |
| database | 任务执行的目标数据库 |
| username | 执行任务的用户 |
| active | 是否启用，t 表示启用，f 表示停用 |
十、修改任务
使用 cron.alter_job 函数修改任务。第一个参数为任务 ID，其余参数按需传入要修改的字段：
postgres=> SELECT cron.alter_job(2, schedule => '*/2 * * * *', command => 'SELECT now();'); alter_job———–(1 row)
上述语句将任务2的调度周期改为每2分钟执行一次，命令保持不变。
十一、按任务名删除
postgres=> SELECT cron.unschedule('five-min'); unschedule———— t(1 row)
返回 t 表示删除成功。
十二、按任务 ID 删除
postgres=> SELECT cron.unschedule(1); unschedule———— t(1 row)
十三、查看运行记录
任务每次执行后，运行结果记录在 cron.job_run_details 表中：
postgres=> SELECT jobid, status, return_message, start_time, end_time FROM cron.job_run_details ORDER BY runid DESC LIMIT 2; jobid | status | return_message | start_time | end_time——-+———–+—————-+——————————-+——————————- 3 | succeeded | INSERT 0 1 | 2026-09-03 11:42:00.003175+08 | 2026-09-03 11:42:00.006969+08(1 row)
字段说明：
| 字段 | 说明 |
| status | 执行状态，succeeded 表示成功，failed 表示失败 |
| return_message | 命令的完成消息，如 INSERT 0 1 表示成功插入1行 |
| start_time / end_time | 任务开始和结束时间 |
十四、参数说明
pg_cron 的相关参数如下：
| 参数 | 默认值 | 说明 |
| cron.database_name | postgres | 存放 pg_cron 元数据的数据库，修改需重启 |
| cron.max_running_jobs | 5 | 允许同时运行的最大任务数，修改需重启 |
| cron.timezone | GMT | 调度时区，修改需重启 |
注意：说明：
注意：上述参数的修改方式请以控制台参数设置为准。操作请参考 设置实例参数。
十五、Q：创建扩展时提示只能在指定数据库创建？
A：pg_cron 的扩展只能在 cron.database_name 参数指定的数据库中创建。请先确认当前连接的数据库是否与 cron.database_name 一致，或通过控制台修改该参数后重试。
十六、Q：任务执行失败如何排查？
A：查询 cron.job_run_details 表，查看失败任务的 status 和 return_message 字段，其中记录了执行状态和错误信息。
十七、相关参考
pg_cron 产品文档