cron_utils

概览

The PGXN 0.1.0 distribution is marked unstable; the control file marks the extension relocatable.

版本

构建

您可以使用 pig build 命令构建 cron_utils 扩展的 RPM / DEB 包：

pig build pkg cron_utils         # 构建 RPM / DEB 包

安装

您可以直接安装 cron_utils 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：

pig repo add pgsql -u          # 添加仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展：

• 安装
• pig
• dnf
• apt

pig install cron_utils;          # 当前活跃 PG 版本安装

pig ext install -y cron_utils -v 18  # PG 18
pig ext install -y cron_utils -v 17  # PG 17
pig ext install -y cron_utils -v 16  # PG 16
pig ext install -y cron_utils -v 15  # PG 15
pig ext install -y cron_utils -v 14  # PG 14

dnf install -y cron_utils_18       # PG 18
dnf install -y cron_utils_17       # PG 17
dnf install -y cron_utils_16       # PG 16
dnf install -y cron_utils_15       # PG 15
dnf install -y cron_utils_14       # PG 14

apt install -y postgresql-18-cron-utils   # PG 18
apt install -y postgresql-17-cron-utils   # PG 17
apt install -y postgresql-16-cron-utils   # PG 16
apt install -y postgresql-15-cron-utils   # PG 15
apt install -y postgresql-14-cron-utils   # PG 14

创建扩展：

CREATE EXTENSION cron_utils;

用法

来源：

• pg_cron_utils 0.1.0 README
• Extension control file
• SQL definitions

cron_utils 解析五字段 cron 表达式并在 PostgreSQL 中计算触发时间戳。它是一个调度工具，而不是作业执行器：使用它可以预览、验证或查询一个计划，并单独使用 pg_cron 等调度程序来执行工作。

核心流程

CREATE EXTENSION cron_utils;

-- First trigger at or after the supplied time.
SELECT cron_first_trigger('0 9 * * 1-5', now());

-- Last trigger before the supplied time (strict is true by default).
SELECT cron_last_trigger('0 9 * * 1-5', now());

-- Next five hourly triggers.
SELECT *
FROM cron_iterate_n('0 * * * *', now(), false, 'next', 5);

要检查一个限定窗口：

SELECT *
FROM cron_first_last_triggers(
  '0 0 * * *',
  date_trunc('month', now()),
  date_trunc('month', now()) + interval '1 month'
);

当表达式在窗口中没有触发时，返回的边界可以是 NULL。

重要对象

• cron_parts 是分钟、小时、日、月和周字段的解析表示。
• parse_cron(text) 解析 *、列表、范围以及步进语法。
• cron_first_trigger(expr, base_time, strict) 向前搜索。当 strict = true 时，会跳过在 base_time 精确匹配的情况。
• cron_last_trigger(expr, base_time, strict) 向后搜索，默认为严格匹配。
• cron_first_last_triggers(expr, start_time, end_time) 返回窗口中的第一个和最后一个匹配项。
• cron_iterate_n(expr, base_time, strict, direction, max_matches) 按 next 或 prev 方向返回连续的匹配项。

语义与注意事项

表达式使用标准的五个字段 minute hour day month dow；秒不被接受。周字段使用 1 = Monday 到 7 = Sunday 的表示方式。结果为 timestamptz，因此会话时区会影响显示的本地时间，并且对于本地时间计划应测试夏令时转换。

该扩展是纯 SQL/PL/pgSQL 实现的，可重定位且没有依赖于 pg_cron。其函数声明为不可变且并行安全。0.1.0 版本在控制元数据中标记为 unstable，因此在将其嵌入关键调度程序之前，请锁定行为并重新测试边缘情况。