PostgreSQL扩展实战：uuid-ossp与pg_cron的安装、配置与业务应用

我在生产环境里第一次大规模引入 PostgreSQL 扩展，是被一套带 UUID 主键的业务表给推着走的。当时导数据、做同步、排查主键冲突，连续折腾了好几天，最后发现把 uuid-ossp 和 pg_cron 这两个扩展用好，很多“看着麻烦”的事情其实一两句 SQL 就能解决。这两个扩展一个管数据标识怎么生成，一个管数据库内部任务怎么定时跑，都属于安装简单、但对日常维护收益极高的类型。这篇就从实际使用角度，把它们的安装、配置、踩坑和真实业务场景完整拆一遍。

1. 先想清楚：PostgreSQL 扩展机制到底是什么

很多刚接触 PostgreSQL 的人会有一个疑问：好好的数据库，为什么还要装“插件”？实际上这是 PostgreSQL 一个非常核心的设计思路——内核保持精简，把特定功能以扩展模块的形式提供，你要用哪个就在哪个数据库里启用哪个。扩展不是独立运行的进程，它通常由三部分组成：编译好的动态库（.so 文件）、控制文件（.control）、以及若干 SQL 脚本。执行 CREATE EXTENSION 时，数据库会读取脚本，把函数、数据类型、甚至操作符注册到当前库中。

正是这种机制，让不同业务场景可以按需拼装能力。比如你要生成 UUID 主键，就启用 uuid-ossp；要让数据库自己定时执行清理任务，就启用 pg_cron。扩展之间互不干扰，该有的权限划分也在数据库内部完成。对开发运维人员来说，这比在外部额外搭建服务、写脚本、维护定时器要轻量得多。

1.1 为什么是 uuid-ossp 和 pg_cron

PostgreSQL 官方 contrib 包和社区里能用的扩展非常多，但 uuid-ossp 和 pg_cron 基本属于“高频工具型”扩展。uuid-ossp 负责生成通用唯一标识符，尤其在微服务、数据同步、多环境合并场景中几乎绕不开；pg_cron 则解决的是数据库内部任务调度问题，比如定时清理过期数据、定时 vacuum、自动建分区。

我个人的判断标准很简单：uuid-ossp 解决的是“数据定位”的问题，pg_cron 解决的是“数据维护”的问题。两者各自独立，但经常一起出现。比如你用 UUID 做业务主键，同时又要定时往这张表里写入统计数据，那“表结构设计”和“定时任务调度”刚好对应这两个扩展。这也是我用它们用得最顺手的原因。

1.2 版本与运行环境对扩展的影响

扩展能不能顺利装上，很大程度上由 PostgreSQL 版本和操作系统决定。uuid-ossp 通常随 postgresql-contrib 包一起提供，版本兼容性较好；pg_cron 则更像一个“半官方”扩展，在一些 Linux 发行版中需要额外仓库支持，且目前不支持 Windows。这个限制要提前知道，否则在 Windows 环境折腾半天会发现根本不支持。

我常用的环境是 PostgreSQL 15/16，运行在 Debian 系和 CentOS 系服务器上。实际测试下来，这两个版本上安装流程一致，只是在“创建扩展”后能否直接使用函数上有些细节差异。比如 PostgreSQL 13 之后内置了 gen_random_uuid()，很多人拿它跟 uuid-ossp 对比，这个后文会专门讲。

提示：任何时候动手前，先看当前实例版本。扩展不是装上就能用，它必须和 PostgreSQL 二进制版本匹配，尤其是源码编译方式，稍不注意就会因为路径或编译参数不对导致“控制文件找不到”。

2. 安装准备：先把地基打牢

很多安装失败的案例，最后定位下来都不是扩展本身的问题，而是环境信息没对齐。所以在执行安装命令前，我习惯先把三件事确认清楚：PostgreSQL 版本、扩展源码位置、服务器架构。

2.1 查看版本与关键路径

直接用 psql 连入数据库，查看当前版本：

sql复制SELECT version();

或者用命令行工具查看：

bash复制psql --version
pg_config --version

如果是在编译安装 PostgreSQL 的机器上，还需要确认扩展安装目录和动态库目录：

bash复制pg_config --pkglibdir
pg_config --sharedir

--pkglibdir 是动态库的安装目录，--sharedir 是扩展 SQL 脚本和控制文件要放的位置。很多源码安装扩展踩坑，就是因为 pg_config 指向的不是当前运行的 PostgreSQL 实例，而是系统里另一套版本。所以在源码编译时候，确认 PATH 中 pg_config 的路径是第一优先级非常关键，否则扩展装到了错误的版本目录里，重启后依然加载不了。

2.2 使用系统包管理器安装

如果服务器上 PostgreSQL 是通过 apt、yum 安装的，优先用系统包管理器，这样依赖关系最省心。

Debian/Ubuntu 环境，uuid-ossp 通常随 contrib 包提供：

bash复制sudo apt install postgresql-contrib-15

其中“15”要和服务器上 PostgreSQL 大版本一致。装好以后，直接在数据库里执行：

sql复制CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

pg_cron 在 Debian/Ubuntu 下一般可以直接用 PostgreSQL 官方源里的包，不同发行版后期维护差异较大。我自己常用的是：

bash复制sudo apt install postgresql-15-cron

CentOS/Rocky 环境则是：

bash复制sudo yum install postgresql15-contrib
sudo yum install postgresql15-cron

这些包安装完成后，扩展文件会落到 PostgreSQL 对应的扩展目录中。使用 CREATE EXTENSION 之前，可以用下面这条 SQL 确认扩展是否已经能被数据库识别：

sql复制SELECT name, default_version, installed_version FROM pg_available_extensions WHERE name IN ('uuid-ossp', 'pg_cron');

如果能在结果里看到这两个扩展，说明装好了，接下来直接启用就行。

2.3 源码编译安装 pg_cron 的步骤

如果用的是自定义安装的 PostgreSQL，或者发行版仓库里没有现成包，那就得走源码编译。pg_cron 本身是开源项目，直接拉取源码编译即可。

bash复制git clone https://github.com/citusdata/pg_cron.git
cd pg_cron
make
sudo make install

这里的 make 会自动调用当前 shell PATH 里的 pg_config，所以前文提到的路径问题在这里影响非常大。如果 PostgreSQL 安装路径比较特殊，可以手动指定：

bash复制make PG_CONFIG=/usr/local/pgsql/bin/pg_config
sudo make install PG_CONFIG=/usr/local/pgsql/bin/pg_config

装好后验证一下：

bash复制ls $(pg_config --pkglibdir) | grep cron
ls $(pg_config --sharedir)/extension | grep cron

能看到 pg_cron.so 和 pg_cron--1.x.sql 等文件，就算成功。

2.4 Docker 环境下的差异

很多朋友是在 Docker 里跑 PostgreSQL，这种方式和宿主机安装还是有区别的。容器是临时和可重建的，直接在容器里用 apt 安装扩展，容器一删就全没了，所以最好在 Dockerfile 或者初始化脚本里处理。如果你用 postgres:15 镜像，可以先装系统依赖再装 contrib：

dockerfile复制FROM postgres:15
RUN apt-get update \
    && apt-get install -y postgresql-contrib-15 postgresql-15-cron \
    && rm -rf /var/lib/apt/lists/*

如果只是临时验证功能，也可以进入容器后手动安装，容器删除后重新初始化。需要注意，docker 镜像如果使用官方 entrypoint，它会自动执行 /docker-entrypoint-initdb.d/ 下的脚本，想要初始化时就创建扩展，可以把 CREATE EXTENSION 放进该目录的 .sql 脚本里。pg_cron 的 shared_preload_libraries 配置需要在容器启动命令或自定义 postgresql.conf 中预先注入。

3. UUID-OSSP：给业务主键一个严谨的唯一标识

3.1 快速启用 uuid-ossp

在选定数据库里执行：

sql复制CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

注意扩展名带引号，为什么？因为扩展包内部名称带有连字符，PostgreSQL 在解析 SQL 时会把它当成普通标识符处理，不带引号会报语法错误。这在官方文档里也写了，很多新手第一次执行时都会在这里卡一下。

启用后查看函数：

sql复制SELECT proname FROM pg_proc WHERE pronamespace = 'uuid-ossp'::regnamespace;

如果函数存在，就可以正常使用 uuid_generate_v4() 等函数了。

3.2 uuid-ossp 核心函数逐个说清

uuid-ossp 提供的函数有好几个，很多文档看一眼就过去了，但实际选型时每个函数差别很大。

uuid_generate_v1() 是基于时间戳、时钟序列和 MAC 地址生成的版本 1 UUID，理论上具有时间顺序性，连续生成的值大致递增。但因为会暴露网卡 MAC 地址，生产环境有一定安全隐患，所以我很少直接用。uuid_generate_v1mc() 是“同款但替换了 MAC 地址为随机值”的变体，既保留了时间递增特性，又适当规避了泄漏问题，在需要近似单调递增时可以考虑。

uuid_generate_v4() 就是大家最常见的随机 UUID，通过加密级随机数生成，每次调用结果几乎没有碰撞可能，但因为是随机值，用来做数据库主键时，插入顺序和索引顺序完全不一致，在数据量大的情况下容易引起 B-tree 索引页分裂和写放大。

uuid_generate_v3(namespace, name) 和 uuid_generate_v5(namespace, name) 是确定性 UUID，也就是说输入相同，输出的 UUID 永远相同。v3 用 MD5，v5 用 SHA-1，后者更推荐。它们的用途不是生成随机主键，而是根据业务唯一键生成一个稳定的业务 UUID，比如根据用户 ID 加“订单”命名空间生成 UUID，这样同一用户在相同场景下得到的 UUID 完全一致，就能天然用来做幂等判断。

另外两个辅助函数容易被忽略：uuid_nil() 返回全零 UUID，用来做空值占位再合适不过；uuid_ns_url()、uuid_ns_dns() 等函数提供了标准命名空间常量，在调用 v3/v5 函数时作为第一个参数使用。

各版本函数对比如下：

3.3 PostgreSQL 13 之后也可以用内置 gen_random_uuid()

PostgreSQL 13 起，数据库自带的 pgcrypto 扩展里提供了一个非常常用的函数 gen_random_uuid()，它就是生成一串 v4 随机 UUID。如果只需要“随机 UUID 主键”，可以不用 uuid-ossp，直接启用 pgcrypto：

sql复制CREATE EXTENSION IF NOT EXISTS pgcrypto;
SELECT gen_random_uuid();

那 uuid-ossp 是不是没有存在价值了？不是。因为 uuid-ossp 里还提供了 v1、v3、v5 等函数，这些是 gen_random_uuid() 替代不了的。另外很多历史项目、旧版本数据库已经基于 uuid-ossp 设计了序列对象和函数依赖，直接替换需要做整体评估。我的建议是：新项目如果只是要 v4 UUID，可以直接用内置函数，减少一个扩展依赖；但如果要用 v5 做确定性 UUID，或者需要时间递增类 UUID，还是得用 uuid-ossp。两者不是简单的替代关系。

3.4 用 UUID 做业务表主键的实战写法

下面这个例子比较接近真实场景。假设有一个用户表，主键希望由应用层生成，减少数据库层的主键压力，同时兼顾多环境数据合并。

sql复制CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE TABLE app_user (
    user_id uuid PRIMARY KEY DEFAULT uuid_generate_v4(),
    account_name varchar(64) NOT NULL UNIQUE,
    email varchar(128),
    created_at timestamptz NOT NULL DEFAULT now()
);

之后插入数据时，就可以完全不关心主键值：

sql复制INSERT INTO app_user (account_name, email) VALUES ('zhangsan', 'zhangsan@example.com');

插入完成后要拿主键值，配合 RETURNING 即可：

sql复制INSERT INTO app_user (account_name, email)
VALUES ('lisi', 'lisi@example.com')
RETURNING user_id;

这套设计和自增 BIGSERIAL 主键比，最核心的优势是“全局唯一”。不同业务库独立生成也不会冲突，非常适合分库分表、数据汇总、多环境同步等场景。很多数据库同步工具在 PostgreSQL、MySQL、SQL Server 之间流转数据，如果主键是自增整数，常常要处理源端和目标端主键范围冲突；换成 UUID 后直接省掉一大半烦恼。

不过也别迷信 UUID。如果单表单日写入量极大，或者对二级索引维护非常敏感，随机 UUID 主键会让聚簇索引频繁页分裂。为了缓解这个影响，可以搭配 uuid_generate_v1mc() 或考虑把主键与“创建时间+序列号”做组合，或者使用支持时序 UUID 的扩展。这是设计取舍，不是非黑即白。

4. PG-CRON：让数据库自己按计划干活

4.1 核心配置：shared_preload_libraries

pg_cron 和 uuid-ossp 最大的不同在于，它是后台工作进程，不是简单的函数集合，所以必须在 PostgreSQL 启动时先预加载动态库。编辑 postgresql.conf：

ini复制shared_preload_libraries = 'pg_cron'
cron.database_name = 'postgres'

cron.database_name 这个参数很关键。pg_cron 的元数据表存放在指定数据库中，默认值并不想当然地等于你当前所在的库。如果不设置，大多数版本会使用 postgres 库作为元数据库，因此我的做法是把 postgres 设为调度任务管理库，然后在其他业务库里进行任务调用。

改完配置文件后必须重启 PostgreSQL 服务：

bash复制sudo systemctl restart postgresql

重启后，通过下面的 SQL 可以验证共享库是否加载成功：

sql复制SHOW shared_preload_libraries;

如果要检查后台进程，也可以直接看系统进程：

bash复制ps aux | grep cron

正常情况下，你会看到名为 postgres: pg_cron launcher 的进程。没有这个进程，基本上后面所有 cron.schedule 调用都会白执行。

4.2 在数据库中创建 pg_cron 扩展

预加载库不等于在数据库里创建扩展，还需要手动执行：

sql复制CREATE EXTENSION IF NOT EXISTS pg_cron;

这一步会创建 cron schema，以及 cron.job、cron.job_run_details 等系统表，并注册 cron.schedule()、cron.unschedule() 等函数。创建完成后查看任务表：

sql复制SELECT jobid, jobname, schedule, command, active FROM cron.job;

如果当前用户没有权限，会提示 function 不存在或 schema 权限不足。通常需要超级用户或对应 schema 的权限来创建扩展。

注意：pg_cron 的官方支持平台是 Linux 和 macOS，Windows 目前不支持。Windows 尝试配置时，安装动态库这一步就能挂掉。如果是 Windows Docker 里跑 Linux 容器，那其实还有救；宿主机直接跑 Windows 版 PostgreSQL 则不建议浪费时间。

4.3 创建第一个定时任务：清理会话表

这里用一个实际例子说明基本用法。假设有一张 user_session 登录会话表，里面记录 expired_at 过期时间。每天晚上 3 点清理过期会话，SQL 定义如下。

sql复制SELECT cron.schedule(
    'clean-expired-session',
    '0 3 * * *',
    $$DELETE FROM user_session WHERE expired_at < now() - interval '7 days'$$
);

cron.schedule 有三个参数时，分别是任务名、cron 表达式、要执行的 SQL。执行上面的语句后，会返回一个 jobid，比如 1。通过 cron.job 表可以看到任务注册成功：

sql复制SELECT jobid, jobname, schedule, command, active
FROM cron.job;

任务会不会执行成功，要去看执行日志：

sql复制SELECT jobid, status, return_message, start_time, end_time
FROM cron.job_run_details
ORDER BY start_time DESC
LIMIT 10;

status 字段包号表示执行成功，返回错误码或异常信息时会记录在 return_message 中。这个表是排查 pg_cron 问题时的第一落点。

修改任务的执行计划，最稳妥的做法是删除并重建任务：

sql复制SELECT cron.unschedule('clean-expired-session');
SELECT cron.schedule('clean-expired-session', '0 4 * * *', $$DELETE FROM user_session WHERE expired_at < now() - interval '7 days'$$);

虽然也可以直接 UPDATE cron.job SET schedule = ... WHERE jobname = ...，但我一般不建议手动改系统表，容易把状态弄乱，还是走函数接口更安全。

4.4 实战二：定时 VACUUM，处理膨胀和 WAL 增长

很多 PostgreSQL 运维都会遇到 WAL 日志占用磁盘越来越大，死元组多、长时间不 vacuum 是常见原因之一。数据库默认 autovacuum 可以兜底，但大表在业务高峰期触发自动 vacuum 会让 IO 飙得厉害，所以更推荐在低峰期用 pg_cron 固定时间手动做一次。

创建定时 vacuum 任务：

sql复制SELECT cron.schedule(
    'manual-vacuum-main-table',
    '30 2 * * *',
    $$VACUUM (ANALYZE) main_table$$
);

VACUUM (ANALYZE) 会同时更新优化器统计信息，对查询计划质量很有帮助。如果有多张大表，可以在一个任务里排列多条语句，但我个人更建议一张大表一个任务，或者用存储过程统一管理，方便看每张表的执行状态。VACUUM 命令不能在事务块内执行，pg_cron 对这个场景有特别处理，实测直接写 VACUUM 是支持的。如果你要通过存储过程调用 VACUUM，必须用 dblink 或查询包装之类的手段，这反而会让问题复杂化。

顺带一提，监控磁盘如果发现 WAL 目录暴涨，先把 pg_stat_activity 里长时间 idle in transaction 的连接干掉，再回头查死元组比例。定时 vacuum 是用来“防患于未然”的，不是用来救火的。

4.5 实战三：自动创建下月分区表

分区表越来越多地被用在日志类和流水类业务中。PostgreSQL 原生的分区表功能加上 pg_cron，可以在每月月底自动把下个月的分区建出来。假设定义了一个按月分区的订单表 order_log，分区名为 order_log_202502。

先建一个辅助函数：

sql复制CREATE OR REPLACE FUNCTION create_next_month_partition()
RETURNS void AS $$
DECLARE
    next_month date;
    partition_name text;
BEGIN
    next_month := date_trunc('month', now()) + interval '1 month';
    partition_name := 'order_log_' || to_char(next_month, 'YYYYMM');
    IF NOT EXISTS (
        SELECT 1 FROM pg_class WHERE relname = partition_name
    ) THEN
        EXECUTE format(
            'CREATE TABLE %I PARTITION OF order_log FOR VALUES FROM (%L) TO (%L)',
            partition_name,
            next_month,
            next_month + interval '1 month'
        );
    END IF;
END;
$$ LANGUAGE plpgsql;

用 pg_cron 把函数挂在每月 1 日凌晨执行：

sql复制SELECT cron.schedule(
    'create-next-partition',
    '0 1 1 * *',
    $$SELECT create_next_month_partition()$$
);

这种方式对于大规模流水数据维护非常实用，避免人工漏建分区导致应用写入失败。类似的逻辑还可以扩展为自动删除三个月前的旧分区，进一步控制磁盘占用。

4.6 pg_cron 和外部 crontab 怎么选

很多老运维习惯在服务器上写 crontab，定时用 psql 执行脚本，这当然也能用。但 pg_cron 的优势在于任务和数据库耦合在一起，权限体系、执行记录、事务状态一目了然。数据库集群迁移时，只要把 cron.job 里的任务重建，就不必再单独维护服务器 crontab。对高可用架构来说，还需要考虑主备切换后任务只应在主节点执行的问题。因为备库并不具备写入能力，任务如果因为备库启动而执行，会直接报只读错误。

pg_cron 也没有内置重试机制，它只负责“到点执行 SQL”，执行失败会在 cron.job_run_details 记录错误信息，不会自动告警。所以使用时要结合监控系统，定时检查 job_run_details 表中是否有新的失败记录，或直接对日志做报警。任务能否落库成功，并不能完全等于业务执行成功，这是外部 cron 和 pg_cron 共有的局限。

5. 两个插件配合：UUID 主键和定时任务一起用的场景

既然题目同时聊 UUID-OSSP 和 PG-CRON，那就顺手讲一下这两个插件在同一个业务里如何协同，让它们不只是“各管各的工具”。

5.1 定时任务写入带 UUID 的业务表

假设我们每天要从第三方接口拉取一条汇总数据，并且希望每次拉取结果都有唯一的 UUID 标识，方便追溯和比对。那么我在 cron 任务里可以直接引用 uuid_generate_v4() 作为默认值，或者显式调用函数。

先建一张拉取记录表：

sql复制CREATE TABLE sync_record (
    record_id uuid PRIMARY KEY DEFAULT uuid_generate_v4(),
    source varchar(32) NOT NULL,
    sync_date date NOT NULL,
    row_count int,
    finished_at timestamptz NOT NULL DEFAULT now()
);

再用 pg_cron 在每天凌晨自动插入记录。为了演示，假设把“同步动作”封装成函数 do_sync()，它内部完成后返回日志文本。

sql复制CREATE OR REPLACE FUNCTION do_sync_api_data()
RETURNS void AS $$
BEGIN
    INSERT INTO sync_record (source, sync_date, row_count)
    VALUES ('api-order', current_date, 12345);
END;
$$ LANGUAGE plpgsql;

SELECT cron.schedule(
    'nightly-sync',
    '20 0 * * *',
    $$SELECT do_sync_api_data()$$
);

这样，每次同步记录都自动获得 UUID 主键，后续排错只要拿到 record_id，就能从日志、链路追踪系统里反查整个任务执行过程。它同时体现了 UUID 的可生成、“不依赖中心序号”的特性，也体现了 pg_cron 对定时调度的便利性。

5.2 用确定性 UUID 做跨库合并的幂等键

很多处在 MySQL、SQL Server、PostgreSQL 共存环境中的项目，会使用同步工具做增量数据汇合。多库同步时，最怕的就是主键冲突。一次全量导入或增量重放如果重复执行，轻则产生重复数据，重则直接报主键冲突中断任务。

确定性 UUID 可以在这里发挥稳定作用。比如业务订单在源系统里有一个唯一单号 order_no = 'A10001'，在 PostgreSQL 同步表里可以用同一个“订单命名空间+源单号”生成幂等主键：

sql复制SELECT uuid_generate_v5(
    uuid_ns_url(),
    'order-A10001'
);

这样不管数据从哪个源系统重放多少次，只要单号一致，生成的 UUID 永远一致。重放时配合 ON CONFLICT DO UPDATE 或 ON CONFLICT DO NOTHING，就实现了天然的幂等写入。

sql复制INSERT INTO sync_order (order_id, order_no, product_name, updated_at)
VALUES (
    uuid_generate_v5(uuid_ns_url(), 'order-A10001'),
    'A10001',
    '商品A',
    now()
)
ON CONFLICT (order_id)
DO UPDATE SET product_name = EXCLUDED.product_name,
              updated_at = EXCLUDED.updated_at;

这个场景正是 uuid-ossp 中 v5 函数无法被替代的核心价值。如果你只需要 uuid-ossp 来做这件事，就不必为了“随机主键”再装 pgcrypto。

5.3 配合时的索引与分区设计提醒

当一个表同时用 UUID 主键，又希望用 pg_cron 做分区维护时，分区键的选择要特别小心。如果你把随机 UUID 作为分区键做 range 分区，那新插入的数据会随机落到各个分区，每个分区都有随机写入，既让分区裁剪失效，也让索引膨胀速度变快。比较好的折衷是：业务主键用 UUID 保证唯一性，但分区键单独选择 created_at 这类时间字段，让 pg_cron 按月建分区，数据写入集中在当前时间分区。这样既享受了 UUID 的全局唯一，又避免了随机值带来的索引和分区问题。

6. 踩坑报告：安装和使用阶段的高频问题

6.1 找不到扩展控制文件

报错信息通常类似 extension "uuid-ossp" has no installation script nor update path for version "1.1" 或者 could not open extension control file ... No such file or directory。

这类问题绝大多数是扩展文件没有安装到正确的位置。先检查 pg_config --sharedir 和 pg_config --pkglibdir 对应的目录里有没有对应文件，再检查你是不是有多个 PostgreSQL 版本。Debian 下尤其容易发生系统里同时存在 PostgreSQL 14 和 15，psql 连接的是 15，安装包装的却是 14 的 contrib，导致文件去了另一个版本目录。处理办法是安装与运行版本一致的 contrib 包，或者重新配置编译路径。

6.2 执行 CREATE EXTENSION 提示权限不足

PostgreSQL 中对创建扩展有权限门槛，只有具备超级用户权限或者具备数据库 owner 权限的用户才能执行 CREATE EXTENSION。如果使用普通业务账号执行，会报 permission denied to create extension。

这样处理：用超级用户先在指定库创建扩展，再把函数的使用权限授权给业务角色。如果扩展创建在 public schema 下，普通用户可以通过 public 的默认权限调用函数；但如果创建在 uuid-ossp 这个独立 schema 下，需要显式授权：

sql复制GRANT USAGE ON SCHEMA "uuid-ossp" TO app_user;
GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA "uuid-ossp" TO app_user;

pg_cron 的 schema 是 cron，业务用户如果要查看任务状态，也要授予相应权限。

6.3 pg_cron 任务创建成功，但从不执行

这是 pg_cron 最经典的坑。cron.schedule() 返回了 jobid，查 cron.job 也能看到记录，但预定时间到了任务就是不跑。第一优先级检查 shared_preload_libraries 有没有配置成功，因为只创建扩展但没预加载库，任务只是被记录了，不会被执行。检查方式就是 SHOW shared_preload_libraries; 和 ps aux | grep cron。

另一个可能是你创建扩展的数据库和 cron.database_name 不一致。pg_cron 的后台进程只在 cron.database_name 指向的数据库里启动，如果任务是通过其他库创建，理论上也行，但有些版本下会因为连接数据库的问题导致任务不触发。统一把任务放在 postgres 库中管理是最省事的方案。

6.4 任务执行时间不对，差了 8 小时

pg_cron 对时间的解析和数据库客户端的时区不一定一致。如果你把任务设在 '0 3 * * *'，期望是本地时间凌晨 3 点执行，结果却在早上 8 点执行，大概率是默认时区使用了 UTC。新版 pg_cron 一般可以通过 cron.timezone 配置改时区：

ini复制cron.timezone = 'Asia/Shanghai'

修改后重启服务，或者使用 ALTER SYSTEM SET cron.timezone 后 reload，重新调度任务。老版本不支持该参数时，最稳妥的做法是统一把 cron 表达式写成 UTC 时间，例如期望北京时间凌晨 3 点执行，就填 '0 19 * * *'。这类问题最坑的地方在于看起来像是任务没执行，其实只是执行时间和你的预期不同，排查时一定先看执行日志里的 start_time。

6.5 主备切换后任务行为异常

如果 PostgreSQL 做了高可用部署，pg_cron 任务不判断实例当前是主库还是备库，备库也会尝试执行任务。备库默认只读，执行写操作会报 cannot execute INSERT in a read-only transaction。建议在定时调用的函数或命令前加一层判断：

sql复制CREATE OR REPLACE FUNCTION maintenance_if_primary()
RETURNS void AS $$
BEGIN
    IF pg_is_in_recovery() THEN
        RETURN;
    END IF;
    -- 执行维护逻辑
END;
$$ LANGUAGE plpgsql;

这样任务在备库上即使被触发，也会立即返回，不会产生无意义的错误日志。

6.6 常见问题速查表

6.7 一个小习惯：任务命名和注释

在生产环境中，我给 pg_cron 任务命名时遵循明确的前缀规则，例如 vacuum-、clean-、archive-、sync-，这样在 cron.job 表里扫一遍就能知道哪类任务多。同时给每个任务留一个“最近执行状态”的检查视图，比如直接查看 cron.job_run_details 最近 100 条里有没有失败记录：

sql复制SELECT jobname, status, start_time, return_message
FROM cron.job
JOIN cron.job_run_details USING (jobid)
ORDER BY start_time DESC
LIMIT 100;

这个视图帮我解决过好几次半夜任务静默失败的问题。pg_cron 本身不会发告警，只有主动查日志才会发现异常，所以把这个检查放到日常巡检脚本里非常有必要。

在我实际操作的过程中，最大的体会是：数据库扩展不是“装上就好”的东西，它涉及版本匹配、目录路径、重启生效、时区、权限体系等多个层面的协作。uuid-ossp 和 pg_cron 本身并不难，难的是当你把它们放进一个有主备、有同步、有多环境、有安全审计的生产系统时，每一个细节都可能变成问题来源。写这篇文章不是想给出一个“标准答案”，而是希望大家能带着自己的业务场景去理解这两个工具：先想清楚要解决什么问题，再决定用哪个函数、配哪种调度策略，最后再用任务日志和监控把它跑稳。