ApsaraDB RDS:Use the pg_cron extension

Visão geral

O pg_cron é um agendador baseado no cron e compartilha a mesma sintaxe. Execute comandos SQL para configurar tarefas agendadas. Para obter mais informações, consulte pg_cron.

Uma tarefa agendada consiste em um cronograma e uma ação. Esta seção usa uma tarefa agendada como exemplo para descrever essas duas partes. Configure a tarefa executando o seguinte comando: SELECT cron.schedule('30 3 * * 6', $$DELETE FROM events WHERE event_time < now() - interval '1 week'$$);.

• Cronograma

  Esta parte define quando o sistema usa a extensão pg_cron para executar a tarefa. Especifique o cronograma seguindo a mesma sintaxe das expressões cron padrão. Nessa sintaxe, um caractere curinga de asterisco (**) em um campo indica que a tarefa é executada em qualquer momento definido pelo campo, enquanto um valor numérico indica que a tarefa é executada apenas no momento exato especificado por esse valor. No exemplo de tarefa agendada, o cronograma é 30 3 * * 6, o que determina a execução da tarefa às 03:30:00 (UTC) de cada sábado.

   ┌───────────── Minute: 0 to 59
   │ ┌────────────── Hour: 0 to 23
   │ │ ┌─────────────── Date: 1 to 31
   │ │ │ ┌──────────────── Month: 1 to 12
   │ │ │ │ ┌───────────────── Day of the week: 0 to 6 (The value 0 indicates Sunday.)
   │ │ │ │ │                  
   │ │ │ │ │
   │ │ │ │ │
   * * * * *

  Para criar e validar o cronograma de uma tarefa agendada do pg_cron, acesse crontab.guru.

• Ação

  Esta parte define a operação que a tarefa deve realizar durante a execução. No exemplo de tarefa agendada, a ação é $$DELETE FROM events WHERE event_time < now() - interval '1 week'$$, o que instrui a tarefa agendada a excluir dados expirados de uma tabela chamada events.

Pré-requisitos

• Sua instância RDS executa o PostgreSQL 10 ou superior.

• A versão secundária do mecanismo da sua instância RDS é 20250430 ou superior.

  Importante

  Algumas versões secundárias do mecanismo anteriores a 20250430 também oferecem suporte a esta extensão. No entanto, o ApsaraDB RDS planeja otimizar as extensões suportadas nas atualizações de versão secundária para padronizar o gerenciamento de extensões e aumentar a segurança contra vulnerabilidades. Por isso, não é possível criar esta extensão em instâncias RDS com versão secundária do mecanismo anterior a 20250430. Para obter mais informações, consulte Restrictions on extension creation for RDS for PostgreSQL.

  • Se você já criou esta extensão em uma instância RDS com versão secundária do mecanismo anterior a 20250430, continue a utilizá-la.

  • Se estiver criando esta extensão pela primeira vez ou precisar recriá-la na sua instância RDS, atualize a versão secundária do mecanismo da instância para a versão mais recente. Para obter mais informações, consulte Update the minor engine version.

• Uma conta privilegiada foi criada. Para obter mais informações, consulte Create an account.

Observações de uso

• Por padrão, o horário especificado no cronograma de uma tarefa agendada segue o fuso UTC. Converta o horário conforme o parâmetro TIMEZONE do banco de dados, se necessário. Se a tarefa agendada não for acionada, execute o comando abaixo para configurar uma tarefa de execução a cada minuto e verifique se a extensão funciona corretamente.

  SELECT cron.schedule('* * * * *', 'SELECT 1;');

• As tarefas agendadas configuradas ficam armazenadas em um banco de dados padrão chamado postgres. Visualize essas tarefas em outros bancos de dados.

• A extensão pg_cron é instalada no banco de dados definido pelo parâmetro cron.database_name, cujo valor padrão é postgres. Para instalar a extensão pg_cron em outro banco de dados, modifique o valor do parâmetro cron.database_name. Para obter mais informações, consulte Set instance parameters. A instalação da extensão pg_cron reinicia a instância. Instale a extensão em horários de baixa demanda.

• Instâncias RDS que executam PostgreSQL 10, PostgreSQL 11 ou PostgreSQL 12 com versão secundária do mecanismo anterior a 20201130 suportam a extensão pg_cron original. Contudo, recomendamos atualizar a versão secundária do mecanismo da sua instância RDS para a versão mais recente para usar a versão aprimorada do pg_cron. Para obter mais informações, consulte Update the minor engine version. Se você já utilizava o pg_cron antes da atualização da versão secundária do mecanismo, recrie o pg_cron para aproveitar os novos recursos. As tarefas agendadas configuradas anteriormente com o pg_cron serão perdidas após a recriação da extensão.

• Use uma conta privilegiada para criar ou excluir a extensão pg_cron. Para saber como criar uma conta privilegiada, consulte Create an account.

Uso da extensão

• Criar a extensão

  • Instalar a extensão pelo recurso de gerenciamento de extensões

    1. Faça login no console do ApsaraDB RDS e acesse a página Instances. Na barra de navegação superior, selecione a região onde sua instância RDS está localizada. Em seguida, localize a instância RDS e clique em ID da instância.

    2. No painel de navegação à esquerda, clique em Plug-ins.

    3. Na página exibida, clique em aba Extension Management e, em seguida, na aba Uninstalled Extensions. Pesquise pela extensão pg_cron, selecione o banco de dados onde deseja instalá-la e clique em Install na coluna Actions.

    4. Na caixa de diálogo exibida, selecione uma conta privilegiada e clique em OK para instalar a extensão no banco de dados desejado.

       Durante a instalação da extensão, o status da instância RDS muda para Maintaining Instance. Quando o status da instância RDS retornar para Running, a extensão estará instalada.

  • Executar a instrução SQL necessária para instalar a extensão

    1. Modifique o parâmetro necessário para adicionar pg_cron ao Running Value do parâmetro shared_preload_libraries no console do ApsaraDB RDS. Por exemplo, altere o Running Value desse parâmetro para 'pg_stat_statements,auto_explain,pg_cron'. Para obter mais informações, consulte Set instance parameters.

    2. Conecte-se ao banco de dados desejado usando uma conta privilegiada e execute a seguinte instrução:

       CREATE EXTENSION pg_cron;

       Nota

       Execute a instrução SELECT * FROM pg_extension para visualizar as extensões instaladas.

• Configurar uma tarefa agendada

  SELECT cron.schedule('<Scheduled Task Name>','<Schedule>', '<Action>');

  Nota

  O nome da tarefa agendada é opcional. Após configurar a tarefa, o sistema retorna o ID da tarefa.

  Exemplo:

  -- Delete expired data at 3:30 AM (GMT) every Saturday. 
  SELECT cron.schedule('30 3 * * 6', $$DELETE FROM events WHERE event_time < now() - interval '1 week'$$);
  
  ----------
  
  -- Clear the disk at 10:00 AM (GMT) every day.
  SELECT cron.schedule('0 10 * * *', 'VACUUM');

• Configurar uma tarefa agendada em um banco de dados específico

  SELECT cron.schedule_in_database('<Scheduled Task Name>', '<Schedule>', '<Action>', '<Specified Database>');

  Importante

  Especifique um nome para a tarefa agendada. Caso contrário, a criação da tarefa falhará.

  Se a sua instância RDS for PostgreSQL executar uma versão secundária do mecanismo anterior a 20230530, utilize o comando abaixo para executar uma tarefa agendada. Sem a especificação de um banco de dados, a tarefa será executada no banco de dados definido pelo parâmetro cron.database_name. Por padrão, esse banco de dados é o postgres.

  SELECT cron.schedule('<Schedule>', '<Action>', '<Specified Database>')

  Exemplo:

  SELECT cron.schedule_in_database('weekly-vacuum', '0 4 * * 0', 'VACUUM', 'some_other_database');

• Visualizar as tarefas agendadas configuradas

  SELECT * FROM cron.job;

• Excluir uma tarefa agendada

  SELECT cron.unschedule(<Scheduled Task ID>);

  Se a tarefa agendada possuir um nome definido, exclua-a especificando esse nome.

  SELECT cron.unschedule('<Scheduled Task Name>');

  Exemplo:

  -- Delete a scheduled task by its ID.
  SELECT cron.unschedule(43);
  -- Delete a scheduled task by its name.
  SELECT cron.unschedule('test01');

• Excluir a extensão

  DROP EXTENSION pg_cron;

  Nota

  • Apenas contas privilegiadas têm permissão para executar o comando acima.

  • Na aba Installed Extensions da aba Extension Management, desinstale a extensão.