本文为您介绍 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 | t2 | 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 字段，其中记录了执行状态和错误信息。
