pg_cron - PolarDB: Central de Documentação do Alibaba Cloud

Pré-requisitos

O pg_cron é compatível com clusters do PolarDB for PostgreSQL nas seguintes versões:

PostgreSQL 14, versão de revisão 14.9.14.0 ou posterior
PostgreSQL 11, versão de revisão 1.1.1 ou posterior

Para verificar a versão de revisão, execute um dos comandos a seguir:

-- PostgreSQL 14
SELECT version();

-- PostgreSQL 11
SHOW polar_version;

Problema conhecido: alteração de porta na reinicialização do cluster

Em clusters com versão secundária do mecanismo 14.10.16.0 ou anterior, a reinicialização altera a porta do cluster e causa falhas nas tarefas do pg_cron. A versão secundária do mecanismo 14.10.16.1 e posteriores corrigem esse problema.

Funcionamento

Armazenamento de tarefas agendadas

A tabela cron.job armazena todas as tarefas agendadas. Durante a inicialização do banco de dados, o pg_cron cria uma JOB LIST e uma TASK LIST em memória com base nessa tabela. O gatilho cron.job_cache_invalidate mantém essas listas sincronizadas com a cron.job em tempo real sempre que você adiciona, modifica ou remove tarefas.

Ciclo de vida da execução de tarefas

Cada tarefa passa pelos seguintes estados:

Estado	Descrição
WAITING	Estado padrão. A tarefa aguarda o horário agendado e as condições de ativação.
START	Estabelece as informações de conexão e executa um teste de conectividade. Em caso de sucesso, avança para CONNECTING; caso contrário, vai para ERROR.
CONNECTING	Verifica o status de ativação e a integridade da conexão. Se bem-sucedido, transita para SENDING; se houver falha, vai para ERROR.
SENDING	Envia a tarefa ao servidor PolarDB for PostgreSQL. Transita para RUNNING em caso de sucesso ou para ERROR em caso de falha.
RUNNING	Aguarda o resultado da tarefa. Avança para DONE após conclusão bem-sucedida ou para ERROR se ocorrer falha.
ERROR	Indica falha na tarefa. Redefine as informações de conexão e segue para DONE.
DONE	Tarefa concluída. Redefine as informações da tarefa e retorna ao estado WAITING.

Permissões

Somente contas privilegiadas podem criar, modificar e excluir tarefas agendadas. Contas padrão têm acesso somente leitura à tabela cron.job.

O banco de dados postgres armazena todas as tarefas agendadas. Conecte-se ao postgres para gerenciar as tarefas.

Todas as tarefas usam o Horário de Greenwich (GMT). Converta seu horário local para GMT antes de definir um agendamento.

Ativar o pg_cron

Conecte-se ao banco de dados postgres e execute:

CREATE EXTENSION pg_cron;

Para remover a extensão:

DROP EXTENSION pg_cron;

Gerenciar tarefas agendadas

Criar uma tarefa

Use cron.schedule para criar uma tarefa no banco de dados atual ou cron.schedule_in_database para especificar um banco de dados de destino.

cron.schedule

SELECT cron.schedule(
    'job_name',   -- Task name (optional)
    'schedule',   -- Cron expression
    'command'     -- SQL statement to run
);
-- Returns: jobid (BIGINT)

Parâmetro	Tipo	Descrição
`job_name`	TEXT	Nome da tarefa. Opcional; deixe em branco para criar uma tarefa sem nome.
`schedule`	TEXT	Expressão cron que define quando a tarefa será executada.
`command`	TEXT	Instrução SQL a executar.

cron.schedule_in_database

SELECT cron.schedule_in_database(
    'job_name',   -- Task name
    'schedule',   -- Cron expression
    'command',    -- SQL statement to run
    'db_name'     -- Target database
);
-- Returns: jobid (BIGINT)

Parâmetro	Tipo	Descrição
`job_name`	TEXT	Nome da tarefa.
`schedule`	TEXT	Expressão cron que define quando a tarefa será executada.
`command`	TEXT	Instrução SQL a executar.
`db_name`	TEXT	Banco de dados onde a tarefa será executada.

Exemplo: Crie uma tarefa chamada task1 que executa SELECT 1 a cada minuto no banco de dados db01.

SELECT cron.schedule_in_database('task1', '* * * * *', 'SELECT 1', 'db01');

 schedule_in_database
----------------------
                    1
(1 row)

O valor retornado é o ID da tarefa (jobid).

Visualizar tarefas

SELECT * FROM cron.job;

 jobid | schedule  | command  | nodename | nodeport | database | username | active | jobname
-------+-----------+----------+----------+----------+----------+----------+--------+---------
     1 | * * * * * | SELECT 1 | /tmp     |    39361 | db01     | u1       | t      | task1
(1 row)

Modificar uma tarefa

SELECT cron.alter_job(
    job_id   => 1,              -- Task ID (required)
    schedule => '0 10 * * *',  -- New schedule (optional)
    command  => 'VACUUM;',     -- New SQL statement (optional)
    db_name  => 'db01',        -- New target database (optional)
    active   => true           -- Enable or disable the task (optional)
);

Parâmetro	Tipo	Descrição
`job_id`	BIGINT	ID da tarefa a modificar. Obrigatório.
`schedule`	TEXT	Nova expressão cron. Omita para manter o valor atual.
`command`	TEXT	Nova instrução SQL. Omita para manter o valor atual.
`db_name`	TEXT	Novo banco de dados de destino. Omita para manter o valor atual.
`active`	BOOLEAN	Defina como `true` para ativar ou `false` para desativar a tarefa. Omita para manter o valor atual.

Informe apenas os parâmetros que deseja alterar. Os parâmetros omitidos mantêm os valores atuais.

Excluir uma tarefa

-- Delete by task ID
SELECT cron.unschedule(1);

-- Delete by task name
SELECT cron.unschedule('task1');

 unschedule
------------
 t
(1 row)

Visualizar histórico de execução

SELECT * FROM cron.job_run_details ORDER BY start_time DESC LIMIT 10;

 jobid | runid | job_pid | database | username | command  |  status   | return_message |          start_time           |           end_time
-------+-------+---------+----------+----------+----------+-----------+----------------+-------------------------------+-------------------------------
     1 |     2 | 4152438 | db01     | u1       | SELECT 1 | succeeded | 1 row          | 2023-10-19 03:56:00.006468+00 | 2023-10-19 03:56:00.006822+00
     1 |     1 | 4152316 | db01     | u1       | SELECT 1 | succeeded | 1 row          | 2023-10-19 03:55:00.020442+00 | 2023-10-19 03:55:00.021512+00
(2 rows)

A coluna status aceita três valores:

Status	Descrição
`running`	Tarefa em execução.
`succeeded`	Tarefa concluída com sucesso.
`failed`	Falha na tarefa. Consulte `return_message` para obter detalhes do erro.

Para filtrar tarefas com falha:

SELECT * FROM cron.job_run_details WHERE status = 'failed' ORDER BY start_time DESC;

Referência de expressões cron

O pg_cron usa o formato padrão de expressão cron:

┌───────────── Minute (0–59)
│ ┌────────────── Hour (0–23)
│ │ ┌─────────────── Day of month (1–31)
│ │ │ ┌──────────────── Month (1–12)
│ │ │ │ ┌───────────────── Day of week (0–6, where 0 and 7 = Sunday)
│ │ │ │ │
* * * * *

Padrões comuns de agendamento:

Expressão	Agendamento
`* * * * *`	A cada minuto
`/5 * * *`	A cada 5 minutos
`23 * * * *`	Toda hora, aos 23 minutos
`0 10 * * *`	Diariamente às 10:00 GMT
`0 0 * * 1-5`	Dias úteis à meia-noite GMT
`30 3 * * 6`	Sábados às 03:30 GMT
`* * 4 * *`	A cada minuto no dia 4 de cada mês

Exemplos:

-- Run VACUUM every day at 10:00 GMT
SELECT cron.schedule('nightly-vacuum', '0 10 * * *', 'VACUUM;');

-- Delete events older than one week every Saturday at 03:30 GMT
SELECT cron.schedule('weekly-cleanup', '30 3 * * 6',
    $$DELETE FROM events WHERE event_time < now() - interval '1 week'$$);

-- Run a query every minute
SELECT cron.schedule('heartbeat', '* * * * *', 'SELECT 1;');