J.1. pg_timetable#

J.1. pg_timetable

J.1. pg_timetable #

J.1.1. Обзор #

Версия: 7.1.0

Скачать с nexus-public

pg_timetable — это продвинутый планировщик заданий для Tantor BE, предлагающий множество преимуществ по сравнению с традиционными планировщиками, такими как cron и другие. Он полностью управляется через базу данных и предоставляет несколько дополнительных возможностей.

J.1.2. Установка #

Чтобы установить pg_timetable, скачайте установочный скрипт db_extension_installer.sh и сделайте его исполняемым:

wget https://public.tantorlabs.ru/db_extension_installer.sh && \
chmod +x db_extension_installer.sh

Далее вы можете установить pg_timetable:

J.1.2.1. Локально из скачанного пакета #

  1. Скачайте пакет pg_timetable, подходящий для вашей операционной системы, с сайта nexus-public.

  2. Выполните установку pg_timetable с помощью db_extension_installer.sh из скачанного пакета:

    ./db_extension_installer.sh \
      --from-file=<path to pg_timetable package>
    

J.1.2.2. Автоматически из репозитория пакетов #

  1. Установите значение переменной окружения NEXUS_URL:

    export NEXUS_URL="nexus-public.tantorlabs.ru"
    
  2. Выполните установку pg_timetable с помощью db_extension_installer.sh со следующими параметрами:

    ./db_extension_installer.sh \
      --database-type=tantor \
      --edition=all \
      --extension=pg_timetable
    

J.1.3. Основные возможности #

  • Задачи могут быть организованы в цепочки

  • Цепочка может состоять из встроенных команд, SQL и исполняемых файлов

  • Параметры могут быть переданы в цепочки

  • Пропущенные задачи (возможно, из-за простоя) могут быть повторно выполнены автоматически

  • Поддержка настраиваемых повторений

  • Встроенные задачи, такие как отправка электронных писем и т.д.

  • Конфигурация полностью хранится в базе данных

  • Полная поддержка журналирования через базу данных

  • Планирование в стиле cron в часовом поясе сервера Tantor BE

  • Необязательная защита от одновременного выполнения

  • Цепочки и отдельные задачи могут быть включены или отключены без их удаления

  • Определения цепочек в формате YAML для файловой конфигурации

  • Для задачи и цепочки можно задать тайм-аут выполнения

  • Экспорт трассировки и метрик OpenTelemetry (по выбору)

J.1.4. Учебные материалы #

J.1.4.1. Ваша первая запланированная цепочка #

В этом руководстве мы установим pg_timetable, запланируем однократное задание и проследим за его выполнением.

  1. Загрузите исполняемый файл pg_timetable.

  2. Убедитесь, что сервер Tantor BE запущен и в нём есть роль с правом CREATE для целевой базы данных, например:

    CREATE ROLE scheduler PASSWORD 'somestrong';
    GRANT CREATE ON DATABASE my_database TO scheduler;
    
  3. Создайте новое задание, например, для выполнения VACUUM каждую ночь в 00:30 по часовому поясу сервера Postgres.

    SELECT timetable.add_job('frequent-vacuum', '30 0 * * *', 'VACUUM');
    
    add_job
    ---------
          3
    (1 row)
    
  4. Запустите pg_timetable

    pg_timetable postgresql://scheduler:somestrong@localhost/my_database --clientname=vacuumer
    
  5. Готово!

J.1.4.2. Ваша первая YAML-цепочка #

В этом руководстве мы опишем цепочку в файле YAML, загрузим её и посмотрим, как pg_timetable выполнит её при запуске.

  1. Убедитесь, что pg_timetable установлен и у вас есть роль с правом CREATE в целевой базе данных. Если вы ещё не выполнили эти шаги, обратитесь к первому руководству.

  2. Создайте файл с именем hello.yaml:

    chains:
      - name: "hello-yaml"
        schedule: "@reboot"
        live: true
    
        tasks:
          - name: "hello"
            kind: "BUILTIN"
            command: "Log"
            parameters:
              - "Hello from my first YAML chain!"
    
  3. Проверьте файл перед его загрузкой:

    pg_timetable --file hello.yaml --validate postgresql://scheduler:somestrong@localhost/my_database
    

    Вы увидите:

    YAML file validation successful
    
  4. Загрузите цепочку и запустите её с помощью pg_timetable. Цепочки @reboot выполняются сразу после запуска планировщика, поэтому результат будет виден немедленно:

    pg_timetable --file hello.yaml --clientname=yamltester postgresql://scheduler:somestrong@localhost/my_database
    
  5. Во втором терминале проверьте, что создала цепочка:

    SELECT output FROM timetable.execution_log
    WHERE chain_id = (SELECT chain_id FROM timetable.chain WHERE chain_name = 'hello-yaml');
    
                    output
    ------------------------------------------
     Logged: Hello from my first YAML chain!
    (1 row)
    
  6. Готово!

Полный список полей, типов задач и вариантов обработки ошибок приведён в руководстве по настройке цепочек YAML и справочнике «Схема цепочек YAML».

J.1.4.3. Обработка ошибок цепочки #

В этом руководстве мы запланируем цепочку, которая всегда завершается ошибкой, добавим обработчик ошибок, который регистрирует сбой и планирует повторную попытку с увеличивающейся задержкой, а затем проследим, как задержка растёт в течение нескольких попыток.

  1. Убедитесь, что вы выполнили инструкции из раздела Ваша первая запланированная цепочка — мы будем использовать ту же роль scheduler и базу данных my_database.

  2. Создайте обработчик повторных попыток. Он подсчитывает, сколько раз flaky-job завершалось с ошибкой за последнее время, и повторно запланирует его выполнение с задержкой, которая удваивается при каждой попытке:

    CREATE OR REPLACE FUNCTION retry_with_backoff() RETURNS void
    LANGUAGE plpgsql AS $$
    DECLARE
        attempts integer;
        delay interval;
    BEGIN
        SELECT count(*) INTO attempts
        FROM timetable.execution_log
        WHERE chain_id = current_setting('pg_timetable.current_chain_id')::bigint
          AND returncode != 0
          AND finished > now() - interval '10 minutes';
    
        IF attempts >= 3 THEN
            RAISE NOTICE 'Giving up after % attempts', attempts;
            RETURN;
        END IF;
    
        delay := interval '5 seconds' * (2 ^ attempts);
        RAISE NOTICE 'Attempt % failed, retrying in %', attempts, delay;
        PERFORM timetable.notify_chain_start(
            chain_id => current_setting('pg_timetable.current_chain_id')::bigint,
            worker_name => 'errortester',
            start_delay => delay);
    END
    $$;
    
  3. Запланируйте цепочку, которая каждый раз завершается с ошибкой, и назначьте для неё обработчик с job_on_error:

    SELECT timetable.add_job(
        job_name          => 'flaky-job',
        job_schedule      => '@every 1 hour',
        job_command       => 'SELECT 1/0',
        job_ignore_errors => FALSE,
        job_on_error      => 'SELECT retry_with_backoff()');
    
     add_job
    ---------
           4
    (1 row)
    

    @every 1 hour планирует первый запуск немедленно, а последующие — каждый час; собственные повторные попытки обработчика позволяют запускать его повторно раньше этого срока.

  4. Запустите pg_timetable:

    pg_timetable postgresql://scheduler:somestrong@localhost/my_database --clientname=errortester
    

    Вы увидите, как задача завершится с ошибкой, после чего сообщения RAISE NOTICE обработчика появятся в журнале с интервалами примерно 5, 10 и 20 секунд, а при четвёртой попытке появится сообщение «Giving up»:

    2024-01-01 12:00:00.000 [ERROR] [task:1] [error:division by zero] Task execution failed
    2024-01-01 12:00:00.010 [INFO ] [notice:Attempt 0 failed, retrying in 00:00:05] [severity:NOTICE] Notice received
    2024-01-01 12:00:05.020 [INFO ] [notice:Attempt 1 failed, retrying in 00:00:10] [severity:NOTICE] Notice received
    2024-01-01 12:00:15.030 [INFO ] [notice:Attempt 2 failed, retrying in 00:00:20] [severity:NOTICE] Notice received
    2024-01-01 12:00:35.040 [INFO ] [notice:Giving up after 3 attempts] [severity:NOTICE] Notice received
    
  5. Во втором терминале убедитесь, что каждая попытка была зарегистрирована:

    SELECT returncode, output FROM timetable.execution_log
    WHERE chain_id = (SELECT chain_id FROM timetable.chain WHERE chain_name = 'flaky-job')
    ORDER BY last_run;
    
     returncode |          output
    ------------+---------------------------
             -1 | division by zero
             -1 | division by zero
             -1 | division by zero
             -1 | division by zero
    (4 rows)
    
  6. Готово! Вы справились со сбоем цепочки, не контролируя её вручную.

Описание всех полей обработки ошибок на уровне задач и цепочек (ignore_error, on_error, autonomous) см. в разделе Справочник по командам, задачам и цепочкам. Готовый к запуску вариант этого шаблона с настраиваемыми ограничениями см. в файле samples/DelayedRetry.sql в разделе Примеры.

J.1.4.4. Запуск и остановка цепочек вручную #

В этом руководстве мы запустим pg_timetable в режиме отладки — при этом автоматическое планирование полностью отключено, а цепочки запускаются только вручную. Такой порядок работы используется при разработке, отладке и тестовых запусках.

  1. Убедитесь, что вы выполнили инструкции из раздела Ваша первая запланированная цепочка — мы будем использовать ту же роль scheduler и базу данных my_database.

  2. Создайте цепочку, которая приостанавливает выполнение на 30 секунд. Это даст нам время остановить её во время выполнения:

    SELECT timetable.add_job(
        job_name          => 'sleepy-chain',
        job_schedule      => '* * * * *',
        job_command       => 'SELECT pg_sleep(30)',
        job_live          => TRUE,
        job_ignore_errors => TRUE);
    
     add_job
    ---------
           5
    (1 row)
    

    На выходе вы получите идентификатор цепочки — он понадобится ниже. У вас он может быть другим; подставляйте его вместо 5 во всех примерах.

  3. Запустите pg_timetable с параметром --debug:

    pg_timetable --debug --clientname=debugger postgresql://scheduler:somestrong@localhost/my_database
    
    2024-01-01 12:00:00.000 [LOG]: Connection established...
    2024-01-01 12:00:00.010 [LOG]: Configuration schema created...
    2024-01-01 12:00:00.020 [LOG]: Accepting asynchronous chains execution requests...
    

    Обратите внимание, чего нет: сообщений «Checking for task chains» и «Number of chains to be executed». При указании --debug весь цикл планирования пропускается — выражения cron, интервалы и @reboot игнорируются. Планировщик реагирует только на команды, введённые вручную.

  4. Запустите цепочку вручную:

    SELECT timetable.notify_chain_start(
        chain_id    => 5,
        worker_name => 'debugger');
    
     notify_chain_start
    --------------------
    
    (1 row)
    

    Вернитесь к терминалу pg_timetable:

    2024-01-01 12:05:00.000 [LOG]: Adding asynchronous chain to working queue: {5 START …}
    2024-01-01 12:05:00.010 [LOG]: Starting chain ID: 5; configuration ID: 5
    2024-01-01 12:05:30.020 [LOG]: Executed successfully chain ID: 5; configuration ID: 5
    

    Цепочка выполнилась один раз и остановилась — при ручном запуске всегда выполняется только один проход, независимо от значения job_schedule.

  5. Теперь запустите его снова и на этот раз остановите в процессе выполнения. Из SQL-клиента запустите цепочку:

    SELECT timetable.notify_chain_start(5, 'debugger');
    

    Подождите несколько секунд, затем отмените его:

    SELECT timetable.notify_chain_stop(5, 'debugger');
    
     notify_chain_stop
    --------------------
    
    (1 row)
    

    Терминал pg_timetable показывает отмену:

    2024-01-01 12:07:00.000 [LOG]: Adding asynchronous chain to working queue: {5 START …}
    2024-01-01 12:07:00.010 [LOG]: Starting chain ID: 5; configuration ID: 5
    2024-01-01 12:07:08.050 [LOG]: Adding asynchronous chain to working queue: {5 STOP …}
    2024-01-01 12:07:08.051 [ERROR]: Task execution failed: …; Error: read tcp …: i/o timeout
    2024-01-01 12:07:08.052 [LOG]: Executed successfully chain ID: 5; configuration ID: 5
    

    Ошибка задачи ожидаема — вы прервали pg_sleep. Сама цепочка при этом всё равно сообщает об успешном выполнении, поскольку на шаге 2 мы задали job_ignore_errors => TRUE.

  6. Готово! Теперь вы можете запускать и останавливать цепочки по требованию.

Несколько моментов, о которых следует помнить:

  • --debug отключает всё автоматическое планирование. Цепочки с run_at, @every или @reboot не будут запускаться, если вы не запустите их вручную. Это самый простой способ изолировать одну цепочку во время разработки.

  • В промышленной среде того же эффекта для одной цепочки можно добиться без --debug: задайте live = FALSE в её конфигурации, а затем при необходимости запускайте её вручную. Отключённая цепочка по-прежнему реагирует на notify_chain_start.

  • notify_chain_start принимает ID конфигурации выполнения цепочки — однако add_job() создаёт по одной конфигурации для каждой цепочки, поэтому номера совпадают, пока вы не добавите дополнительные конфигурации.

  • worker_name должно совпадать со значением --clientname работающего экземпляра pg_timetable. Если клиент с таким именем не подключён, уведомление без предупреждения отбрасывается.

  • Ручные запуски принимают необязательный параметр start_delay — подробности см. в разделе Справочник по командам, задачам и цепочкам.

Готовые к запуску примеры с более длинными цепочками и обработчиками ошибок приведены в Примерах — попробуйте samples/basic.sql и samples/DelayedRetry.sql.

J.1.4.5. Хранение секрета #

В этом руководстве мы сохраним зашифрованный пароль в хранилище секретов, укажем ссылку на него в строке подключения задачи и посмотрим, как pg_timetable подставит его во время выполнения, ни разу не записав пароль в открытом виде в журнал.

  1. Убедитесь, что вы выполнили инструкции из раздела Ваша первая запланированная цепочка — мы будем использовать ту же роль scheduler и базу данных my_database.

  2. Выберите ключ шифрования и запустите с ним pg_timetable:

    pg_timetable postgresql://scheduler:somestrong@localhost/my_database --clientname=secrettester --secret-key=mysecretkey123
    

    Оставьте его работающим; мы вернёмся к нему на шаге 5.

  3. Во втором терминале установите pgcrypto и сохраните секрет для клиента secrettester. pgcrypto должно быть установлено ролью с правом CREATE в базе данных — это доверенное расширение, поэтому scheduler может установить его непосредственно:

    CREATE EXTENSION IF NOT EXISTS pgcrypto;
    
    INSERT INTO timetable.secret (client_name, secret_name, value_enc)
    VALUES ('secrettester', 'my_pg_password',
            pgp_sym_encrypt('somestrong', 'mysecretkey123'));
    

    Ключ шифрования здесь ('mysecretkey123') должен совпадать со значением --secret-key из шага 2.

  4. Создайте цепочку с задачей, которая подключается к базе данных, используя ${secret:my_pg_password} в строке подключения вместо пароля, указанного явно:

    WITH new_chain AS (
        INSERT INTO timetable.chain (chain_name, run_at, live)
        VALUES ('remote-greeting', '@reboot', TRUE)
        RETURNING chain_id
    ), new_task AS (
        INSERT INTO timetable.task (chain_id, task_order, command, database_connection)
        SELECT chain_id, 10, 'SELECT $1',
               'host=localhost port=5432 dbname=my_database user=scheduler password=${secret:my_pg_password}'
        FROM new_chain
        RETURNING task_id
    )
    INSERT INTO timetable.parameter (task_id, order_id, value)
    SELECT task_id, 1, '["hello from remote"]'::jsonb FROM new_task;
    

    Измените host/port, если ваш сервер Tantor BE работает не по локальному адресу по умолчанию — обычно database_connection указывает на действительно удалённый сервер; здесь же он указывает на тот же сервер, чтобы пример не зависел от внешних ресурсов.

  5. Перезапустите pg_timetable из шага 2 (Ctrl+C, затем снова выполните ту же команду). Цепочки @reboot выполняются один раз, сразу при запуске, поэтому вы сразу увидите, как задача подключится и успешно завершится:

    [chain:2|remote-greeting] Starting chain
    [chain:2|remote-greeting] [task:2] Starting task
    [chain:2|remote-greeting] [task:2] Switching to remote task mode
    [chain:2|remote-greeting] [task:2] Remote connection established...
    [chain:2|remote-greeting] [task:2] Task executed successfully
    [chain:2|remote-greeting] Chain executed successfully
    

    Номера цепочки и задачи зависят от того, что ещё было создано в my_database — значение имеют только имена и порядок сообщений.

  6. Убедитесь, что задача выполнилась, а пароль в открытом виде не попал в журнал:

    SELECT returncode, command, params FROM timetable.execution_log
    WHERE chain_id = (SELECT chain_id FROM timetable.chain WHERE chain_name = 'remote-greeting');
    
     returncode |  command  |         params
    ------------+-----------+-------------------------
              0 | SELECT $1 | ["hello from remote"]
    (1 row)
    

    params содержит аргументы вашей задачи, а не строку подключения, поэтому здесь нечего было маскировать, но та же гарантия действует, если ссылка на секрет находится внутри самого params, например в samples/Mail.sql.

  7. Готово! Вы получили секрет во время выполнения, ни разу не сохранив и не записав его в журнал в виде открытого текста.

Сведения обо всех таблицах, функциях и правах доступа хранилища секретов см. в разделе Справочник по хранилищу секретов. О схеме с доступом только на запись и её границе доверия см. в разделе Модель безопасности хранилища секретов. Административные действия (предоставление прав отдельной роли администратора секретов, использование секретов в цепочках, описанных в YAML) приведены в разделе Использование хранилища секретов. Более подробный пример с отдельной таблицей для удалённых журналов см. в файле samples/RemoteDB.sql в разделе Примеры.

J.1.5. Практические руководства #

J.1.5.1. Планирование типовых заданий #

Различные примеры можно найти в разделе Примеры. Сведения о переходе с другого планировщика см. в разделе Миграция.

На практике обычно достаточно простых заданий. Под этим термином понимается следующее:

  • задание — это цепочка, содержащая только одну задачу (шаг);

  • оно не использует сложную логику, а простую команду;

  • это не требует сложной обработки транзакций, поскольку одна задача неявно выполняется как одна транзакция.

Для такой группы цепочек мы ввели специальную функцию timetable.add_job().

Полное описание параметров timetable.add_job() см. в разделе Схема базы данных.

J.1.5.1.1. Примеры #
  1. Выполнять public.my_func() в 00:05 каждый день в августе по часовому поясу сервера Postgres:

    SELECT timetable.add_job('execute-func', '5 0 * 8 *', 'SELECT public.my_func()');
    
  2. Запускать VACUUM на 23-й минуте каждого второго часа с 0 до 20 каждый день по часовому поясу сервера Postgres:

    SELECT timetable.add_job('run-vacuum', '23 0-20/2 * * *', 'VACUUM');
    
  3. Обновлять материализованное представление каждые 2 часа:

    SELECT timetable.add_job('refresh-matview', '@every 2 hours', 'REFRESH MATERIALIZED VIEW public.mat_view');
    
  4. Очищать таблицу журнала после перезапуска pg_timetable:

    SELECT timetable.add_job('clear-log', '@reboot', 'TRUNCATE timetable.log');
    
  5. Переиндексировать по воскресеньям в полночь по часовому поясу сервера Postgres с помощью утилиты reindexdb:

    • используется база данных по умолчанию под пользователем по умолчанию (без аргументов командной строки)

      SELECT timetable.add_job('reindex', '0 0 * * 7', 'reindexdb', job_kind := 'PROGRAM');
      
    • указать целевую базу данных и таблицы и включить подробный вывод

      SELECT timetable.add_job('reindex', '0 0 * * 7', 'reindexdb', 
          '["--table=foo", "--dbname=postgres", "--verbose"]'::jsonb, 'PROGRAM');
      
    • передача пароля с помощью переменной окружения через оболочку bash

      SELECT timetable.add_job('reindex', '0 0 * * 7', 'bash', 
          '["-c", "PGPASSWORD=5m3R7K4754p4m reindexdb -U postgres -h 192.168.0.221 -v"]'::jsonb, 
          'PROGRAM');
      
  6. Запускать задание на каждой итерации цикла планировщика (по умолчанию каждые 60 секунд) — передайте NULL в качестве расписания:

    SELECT timetable.add_job('frequent-job', NULL, 'SELECT 1');
    

    Задание запускается автоматически при каждом тике и может также запускаться по требованию с помощью timetable.notify_chain_start().

J.1.5.2. Примеры #

J.1.5.2.1. Создайте простую одношаговую цепочку с параметрами. #

Используйте CTE для вставки данных непосредственно в таблицы схемы timetable:

DELETE FROM timetable.chain WHERE chain_name = 'notify_every_minute';

SELECT timetable.add_job(
    job_name            => 'notify_every_minute',
    job_schedule        => '* * * * *',
    job_command         => 'SELECT pg_notify($1, $2)',
    job_parameters      => '[ "TT_CHANNEL", "Ahoj from SQL base task" ]' :: jsonb,
    job_kind            => 'SQL'::timetable.command_kind,
    job_client_name     => NULL,
    job_max_instances   => 1,
    job_live            => TRUE,
    job_self_destruct   => FALSE,
    job_ignore_errors   => TRUE
) as chain_id;
J.1.5.2.2. Отправить письмо из цепочки #

Проверьте, есть ли сообщения электронной почты для отправки, отправьте их и запишите статус выполнения в журнал. Дополнительная настройка не требуется — достаточно указать параметры при создании цепочки:

DO $$
    -- An example for using the SendMail task.
DECLARE
    v_mail_task_id bigint;
    v_log_task_id bigint;
    v_chain_id bigint;
BEGIN
    -- Get the chain id
    INSERT INTO timetable.chain (chain_name, max_instances, live) VALUES ('send_mail', 1, TRUE)
    RETURNING chain_id INTO v_chain_id;

    -- Add SendMail task
    INSERT INTO timetable.task (chain_id, task_order, kind, command) 
    SELECT v_chain_id, 10, 'BUILTIN', 'SendMail'
    RETURNING task_id INTO v_mail_task_id;

    -- Create the parameters for the SensMail task
        -- "username":	      The username used for authenticating on the mail server
        -- "password":        The password used for authenticating on the mail server
        -- "serverhost":      The IP address or hostname of the mail server
        -- "serverport":      The port of the mail server
        -- "senderaddr":      The email that will appear as the sender
        -- "ccaddr":	      String array of the recipients(Cc) email addresses
        -- "bccaddr":	      String array of the recipients(Bcc) email addresses
        -- "toaddr":          String array of the recipients(To) email addresses
        -- "subject":	      Subject of the email
        -- "attachment":      String array of the attachments (local file)
        -- "attachmentdata":  Pairs of name and base64-encoded content
        -- "msgbody":	      The body of the email

    INSERT INTO timetable.parameter (task_id, order_id, value)
        VALUES (v_mail_task_id, 1, '{
                "username":     "user@example.com",
                "password":     "password",
                "serverhost":   "smtp.example.com",
                "serverport":   587,
                "senderaddr":   "user@example.com",
                "ccaddr":       ["recipient_cc@example.com"],
                "bccaddr":      ["recipient_bcc@example.com"],
                "toaddr":       ["recipient@example.com"],
                "subject":      "pg_timetable - No Reply",
                "attachment":   ["D:\\Go stuff\\Books\\Concurrency in Go.pdf","report.yaml"],
                "attachmentdata": [{"name": "File.txt", "base64data": "RmlsZSBDb250ZW50"}],
                "msgbody":      "<b>Hello User,</b> <p>I got some Go books for you enjoy</p> <i>pg_timetable</i>!",
                "contenttype":  "text/html; charset=UTF-8"
                }'::jsonb);
    
    -- Add Log task and make it the last task using `task_order` column (=30)
    INSERT INTO timetable.task (chain_id, task_order, kind, command) 
    SELECT v_chain_id, 30, 'BUILTIN', 'Log'
    RETURNING task_id INTO v_log_task_id;

    -- Add housekeeping task, that will delete sent mail and update parameter for the previous logging task
    -- Since we're using special add_task() function we don't need to specify the `chain_id`.
    -- Function will take the same `chain_id` from the parent task, SendMail in this particular case
    PERFORM timetable.add_task(
        kind => 'SQL', 
        parent_id => v_mail_task_id,
        command => format(
$query$WITH sent_mail(toaddr) AS (DELETE FROM timetable.parameter WHERE task_id = %s RETURNING value->>'username')
INSERT INTO timetable.parameter (task_id, order_id, value) 
SELECT %s, 1, to_jsonb('Sent emails to: ' || string_agg(sent_mail.toaddr, ';'))
FROM sent_mail
ON CONFLICT (task_id, order_id) DO UPDATE SET value = EXCLUDED.value$query$, 
                v_mail_task_id, v_log_task_id
            ),
        order_delta => 10
    );

-- In the end we should have something like this. Note, that even Log task was created earlier it will be executed later
-- due to `task_order` column.

-- timetable=> SELECT task_id, chain_id, kind, left(command, 50) FROM timetable.task ORDER BY task_order;  
--  task_id | chain_id | task_order |  kind   |                             left
-- ---------+----------+------------+---------+---------------------------------------------------------------
--       45 |       24 |         10 | BUILTIN | SendMail
--       47 |       24 |         20 | SQL     | WITH sent_mail(toaddr) AS (DELETE FROM timetable.p
--       46 |       24 |         30 | BUILTIN | Log
-- (3 rows)

END;
$$
LANGUAGE PLPGSQL;
J.1.5.2.3. Загрузите, преобразуйте и импортируйте данные в одной цепочке #

Используйте оператор DO, чтобы добавить цепочку из трёх шагов непосредственно в таблицы схемы timetable:

-- Prepare the destination table 'location'
CREATE TABLE IF NOT EXISTS public.city(
    city text,
    lat numeric,
    lng numeric,
    country text,
    iso2 text,
    admin_name text,
    capital text,
    population bigint,
    population_proper bigint);
   
GRANT ALL ON public.city TO scheduler;

-- An enhanced example consisting of three tasks:
-- 1. Download text file from internet using BUILT-IN command
-- 2. Remove accents (diacritic signs) from letters using PROGRAM command (can be done with `unaccent` PostgreSQL extension) 
-- 3. Import text file as CSV file using BUILT-IN command (can be down with `psql -c /copy`)
DO $$
DECLARE
    v_task_id bigint;
    v_chain_id bigint;
BEGIN
    -- Create the chain with default values executed every minute (NULL == '* * * * *' :: timetable.cron)
    INSERT INTO timetable.chain (chain_name, live)
    VALUES ('download_locations_and_aggregate', TRUE)
    RETURNING chain_id INTO v_chain_id;

    -- Step 1. Download file from the server
    -- Create the chain
    INSERT INTO timetable.task (chain_id, task_order, kind, command, ignore_error)
    VALUES (v_chain_id, 1, 'BUILTIN', 'Download', TRUE)
    RETURNING task_id INTO v_task_id;

    -- Create the parameters for the step 1:
    INSERT INTO timetable.parameter (task_id, order_id, value)
        VALUES (v_task_id, 1, 
           '{
                "workersnum": 1,
                "fileurls": ["https://simplemaps.com/static/data/country-cities/mt/mt.csv"], 
                "destpath": "."
            }'::jsonb);
    
    RAISE NOTICE 'Step 1 completed. Chain added with ID: %; DownloadFile task added with ID: %', v_chain_id, v_task_id;

    -- Step 2. Transform Unicode characters into ASCII
    -- Create the program task to call 'uconv' and name it 'unaccent'
    INSERT INTO timetable.task (chain_id, task_order, kind, command, ignore_error, task_name)
    VALUES (v_chain_id, 2, 'PROGRAM', 'uconv', TRUE, 'remove_accents')
    RETURNING task_id INTO v_task_id;

    -- Create the parameters for the 'unaccent' task. Input and output files in this case
    -- Under Windows we should call PowerShell instead of "uconv" with command:
    -- Set-content "orte_ansi.txt" ((Get-content "orte.txt").Normalize("FormD") -replace '\p{M}', '')
    INSERT INTO timetable.parameter (task_id, order_id, value)
        VALUES (v_task_id, 1, '["-x", "Latin-ASCII", "-o", "mt_ansi.csv", "mt.csv"]'::jsonb);

    RAISE NOTICE 'Step 2 completed. Unacent task added with ID: %', v_task_id;

    -- Step 3. Import ASCII file to PostgreSQL table using "CopyFromFile" built-in command
    INSERT INTO timetable.task (chain_id, task_order, kind, command)
        VALUES (v_chain_id, 3, 'BUILTIN', 'CopyFromFile')
    RETURNING task_id INTO v_task_id;

    -- Add the parameters for the download task. Execute client side COPY to 'location' from 'orte_ansi.txt'
    INSERT INTO timetable.parameter (task_id, order_id, value)
        VALUES (v_task_id, 1, '{"sql": "COPY city FROM STDIN (FORMAT csv, HEADER true)", "filename": "mt_ansi.csv" }'::jsonb);

    RAISE NOTICE 'Step 3 completed. Import task added with ID: %', v_task_id;

    INSERT INTO timetable.task (chain_id, task_order, kind, command, ignore_error, task_name)
    VALUES (v_chain_id, 4, 'PROGRAM', 'bash', TRUE, 'remove_csv_files')
    RETURNING task_id INTO v_task_id;

    INSERT INTO timetable.parameter (task_id, order_id, value)
    VALUES (v_task_id, 1, '["-c", "rm *.csv"]'::jsonb);
   
   RAISE NOTICE 'Step 4 completed. Cleanup task added with ID: %', v_task_id;
END;
$$ LANGUAGE PLPGSQL;
J.1.5.2.4. Выполнить задачу в автономной транзакции #

Запустить задачу вне транзакции цепочки для операций, которые не могут выполняться в рамках транзакции, например CREATE DATABASE, REINDEX, VACUUM, CREATE TABLESPACE:

-- An advanced example showing how to use atutonomous tasks.
-- This one-task chain will execute test_proc() procedure.
-- Since procedure will make two commits (after f1() and f2())
-- we cannot use it as a regular task, because all regular tasks 
-- must be executed in the context of a single chain transaction.
-- Same rule applies for some other SQL commands, 
-- e.g. CREATE DATABASE, REINDEX, VACUUM, CREATE TABLESPACE, etc.
CREATE OR REPLACE FUNCTION f (msg TEXT) RETURNS void AS $$
BEGIN 
    RAISE notice '%', msg; 
END;
$$ LANGUAGE PLPGSQL;

CREATE OR REPLACE PROCEDURE test_proc () AS $$
BEGIN
    PERFORM f('hey 1');
    COMMIT;
    PERFORM f('hey 2');
    COMMIT;
END;
$$
LANGUAGE PLPGSQL;

DELETE FROM timetable.chain WHERE chain_name = 'call_proc_every_10s';

WITH
    cte_chain (v_chain_id) AS (
        INSERT INTO timetable.chain (chain_name, run_at, max_instances, live, self_destruct) 
        VALUES (
            'call_proc_every_10s', -- chain_name, 
            '@every 10 seconds',        -- run_at,
            1,     -- max_instances, 
            TRUE,  -- live, 
            FALSE -- self_destruct
        ) RETURNING chain_id
    ),
    cte_task(v_task_id) AS (
        INSERT INTO timetable.task (chain_id, task_order, kind, command, ignore_error, autonomous)
        SELECT v_chain_id, 10, 'SQL', 'CALL test_proc()', TRUE, TRUE
        FROM cte_chain
        RETURNING task_id
    )
SELECT v_chain_id, v_task_id FROM cte_task, cte_chain;
J.1.5.2.5. Остановите планировщик и завершите сеанс. #

Используйте встроенную задачу завершения работы, чтобы управлять окнами обслуживания, перезапускать планировщик для обновлений или завершать сеанс перед удалением базы данных:

-- This one-task chain (aka job) will terminate pg_timetable session.
-- This is useful for maintaining purposes or before database being destroyed.
-- One should take care of restarting pg_timetable if needed.

SELECT timetable.add_job (
    job_name     => 'shutdown_on_schedule',
    job_schedule => '* * 1 * *',
    job_command  => 'Shutdown',
    job_kind     => 'BUILTIN'
);
J.1.5.2.6. Получить из следующей задачи код результата и вывод предыдущей задачи #

Проверяет код возврата и вывод предыдущей задачи — это возможно, только если для неё задано ignore_error = true, иначе при сбое планировщик останавливает цепочку. В этом примере также подсчитывается количество выполненных задач с ошибкой, успешно выполненных задач и общее количество задач, а также итоговая доля успешно выполненных задач:

WITH 
    cte_chain (v_chain_id) AS ( -- let's create a new chain and add tasks to it later
        INSERT INTO timetable.chain (chain_name, run_at, max_instances, live) 
        VALUES ('many_tasks', '* * * * *', 1, true)
        RETURNING chain_id
    ),
    cte_tasks(v_task_id) AS ( -- now we'll add 500 tasks to the chain, some of them will fail
        INSERT INTO timetable.task (chain_id, task_order, kind, command, ignore_error)
        SELECT v_chain_id, g.s, 'SQL', 'SELECT 1.0 / round(random())::int4;', true
        FROM cte_chain, generate_series(1, 500) AS g(s)
        RETURNING task_id
    ),
    report_task(v_task_id) AS ( -- and the last reporting task will calculate the statistic
        INSERT INTO timetable.task (chain_id, task_order, kind, command)
        SELECT v_chain_id, 501, 'SQL', $CMD$DO
$$
DECLARE
    s TEXT;
BEGIN
    WITH report AS (
        SELECT 
        count(*) FILTER (WHERE returncode = 0) AS success,
        count(*) FILTER (WHERE returncode != 0) AS fail,
        count(*) AS total
        FROM timetable.execution_log 
        WHERE chain_id = current_setting('pg_timetable.current_chain_id')::bigint
          AND txid = txid_current()
    )
    SELECT 'Tasks executed:' || total || 
         '; succeeded: ' || success || 
         '; failed: ' || fail || 
         '; ratio: ' || 100.0*success/GREATEST(total,1)
    INTO s
    FROM report;
    RAISE NOTICE '%', s;
END;
$$
$CMD$
        FROM cte_chain
        RETURNING task_id
    )
SELECT v_chain_id FROM cte_chain

О хранилище секретов см. Использование хранилища секретов.

J.1.5.3. Переход с других планировщиков #

J.1.5.3.1. Перенос заданий из pg_cron в pg_timetable #

Если вы хотите быстро перенести задания, запланированные в pg_cron, в pg_timetable, можно использовать следующий фрагмент SQL:

SELECT timetable.add_job(
    job_name            => COALESCE(jobname, 'job: ' || command),
    job_schedule        => schedule,
    job_command         => command,
    job_kind            => 'SQL',
    job_live            => active
) FROM cron.job;

Однако функция timetable.add_job() имеет некоторые ограничения. Прежде всего, она помечает созданную задачу как автономную, указывая планировщику выполнять её вне транзакции цепочки. Это не ошибка, но большое количество автономных цепочек может потребовать дополнительных подключений.

Во-вторых, параметры подключения к базе данных для исходных заданий pg_cron теряются, из-за чего все задания становятся локальными. Чтобы экспортировать всю доступную информацию как можно точнее, выполните следующий SQL-фрагмент от имени роли, под которой задания были запланированы в pg_cron:

SET ROLE 'scheduler'; -- set the role used by pg_cron

WITH cron_chain AS (
    SELECT
        nextval('timetable.chain_chain_id_seq'::regclass) AS cron_id,
        jobname,
        schedule,
        active,
        command,
        CASE WHEN 
            database != current_database()
            OR nodename != 'localhost'
            OR username != CURRENT_USER
            OR nodeport != inet_server_port() 
        THEN
            format('host=%s port=%s dbname=%s user=%s', nodename, nodeport, database, username)
        END AS connstr
    FROM
        cron.job
),
cte_chain AS (
	INSERT INTO timetable.chain (chain_id, chain_name, run_at, live)
	    SELECT 
	    	cron_id, COALESCE(jobname, 'cronjob' || cron_id), schedule, active
	    FROM
	    	cron_chain
),
cte_tasks AS (
	INSERT INTO timetable.task (chain_id, task_order, kind, command, database_connection)
	    SELECT
	    	cron_id, 1, 'SQL', command, connstr
	    FROM
	    	cron_chain
	    RETURNING
	        chain_id, task_id
)
SELECT * FROM cte_tasks;
J.1.5.3.2. Перенос заданий из pgAgent в pg_timetable #

Для переноса заданий из pgAgent используйте этот скрипт. В pgAgent нет понятия задачи PROGRAM, поэтому для имитации шагов BATCH pg_timetable выполняет их в командной оболочке. Чтобы изменить командную оболочку, отредактируйте выражение CTE cte_shell.

CREATE OR REPLACE FUNCTION bool_array_to_cron(bool[], start_with int4 DEFAULT 0) RETURNS TEXT AS
$$
WITH u AS (
	SELECT unnest($1) e, generate_series($2, array_length($1, 1)-1+$2) AS i 
)
SELECT COALESCE(string_agg(i::text, ','), '*') FROM u WHERE e
$$
LANGUAGE sql;


WITH
cte_shell(shell, cmd_param) AS (
	VALUES ('sh', '-c') -- set the shell you want to use for batch steps, e.g. "pwsh -c", "cmd /C"
),
pga_schedule AS (
	SELECT
		s.jscjobid,
		s.jscname,
		format('%s %s %s %s %s', 
			bool_array_to_cron(s.jscminutes), 
			bool_array_to_cron(s.jschours), 
			bool_array_to_cron(s.jscmonthdays), 
			bool_array_to_cron(s.jscmonths, 1), 
			bool_array_to_cron(s.jscweekdays, 1)) AS schedule
	FROM 
		pgagent.pga_schedule s  
	WHERE s.jscenabled 
			AND now() < COALESCE(s.jscend, 'infinity'::timestamptz)
			AND now() > s.jscstart
),
pga_chain AS (
    SELECT
        nextval('timetable.chain_chain_id_seq'::regclass) AS chain_id,
        jobid,
        format('%s @ %s', jobname, jscname) AS jobname,
        jobhostagent,
        jobenabled,
        schedule
    FROM
        pgagent.pga_job JOIN pga_schedule ON jobid = jscjobid
),
cte_chain AS (
	INSERT INTO timetable.chain (chain_id, chain_name, client_name, run_at, live)
	    SELECT 
	    	chain_id, jobname, jobhostagent, schedule, jobenabled
	    FROM
	    	pga_chain
),
pga_step AS (
	SELECT 
		c.chain_id,
		nextval('timetable.task_task_id_seq'::regclass) AS task_id,
		rank() OVER (ORDER BY jstname) AS jstorder,
		jstid,
		jstname,
		jstenabled,
		CASE jstkind WHEN 'b' THEN 'PROGRAM' ELSE 'SQL' END AS jstkind,
		jstcode,
		COALESCE(
			NULLIF(jstconnstr, ''), 
			CASE 
				WHEN jstdbname = current_database() THEN NULL
				WHEN jstdbname > '' THEN 'dbname=' || jstdbname 
			END
		) AS jstconnstr,
		jstonerror != 'f' AS jstignoreerror
	FROM
		pga_chain c JOIN pgagent.pga_jobstep js ON c.jobid = js.jstjobid
),
cte_tasks AS (
	INSERT INTO timetable.task(task_id, chain_id, task_name, task_order, kind, command, database_connection)
	    SELECT
	    	task_id, chain_id, jstname, jstorder, jstkind::timetable.command_kind, 
	    	CASE jstkind WHEN 'SQL' THEN jstcode ELSE sh.shell END,
	    	jstconnstr
	    FROM
	    	pga_step, cte_shell sh
),
cte_parameters AS (
	INSERT INTO timetable.parameter (task_id, order_id, value)
		SELECT 
			task_id, 1, jsonb_build_array(sh.cmd_param, s.jstcode)
	    FROM
	    	pga_step s, cte_shell sh
	    WHERE 
	    	s.jstkind = 'PROGRAM'
)
SELECT * FROM pga_chain;

J.1.5.4. Руководство по настройке цепочки YAML #

В этом руководстве показано, как определять цепочки pg_timetable в файлах YAML вместо настройки с помощью SQL.

J.1.5.4.1. Основное использование #
# Load a single YAML file
pg_timetable --file chains.yaml postgresql://user:pass@host/db

# Load several startup files in order
pg_timetable --file bootstrap.sql --file chains/base.yaml --file chains/prod.yaml ******host/db

# Validate YAML without importing
pg_timetable --file chains.yaml --validate

# Replace existing chains with same names
pg_timetable --file chains.yaml --replace postgresql://user:pass@host/db

Каждое значение --file обрабатывается в указанном порядке, поэтому вы можете смешивать SQL-скрипты и определения цепочек в формате YAML в одной стартовой команде.

J.1.5.4.2. Формат YAML #

Полный список полей и значения по умолчанию приведены в справочном разделе «Схема цепочки YAML». Примеры ниже показывают типичные задачи по составлению определений.

J.1.5.4.2.1. Параметры задачи #

Каждая задача может иметь несколько записей параметров, при этом каждая запись вызывает отдельное выполнение:

# SQL task parameters (arrays of values)
- name: "sql-task"
  kind: "SQL"
  command: "SELECT $1, $2, $3, $4"
  parameters:
    - ["one", 2, 3.14, false]    # First execution
    - ["two", 4, 6.28, true]     # Second execution

# PROGRAM task parameters (arrays of command-line arguments)
- name: "program-task"
  kind: "PROGRAM"
  command: "iconv"
  parameters:
    - ["-x", "Latin-ASCII", "-o", "file1.txt", "input1.txt"]
    - ["-x", "UTF-8", "-o", "file2.txt", "input2.txt"]

Команды BUILTIN (Sleep, Log, SendMail, Download, CopyFromFile, CopyToFile, CopyFromProgram, CopyToProgram) принимают в YAML то же значение параметра, что и в SQL, — отличается только окружающий синтаксис. Точную структуру JSON для каждой команды и подробный пример см. в разделе Формат значения параметра.

J.1.5.4.2.2. Примеры #

Простейший пример с одной задачей см. в разделе Схема цепочки YAML.

J.1.5.4.2.3. Многошаговая цепочка #
chains:
  - name: "data-pipeline"
    schedule: "0 1 * * *"  # 1 AM daily
    live: true
    max_instances: 1
    timeout: 7200000  # 2 hours
    
    tasks:
      - name: "extract"
        command: |
          CREATE TEMP TABLE temp_data AS
          SELECT * FROM source_table 
          WHERE date >= CURRENT_DATE - INTERVAL '1 day'
          
      - name: "validate"
        command: |
          DO $$
          BEGIN
            IF (SELECT COUNT(*) FROM temp_data) = 0 THEN
              RAISE EXCEPTION 'No data to process';
            END IF;
          END $$
          
      - name: "transform"
        command: "CALL transform_data_procedure()"
        autonomous: true
        
      - name: "load"
        command: "INSERT INTO target_table SELECT * FROM temp_data"
J.1.5.4.2.4. Несколько цепочек в одном файле #
chains:
  # Monitoring chain
  - name: "health-check"
    schedule: "*/15 * * * *"  # Every 15 minutes
    live: true
    
    tasks:
      - command: "SELECT check_database_health()"
      
  # Cleanup chain  
  - name: "hourly-cleanup"
    schedule: "0 * * * *"  # Every hour
    live: true
    
    tasks:
      - command: "DELETE FROM logs WHERE created_at < now() - interval '7 days'"
J.1.5.4.2.5. Отключение задачи без её удаления #
chains:
  - name: "maintenance-window"
    schedule: "0 1 * * *"
    live: true

    tasks:
      - name: "pre-check"
        command: "SELECT run_precheck()"
      - name: "paused-step"
        command: "SELECT run_optional_step()"
        live: false
      - name: "post-check"
        command: "SELECT run_postcheck()"

Задачи с live: false остаются частью определения цепочки, но пропускаются до повторного включения.

J.1.5.4.3. Расширенные возможности #
J.1.5.4.3.1. Обработка ошибок #

Управление поведением при ошибках с помощью ignore_error и on_error:

chains:
  - name: "resilient-chain"
    on_error: |
      SELECT pg_notify('monitoring', 
            format('{"ConfigID": %s, "Message": "Something bad happened"}', 
                current_setting('pg_timetable.current_chain_id')::bigint))
    
    tasks:
      - name: "risky-task"
        command: "SELECT might_fail()"
        ignore_error: true  # Continue chain execution even if this task fails
        
      - name: "cleanup-task"
        command: "SELECT cleanup()"  # Always runs, even if previous task failed
J.1.5.4.3.2. Управление транзакциями #

Используйте autonomous: true для задач, которые необходимо выполнять вне основной транзакции:

tasks:
  - name: "vacuum-task"
    command: "VACUUM FULL heavy_table"
    autonomous: true  # Required for VACUUM FULL
    
  - name: "create-database"
    command: "CREATE DATABASE new_db"
    autonomous: true  # CREATE DATABASE requires autonomous transaction
J.1.5.4.3.3. Удалённые базы данных #

Выполнение задач в разных базах данных:

tasks:
  - name: "cross-database-task"
    command: "SELECT sync_data()"
    connect_string: "postgresql://user:pass@other-host/other-db"
J.1.5.4.4. Миграция с SQL #
J.1.5.4.4.1. Преобразование существующих цепочек #

Чтобы преобразовать SQL-цепочки в YAML:

  1. Запросите сведения о цепочке и задачах:

    SELECT *
    FROM timetable.chain c 
    WHERE c.chain_name = 'my-chain';
    
    SELECT t.*
    FROM timetable.task t JOIN 
         timetable.chain c ON t.chain_id = c.chain_id AND c.chain_name = 'my-chain'
    ORDER BY t.task_order;
    
  2. Преобразовать в формат YAML:

    • chain_name → name

    • run_at → schedule

    • live → live

    • max_instances → max_instances

    • Поля задачи отображаются напрямую

  3. Проверьте преобразование:

    pg_timetable --file converted.yaml --validate
    
J.1.5.4.4.2. Пример миграции #

Исходный SQL:

SELECT timetable.add_job(
    job_name => 'daily-report',
    job_schedule => '0 9 * * *',
    job_command => 'CALL generate_report()',
    job_live => TRUE
);

Преобразованный YAML:

chains:
  - name: "daily-report"
    schedule: "0 9 * * *"
    live: true
    
    tasks:
      - command: "CALL generate_report()"
J.1.5.4.5. Устранение неполадок #
J.1.5.4.5.1. Распространённые проблемы #

Недопустимый синтаксис YAML:

Error: failed to parse YAML: yaml: line 5: found character that cannot start any token

→ Проверьте отступы и кавычки

Недопустимый формат cron:

Error: invalid cron format: 0 9 * * (expected 5 fields)

→ Убедитесь, что в cron ровно 5 полей

Цепочка уже существует:

Error: chain 'my-chain' already exists (use --replace flag to overwrite)

→ Используйте параметр --replace или выберите другое имя

Отсутствуют обязательные поля:

Error: chain 1: chain name is required

→ Проверьте, что все обязательные поля присутствуют

J.1.5.4.6. Секреты #

Цепочки, созданные с помощью YAML, в версии v1 не поддерживают разрешение ${secret:name} — два поддерживаемых обходных пути описаны в разделе Использование секретов в цепочках, созданных с помощью YAML.

J.1.5.5. Использование хранилища секретов #

J.1.5.5.1. Сохранение секрета и обращение к нему #

samples/Mail.sql и samples/RemoteDB.sql демонстрируют работу хранилища секретов: ссылка ${secret:name} в параметре (jsonb) или в строке conninfo для database_connection во время выполнения заменяется расшифрованным значением соответствующей записи timetable.secret для работающего клиента.

  1. Настройте --secret-key (или PGTT_SECRET_KEY) для процесса планировщика.

  2. Установите pgcrypto (в любой схеме) и добавьте строку в timetable.secret с помощью pgp_sym_encrypt, используя тот же ключ:

    CREATE EXTENSION IF NOT EXISTS pgcrypto; -- by the DBA, not by pg_timetable
    INSERT INTO timetable.secret (client_name, secret_name, value_enc)
    VALUES ('worker-1', 'smtp_main',
            pgp_sym_encrypt('your-password', 'PGTT_SECRET_KEY_VALUE'));
    

    Для успешного выполнения этой операции роль кластера должна быть владельцем timetable.secret.

  3. Замените литерал в параметре на "${secret:your_name}" (для полей jsonb) или password=${secret:your_name} (для строк подключения).

  4. Необязательно: предоставьте отдельной административной роли доступ только на запись. Схема не предоставляет прав по умолчанию для timetable.secret, поэтому оператор, желающий передать управление секретами без раскрытия открытого текста, должен вручную выполнить команду GRANT INSERT, UPDATE, DELETE ON timetable.secret TO admin_role:

    GRANT INSERT, UPDATE, DELETE ON timetable.secret TO admin_role;
    

    resolve_secret принадлежит роли планировщика и по умолчанию не предоставляется никакой другой роли.

J.1.5.5.2. Использование секретов в цепочках, описанных в YAML #

Цепочки, описанные в YAML, не поддерживают ссылки ${secret:name} в v1. Синтаксис ссылок реализован как подстановка строк в среде выполнения Go после того, как parameter.value материализуется в базе данных; загрузчик YAML не разрешает ссылки на секреты. Цепочка YAML, которой требуется секрет, должна либо:

  • ссылаться на строку timetable.task, в которой parameter.value уже содержит ${secret:name} (т. е. цепочка изначально была создана через SQL по шаблону samples/Mail.sql или samples/RemoteDB.sql; шаги описаны выше в разделе Хранение секрета и обращение к нему), или

  • использовать строковый литерал подключения в database_connection и принять связанный с этим компромисс (пароль в таком случае будет виден читателям базы данных, а также в резервных копиях и дампах).

J.1.5.5.2.1. Что нужно для включения хранилища секретов #

pgcrypto не устанавливается pg_timetable. Чтобы использовать ссылки ${secret:name}, администратор базы данных должен установить pgcrypto один раз в каждой базе данных (в любой схеме; это доверенное расширение, которое может установить любая роль с правом CREATE в базе данных). Планировщик настраивается с помощью --secret-key (или PGTT_SECRET_KEY), а записи с секретами добавляются с помощью pgp_sym_encrypt из той же схемы.

Синтаксис хранилища используется только при явном выборе: цепочки, в которых parameter.value содержит пароль в явном виде, продолжают работать без изменений.

Синтаксис схемы и ссылок описан в разделе «Справочник хранилища секретов».

О границах доверия, обосновании проектных решений и рекомендациях по обращению с учётными данными см. Модель безопасности хранилища секретов. О схеме и синтаксисе см. Справочник по хранилищу секретов.

J.1.5.6. Включить OpenTelemetry #

Примечание

Поддержка OTel включается исключительно по явному указанию. Если параметр --otel-endpoint не задан, pg_timetable работает точно так же, как и раньше, без дополнительных накладных расходов.

J.1.5.6.1. Сигналы #

pg_timetable поддерживает два сигнала OTel, каждый из которых можно включать независимо:

СигналПараметрЧто он даёт
Трассировки--otel-tracesРаспределённая трассировка для каждого выполнения цепочки с дочерними спанами для каждой задачи
Метрики--otel-metricsСчётчики и гистограмма, отражающие пропускную способность цепочек и задач
J.1.5.6.2. Быстрый старт #
J.1.5.6.2.2. Только трассировки — Jaeger #

Только трассировки

Jaeger реализует только службу OTLP для трассировок. Включение --otel-metrics при использовании конечной точки Jaeger приведёт к ошибкам экспорта. Используйте эту конфигурацию, если вам нужны только трассировки.

# 1. Start Jaeger
docker run --rm -d -p 4317:4317 -p 16686:16686 jaegertracing/all-in-one:latest

# 2. Run pg_timetable with tracing only
pg_timetable \
  --otel-endpoint grpc://localhost:4317 \
  --otel-traces \
  --otel-insecure \
  postgresql://scheduler:pass@localhost/mydb

Откройте http://localhost:16686 и выберите сервис pg_timetable, чтобы посмотреть трассировки.

J.1.5.6.2.3. Только метрики — OTel Collector → Prometheus #
pg_timetable \
  --otel-endpoint grpc://otel-collector:4317 \
  --otel-metrics \
  --otel-metric-period 15 \
  postgresql://scheduler:pass@localhost/mydb
J.1.5.6.3. Сокращение объёма трассировки #

По умолчанию трассируются 100 % выполнений цепочки. В развёртываниях с высокой частотой выполнения можно уменьшить объём трассировки с помощью семплера с заданной долей выборки:

# Trace 10 % of chain executions
pg_timetable --otel-traces --otel-sample-ratio 0.1 \
  --otel-endpoint grpc://localhost:4317 \
  postgresql://scheduler:pass@localhost/mydb

Описание всех параметров, атрибутов спанов, метрик и ключей конфигурации см. в справочнике по OpenTelemetry.

J.1.5.7. Ограничение числа сеансов базы данных при выполнении множества заданий #

Если вы планируете много цепочек и хотите ограничить число подключений к базе данных, которые открывает pg_timetable, используйте приведённые ниже параметры, а не подбирайте значение наугад.

J.1.5.7.1. Вычислите предельное число подключений #

Один экземпляр pg_timetable открывает не более:

max_conn = --cron-workers + --interval-workers + 3

+3 учитывает приёмник обычной цепочки, приёмник интервальной цепочки и регистратор базы данных — каждый из них держит собственное подключение наряду с пулом рабочих процессов. При значениях по умолчанию (--cron-workers=16 --interval-workers=16) это 35 подключений на экземпляр; если с одним сервером работают несколько экземпляров, этот предел умножается на их число.

Чтобы ограничить число сеансов, уменьшите значения --cron-workers и/или --interval-workers (см. справочник по параметрам командной строки):

pg_timetable postgresql://scheduler:somestrong@localhost/my_database --cron-workers=4 --interval-workers=2
J.1.5.7.2. Сократите число одновременных выполнений цепочек, не меняя число рабочих процессов #

job_max_instances (или max_instances в YAML) ограничивает число копий одной конкретной цепочки, выполняющихся одновременно. Этот параметр не влияет на цепочки, которые выполняются один раз и затем самоуничтожаются, поскольку в каждый момент времени может выполняться только один их экземпляр. Чтобы сократить общее число одновременно выполняющихся цепочек, не уменьшая число рабочих процессов:

  • планировать запуск цепочек реже, например каждые 10 минут вместо каждой минуты;

  • используйте расписание @after вместо @every для цепочек, следующий запуск которых должен происходить после завершения предыдущего, а не по фиксированному графику независимо от наложения запусков.

Полный список полей см. в таблице timetable.chain.

J.1.5.7.3. Если вы видите сообщение «Failed to send chain to the execution channel» #

Это означает, что, когда планировщик попытался передать на выполнение цепочку, для которой наступило время запуска, все рабочие процессы были заняты, а очередь в памяти между планировщиком и рабочими процессами была заполнена. Поскольку очередь имеет большой буфер, это указывает на устойчивое накопление заданий, а не на кратковременный всплеск нагрузки. Способы решения те же, что и выше: сократить число цепочек, запускать их реже или увеличить число рабочих процессов, если база данных может выдержать дополнительные подключения.

J.1.5.7.4. Наблюдайте, прежде чем настраивать #

Проверьте timetable.log на наличие этой ошибки и общее состояние выполнения, а также сопоставьте данные pg_stat_activity с рассчитанным значением max_conn, чтобы убедиться, что на практике установленный предел соблюдается:

SELECT count(*) FROM pg_stat_activity WHERE application_name = 'pg_timetable';

J.1.6. Справочники #

J.1.6.1. REST API #

pg_timetable предоставляет богатый REST API, который внешние инструменты могут использовать для запуска, остановки, повторной инициализации, перезапуска и перезагрузки, для проверки работоспособности по HTTP, а также для мониторинга.

Ниже приведён список конечных точек REST API pg_timetable.

J.1.6.1.1. Конечные точки проверки работоспособности #
J.1.6.1.1.1. GET /liveness #

Всегда возвращает код состояния HTTP 200, указывающий, что pg_timetable работает.

J.1.6.1.1.2. GET /readiness #

Возвращает код состояния HTTP 200, когда pg_timetable работает, а планировщик находится в основном цикле обработки цепочек. Если планировщик подключается к базе данных, создаёт схему базы данных или обновляет её, возвращается код состояния HTTP 503.

J.1.6.1.2. Конечные точки управления цепочками #
J.1.6.1.2.1. GET /startchain?id=<chain-id> #

Возвращает код состояния HTTP 200, если цепочку с заданным идентификатором можно добавить в очередь рабочих процессов. Однако это не означает, что выполнение цепочки начнётся немедленно. Перед запуском цепочки рабочий процесс выполняет проверки нагрузки и другие проверки. В случае ошибки возвращается код состояния HTTP 400 с сообщением об ошибке.

J.1.6.1.2.2. GET /stopchain?id=<chain-id> #

Возвращает код состояния HTTP 200, если цепочка с указанным идентификатором в данный момент работает и может быть остановлена. Если цепочка выполняется, сигнал отмены отправляется немедленно. В случае ошибки возвращается код состояния HTTP 400 и сообщение об ошибке.

J.1.6.2. Справочник командной строки #

Полный список параметров командной строки pg_timetable и соответствующих им переменных окружения.

# ./pg_timetable

Application Options:
  -c, --clientname=                                Unique name for application instance [$PGTT_CLIENTNAME]
      --config=                                    YAML configuration file
      --no-program-tasks                           Disable executing of PROGRAM tasks [$PGTT_NOPROGRAMTASKS]
  -v, --version                                    Output detailed version information [$PGTT_VERSION]
      --connstr                                    PostgreSQL connection string [$PGTT_CONNSTR]

Logging:
      --log-level=[debug|info|error]               Verbosity level for stdout and log file (default: info)
      --log-database-level=[debug|info|error|none] Verbosity level for database storing (default: info)
      --log-file=                                  File name to store logs
      --log-file-format=[json|text]                Format of file logs (default: json)
      --log-file-rotate                            Rotate log files
      --log-file-size=                             Maximum size in MB of the log file before it gets rotated (default: 100)
      --log-file-age=                              Number of days to retain old log files, 0 means forever (default: 0)
      --log-file-number=                           Maximum number of old log files to retain, 0 to retain all (default: 0)

Start:
  -f, --file=                                      SQL script or YAML chain definition file to execute during
                                                   startup; may be specified multiple times
      --replace                                    Replace existing chains when loading YAML files
      --validate                                   Only validate YAML file without importing chains
      --init                                       Initialize database schema to the latest version and exit. Can be used
                                                   with --upgrade
      --upgrade                                    Upgrade database to the latest version
      --debug                                      Run in debug mode. Only asynchronous chains will be executed

Resource:
      --cron-workers=                              Number of parallel workers for scheduled chains (default: 16)
      --interval-workers=                          Number of parallel workers for interval chains (default: 16)
      --chain-timeout=                             Abort any chain that takes more than the specified number of
                                                   milliseconds
      --task-timeout=                              Abort any task within a chain that takes more than the specified number
                                                   of milliseconds

REST:
      --rest-port=                                 REST API port (default: 0) [$PGTT_RESTPORT]

OTel:
      --otel-endpoint=                             OTLP exporter endpoint URL (grpc://, http://, https://)
      --otel-traces                                Enable OpenTelemetry distributed tracing
      --otel-metrics                               Enable OpenTelemetry metrics export
      --otel-service-name=                         OTel service.name resource attribute (default: pg_timetable)
      --otel-insecure                              Disable TLS for OTLP connection (dev/test only)
      --otel-sample-ratio=                         Trace sampling ratio 0.0-1.0 (default: 1.0)
      --otel-metric-period=                        Metrics export interval in seconds (default: 30)
      --otel-shutdown-timeout=                     OTel provider flush timeout in seconds on shutdown (default: 5)

J.1.6.3. Справочник команд, задач и цепочек #

J.1.6.3.1. Команда #

В настоящее время существует три различных типа команд:

J.1.6.3.1.1. SQL #

Фрагмент SQL. Начало очистки, обновление материализованного представления или обработка данных.

J.1.6.3.1.2. PROGRAM #

Внешняя команда. Любой исполняемый файл, который можно вызвать, включая командные оболочки, например bash, pwsh и т. д. Внешняя команда будет вызываться с помощью функции exec.CommandContext языка Go.

J.1.6.3.1.3. BUILTIN #

Внутренняя команда. Готовая функциональность, встроенная в pg_timetable. К таким командам относятся:

  • NoOp

  • Sleep

  • Log

  • SendMail

  • Download

  • CopyFromFile

  • CopyToFile

  • CopyFromProgram

  • CopyToProgram

  • Shutdown

J.1.6.3.2. Задача #

Следующий строительный блок — задача, которая представляет собой отдельный шаг в списке команд цепочки. Пример задач, объединённых в цепочку:

  1. Загрузить файлы с сервера

  2. Импортировать файлы

  3. Выполнить агрегацию

  4. Построить отчёт

  5. Удалить файлы с диска

Примечание

Все задачи цепочки в pg_timetable выполняются в рамках одной транзакции. Однако обратите внимание, что откатить задачи PROGRAM и BUILTIN невозможно.

J.1.6.3.2.1. Таблица timetable.task #
ПолеТипОписание
chain_idbigintСсылка на цепочку; если NULL, задача считается отключённой
task_orderDOUBLE PRECISIONУказывает порядковый номер задачи в цепочке
kindtimetable.command_kindТип команды. Может быть SQL (по умолчанию), PROGRAM или BUILTIN
commandtextСодержит команду SQL, путь к приложению или имя команды BUILTIN, которая будет выполнена
run_astextРоль, от имени которой должна выполняться задача
database_connectiontextСтрока подключения к внешней базе данных, которую следует использовать
ignore_errorbooleanУказывает, следует ли продолжать выполнение следующей задачи при возникновении ошибки (по умолчанию: false)
autonomousbooleanУказывает, должна ли задача выполняться вне транзакции цепочки. Полезно для VACUUM, CREATE DATABASE, CALL и т. д.
timeoutintegerПрерывать любую задачу в цепочке, выполнение которой занимает больше указанного числа миллисекунд
livebooleanПризнак готовности задачи к выполнению; при значении false выполнение пропускается (по умолчанию: true)

Если в строке задачи задано live = FALSE, её выполнение пропускается, но сама строка не удаляется:

UPDATE timetable.task
SET live = FALSE
WHERE task_id = 42;

Того же эффекта для цепочек, управляемых через YAML, можно добиться, указав live: false для отдельной задачи.

Предупреждение

Если для задачи параметр ignore_error установлен в значение true (по умолчанию — false), рабочий процесс сообщит об успешном выполнении, даже если задача в цепочке завершится с ошибкой.

Как упоминалось выше, команды представляют собой простые заготовки (например, отправить письмо, vacuum и т. д.). В большинстве случаев, чтобы они заработали, при выполнении им необходимо передать входные параметры.

J.1.6.3.2.2. Таблица timetable.parameter #
ПолеТипОписание
task_idbigintИдентификатор задачи
order_idintegerПорядковый номер параметра. Несколько параметров обрабатываются один за другим в указанном порядке
valuejsonbЗначение JSON, содержащее параметры
J.1.6.3.2.3. Формат значения параметра #

В зависимости от типа команды аргумент может быть представлен разными значениями JSON.

J.1.6.3.2.4. SQL #

Схема: массив

Пример:

'[ "one", 2, 3.14, false ]'::jsonb
J.1.6.3.2.5. PROGRAM #

Схема: массив строк

Пример:

'["-x", "Latin-ASCII", "-o", "orte_ansi.txt", "orte.txt"]'::jsonb
J.1.6.3.2.6. BUILTIN: Sleep #

Схема: целое число

Пример:

'5' :: jsonb
J.1.6.3.2.7. BUILTIN: Log #

Схема: любой

Примеры:

'"WARNING"'::jsonb
'{"Status": "WARNING"}'::jsonb
J.1.6.3.2.8. BUILTIN: SendMail #

Схема: объект

Пример:

'{
    "username":     "user@example.com",
    "password":     "password",
    "serverhost":   "smtp.example.com",
    "serverport":   587,
    "senderaddr":   "user@example.com",
    "ccaddr":       ["recipient_cc@example.com"],
    "bccaddr":      ["recipient_bcc@example.com"],
    "toaddr":       ["recipient@example.com"],
    "subject":      "pg_timetable - No Reply",
    "attachment":   ["/temp/attachments/Report.pdf","config.yaml"],
    "attachmentdata": [{"name": "File.txt", "base64data": "RmlsZSBDb250ZW50"}],
    "msgbody":      "<h2>Hello User,</h2> <p>check some attachments!</p>",
    "contenttype":   "text/html; charset=UTF-8"
}'::jsonb
J.1.6.3.2.9. BUILTIN: Download #

Схема: объект

Пример:

'{
    "workersnum": 2, 
    "fileurls": ["http://example.com/foo.gz", "https://example.com/bar.csv"], 
    "destpath": "."
}'::jsonb
J.1.6.3.2.10. BUILTIN: CopyFromFile #

Схема: объект

Пример:

'{
    "sql": "COPY location FROM STDIN", 
    "filename": "download/orte_ansi.txt" 
}'::jsonb
J.1.6.3.2.11. BUILTIN: CopyToFile #

Схема: объект

Пример:

'{
    "sql": "COPY location TO STDOUT", 
    "filename": "download/location.txt" 
}'::jsonb
J.1.6.3.2.12. BUILTIN: CopyToProgram #

Схема: объект

Пример:

'{
    "sql": "COPY location TO STDOUT",
    "cmd": "sh",
    "args": ["gzip", "-c", ">", "/tmp/output.gz"]
}'::jsonb
J.1.6.3.2.13. BUILTIN: CopyFromProgram #

Схема: объект

Пример:

'{
    "sql": "COPY location FROM STDIN",
    "cmd": "gunzip",
    "args": ["-c", "/tmp/data.gz"]
}'::jsonb
J.1.6.3.2.14. BUILTIN: Shutdown #

значение проигнорировано

J.1.6.3.2.15. BUILTIN: NoOp #

значение проигнорировано

J.1.6.3.3. Цепочка #

После упорядочивания задач их необходимо запланировать как цепочку. Для этого pg_timetable использует расширенный формат строки cron и предоставляет дополнительные параметры настройки.

J.1.6.3.3.1. Таблица timetable.chain #
ПолеТипОписание
chain_nametextУникальное имя цепочки
run_attimetable.cronСтандартное значение в стиле cron для часового пояса сервера Postgres или выражение @after, @every, @reboot. Если указано NULL, цепочка запускается каждую минуту
max_instancesintegerМаксимальное количество экземпляров этой цепочки, которые могут выполняться одновременно
timeoutintegerПрерывать любую цепочку, выполнение которой занимает больше указанного числа миллисекунд
livebooleanОпределяет, может ли цепочка быть выполнена, когда наступит время её выполнения по расписанию
self_destructbooleanУдалить цепочку после успешного выполнения. В случае неудачи цепочка будет выполнена по расписанию ещё один раз
exclusive_executionbooleanУказывает, следует ли выполнять цепочку монопольно, приостановив выполнение всех остальных цепочек
client_nametextУказывает, какой клиент должен выполнять цепочку. Установите значение NULL, чтобы разрешить выполнение любому клиенту
on_error—Содержит SQL-код, выполняемый при возникновении ошибки. Если для задачи, вызвавшей ошибку, установлен параметр ignore_error, никаких действий не выполняется

Примечание

Все цепочки в pg_timetable планируются с учётом часового пояса сервера Tantor BE. При добавлении новых цепочек можно изменить часовой пояс для текущего сеанса, например:

SET TIME ZONE 'UTC';

-- Run VACUUM at 00:05 every day in August UTC
SELECT timetable.add_job('execute-func', '5 0 * 8 *', 'VACUUM');

J.1.6.4. Формат определения цепочки YAML для pg_timetable #

Этот документ определяет формат YAML для описания цепочек запланированных задач в pg_timetable.

J.1.6.4.1. YAML-схема #
# Top-level structure
chains:
  - name: "chain-name"                        # Required: chain_name (TEXT, unique)
    schedule: "* * * * *"                     # Required: run_at (cron format)
    live: true                                # Optional: live (BOOLEAN), default: false
    max_instances: 1                          # Optional: max_instances (INTEGER)
    timeout: 30000                            # Optional: timeout in milliseconds (INTEGER)
    self_destruct: false                      # Optional: self_destruct (BOOLEAN), default: false
    exclusive: false                          # Optional: exclusive_execution (BOOLEAN), default: false  
    client_name: "worker-1"                   # Optional: client_name (TEXT)
    on_error: "SELECT log_error()"            # Optional: on_error SQL (TEXT)
    
    tasks:                                                # Required: array of tasks
      - name: "task-1"                                    # Optional: task_name (TEXT)
        kind: "SQL"                                       # Optional: kind (SQL|PROGRAM|BUILTIN), default: SQL
        command: "SELECT $1, $2"                          # Required: command (TEXT)
        parameters:                                       # Optional: parameters (array of execution parameters)
          - ["value1", 42]                                # First execution with these parameters
          - ["value2", 99]                                # Second execution with different parameters
        run_as: "postgres"                                # Optional: run_as (TEXT) - role for SET ROLE
        connect_string: "postgresql://user@host/otherdb"  # Optional: database_connection (TEXT)
        ignore_error: false                               # Optional: ignore_error (BOOLEAN), default: false
        autonomous: false                                 # Optional: autonomous (BOOLEAN), default: false
        timeout: 5000                                     # Optional: timeout in milliseconds (INTEGER)
        live: true                                        # Optional: live (BOOLEAN), default: true; set false to skip the task
        
      - name: "task-2"
        kind: "PROGRAM"
        command: "bash"
        parameters: ["-c", "echo hello"]
        ignore_error: true
J.1.6.4.2. Соответствие полей #
J.1.6.4.2.1. Уровень цепочки #
Поле YAMLСтолбец БДТипЗначение по умолчаниюОписание
namechain_nameTEXTобязательноУникальный идентификатор цепочки
schedulerun_atcronобязательноРасписание в формате cron. Если не указано или пусто, по умолчанию используется * * * * * (каждую минуту)
liveliveBOOLEANfalseАктивна ли цепочка
max_instancesmax_instancesINTEGERnullМаксимальное число одновременно выполняемых экземпляров
timeouttimeoutINTEGER0Тайм-аут цепочки (мс)
self_destructself_destructBOOLEANfalseУдалить после успешного выполнения
exclusiveexclusive_executionBOOLEANfalseПриостанавливать другие цепочки
client_nameclient_nameTEXTnullОграничить конкретным клиентом
on_erroron_errorTEXTnullSQL для обработки ошибок
J.1.6.4.2.2. Уровень задачи #
Поле YAMLСтолбец БДТипЗначение по умолчаниюОписание
nametask_nameTEXTnullОписание задачи
kindkindENUM'SQL'Тип команды (SQL/PROGRAM/BUILTIN)
commandcommandTEXTобязательноКоманда для выполнения
parametersчерез timetable.parameterМассив элементов любого типаnullМассив значений параметров, хранящихся в отдельных строках JSONB с order_id
run_asrun_asTEXTnullРоль для SET ROLE
connect_stringdatabase_connectionTEXTnullСтрока подключения
ignore_errorignore_errorBOOLEANfalseПродолжать при ошибке
autonomousautonomousBOOLEANfalseВыполнять вне транзакции
timeouttimeoutINTEGER0Время ожидания задачи (мс)
liveliveBOOLEANtrueВыполняется ли задача; отключённые задачи пропускаются
J.1.6.4.3. Порядок выполнения задач #

Задачи упорядочены последовательно внутри цепочки на основе их позиции в массиве. Система автоматически присвоит соответствующие значения task_order с интервалами (например, 10, 20, 30), чтобы обеспечить возможность будущих вставок.

J.1.6.4.4. Примеры #
J.1.6.4.4.1. Простое задание SQL #
chains:
  - name: "daily-report"
    schedule: "0 9 * * *"  # 9 AM daily
    live: true
    tasks:
      - name: "generate-report"
        command: "CALL generate_daily_report()"
J.1.6.4.4.2. Многозадачная цепочка #
chains:
  - name: "etl-pipeline"
    schedule: "0 2 * * *"  # 2 AM daily
    live: true
    max_instances: 1
    timeout: 3600000  # 1 hour
    
    tasks:
      - name: "extract-data"
        command: "SELECT extract_sales_data($1)"
        parameters: ["2023-01-01"]
        
      - name: "transform-data"  
        command: "CALL transform_sales_data()"
        autonomous: true
        
      - name: "load-data"
        command: "CALL load_to_warehouse()"
        ignore_error: false
J.1.6.4.4.3. Программная задача #
chains:
  - name: "backup-job"
    schedule: "0 3 * * 0"  # Sunday 3 AM
    live: true
    
    tasks:
      - name: "pg-dump"
        kind: "PROGRAM"
        command: "pg_dump"
        parameters: 
          - ["-h", "localhost", "-U", "postgres", "-d", "mydb", "-f", "/backups/mydb.sql"]
J.1.6.4.5. Правила проверки #
  1. Обязательные поля: name, schedule, tasks и command для каждой задачи

  2. Уникальные имена: Имена цепочек должны быть уникальными в пределах базы данных

  3. Допустимый Cron: Расписание должно быть в допустимом формате cron (5 полей)

  4. Допустимый тип: Тип задачи должен быть одним из следующих: SQL, PROGRAM, BUILTIN

  5. Типы параметров: Параметры могут быть любым типом, совместимым с JSON (строки, числа, логические значения, массивы, объекты) и хранятся как отдельные значения JSONB

  6. Значения тайм-аутов: Должны быть неотрицательными целыми числами (миллисекунды)

J.1.6.5. Схема базы данных #

pg_timetable — приложение, управляемое базой данных. При первом запуске необходимая схема создаётся, если она отсутствует.

J.1.6.5.1. Основные таблицы и объекты #
CREATE TABLE timetable.chain (
    chain_id            BIGSERIAL   PRIMARY KEY,
    chain_name          TEXT        NOT NULL UNIQUE,
    run_at              timetable.cron,
    max_instances       INTEGER,
    timeout             INTEGER     DEFAULT 0,
    live                BOOLEAN     DEFAULT FALSE,
    self_destruct       BOOLEAN     DEFAULT FALSE,
    exclusive_execution BOOLEAN     DEFAULT FALSE,
    client_name         TEXT,
    on_error            TEXT
);

COMMENT ON TABLE timetable.chain IS
    'Stores information about chains schedule';
COMMENT ON COLUMN timetable.chain.run_at IS
    'Extended CRON-style time notation the chain has to be run at';
COMMENT ON COLUMN timetable.chain.max_instances IS
    'Number of instances (clients) this chain can run in parallel';
COMMENT ON COLUMN timetable.chain.timeout IS
    'Abort any chain that takes more than the specified number of milliseconds';
COMMENT ON COLUMN timetable.chain.live IS
    'Indication that the chain is ready to run, set to FALSE to pause execution';
COMMENT ON COLUMN timetable.chain.self_destruct IS
    'Indication that this chain will delete itself after successful run';
COMMENT ON COLUMN timetable.chain.exclusive_execution IS
    'All parallel chains should be paused while executing this chain';
COMMENT ON COLUMN timetable.chain.client_name IS
    'Only client with this name is allowed to run this chain, set to NULL to allow any client';    

CREATE TYPE timetable.command_kind AS ENUM ('SQL', 'PROGRAM', 'BUILTIN');

CREATE TABLE timetable.task (
    task_id             BIGSERIAL               PRIMARY KEY,
    chain_id            BIGINT                  REFERENCES timetable.chain(chain_id) ON UPDATE CASCADE ON DELETE CASCADE,
    task_order          DOUBLE PRECISION        NOT NULL,
    task_name           TEXT,
    kind                timetable.command_kind  NOT NULL DEFAULT 'SQL',
    command             TEXT                    NOT NULL,
    run_as              TEXT,
    database_connection TEXT,
    ignore_error        BOOLEAN                 NOT NULL DEFAULT FALSE,
    autonomous          BOOLEAN                 NOT NULL DEFAULT FALSE,
    timeout             INTEGER                 DEFAULT 0,
    live                BOOLEAN                 NOT NULL DEFAULT TRUE
);          

COMMENT ON TABLE timetable.task IS
    'Holds information about chain elements aka tasks';
COMMENT ON COLUMN timetable.task.chain_id IS
    'Link to the chain, if NULL task considered to be disabled';
COMMENT ON COLUMN timetable.task.task_order IS
    'Indicates the order of task within a chain';    
COMMENT ON COLUMN timetable.task.run_as IS
    'Role name to run task as. Uses SET ROLE for SQL commands';
COMMENT ON COLUMN timetable.task.ignore_error IS
    'Indicates whether a next task in a chain can be executed regardless of the success of the current one';
COMMENT ON COLUMN timetable.task.kind IS
    'Indicates whether "command" is SQL, built-in function or an external program';
COMMENT ON COLUMN timetable.task.command IS
    'Contains either an SQL command, or command string to be executed';
COMMENT ON COLUMN timetable.task.timeout IS
    'Abort any task within a chain that takes more than the specified number of milliseconds';
COMMENT ON COLUMN timetable.task.autonomous IS
    'Specify if the task should be executed out of the chain transaction. Useful for VACUUM, CREATE DATABASE, CALL etc.';
COMMENT ON COLUMN timetable.task.live IS
    'Indication that the task is ready to run, set to FALSE to skip execution';

-- parameter passing for a chain task
CREATE TABLE timetable.parameter(
    task_id     BIGINT  REFERENCES timetable.task(task_id)
                        ON UPDATE CASCADE ON DELETE CASCADE,
    order_id    INTEGER CHECK (order_id > 0),
    value       JSONB,
    PRIMARY KEY (task_id, order_id)
);

COMMENT ON TABLE timetable.parameter IS
    'Stores parameters passed as arguments to a chain task';

CREATE UNLOGGED TABLE timetable.active_session(
    client_pid  BIGINT  NOT NULL,
    server_pid  BIGINT  NOT NULL,
    client_name TEXT    NOT NULL,
    started_at  TIMESTAMPTZ DEFAULT now()
);

COMMENT ON TABLE timetable.active_session IS
    'Stores information about active sessions';

CREATE TYPE timetable.log_type AS ENUM ('DEBUG', 'NOTICE', 'INFO', 'ERROR', 'PANIC', 'USER');

CREATE OR REPLACE FUNCTION timetable.get_client_name(integer) RETURNS TEXT AS
$$
    SELECT client_name FROM timetable.active_session WHERE server_pid = $1 LIMIT 1
$$
LANGUAGE sql;

CREATE TABLE timetable.log
(
    ts              TIMESTAMPTZ         DEFAULT now(),
    pid             INTEGER             NOT NULL,
    log_level       timetable.log_type  NOT NULL,
    client_name     TEXT                DEFAULT timetable.get_client_name(pg_backend_pid()),
    message         TEXT,
    message_data    jsonb
);

COMMENT ON TABLE timetable.log IS
    'Stores log entries of active sessions';

CREATE TABLE timetable.execution_log (
    chain_id        BIGINT,
    task_id         BIGINT,
    txid            BIGINT NOT NULL,
    last_run        TIMESTAMPTZ DEFAULT now(),
    finished        TIMESTAMPTZ,
    pid             BIGINT,
    returncode      INTEGER,
    ignore_error    BOOLEAN,
    kind            timetable.command_kind,
    command         TEXT,
    output          TEXT,
    client_name     TEXT        NOT NULL,
    params          TEXT
);

COMMENT ON TABLE timetable.execution_log IS
    'Stores log entries of executed tasks and chains';
COMMENT ON COLUMN timetable.execution_log.chain_id IS
    'Link to the chain executed';
COMMENT ON COLUMN timetable.execution_log.task_id IS
    'Link to the task executed';
COMMENT ON COLUMN timetable.execution_log.txid IS
    'Transaction ID of the executed task';
COMMENT ON COLUMN timetable.execution_log.last_run IS
    'Timestamp of the last execution of the task';
COMMENT ON COLUMN timetable.execution_log.finished IS
    'Timestamp of the task execution finish';
COMMENT ON COLUMN timetable.execution_log.pid IS
    'Process ID of the worker executing the task';
COMMENT ON COLUMN timetable.execution_log.returncode IS
    'Return code of the executed task';
COMMENT ON COLUMN timetable.execution_log.ignore_error IS
    'Indicates whether a next task in a chain can be executed regardless of the success of the current one';
COMMENT ON COLUMN timetable.execution_log.kind IS
    'Indicates whether "command" is SQL, built-in function or an external program';
COMMENT ON COLUMN timetable.execution_log.command IS
    'Contains either an SQL command, or command string to be executed';
COMMENT ON COLUMN timetable.execution_log.output IS
    'Contains output of the executed task';
COMMENT ON COLUMN timetable.execution_log.client_name IS
    'Name of the client executing the task';
COMMENT ON COLUMN timetable.execution_log.params IS
    'Contains parameters passed as arguments to a chain task';

CREATE INDEX execution_log_chain_id_finished_idx
    ON timetable.execution_log (chain_id, finished);

CREATE INDEX execution_log_finished_brin_idx
    ON timetable.execution_log USING brin (finished);

CREATE UNLOGGED TABLE timetable.active_chain(
    chain_id    BIGINT  NOT NULL,
    client_name TEXT    NOT NULL,
    started_at  TIMESTAMPTZ DEFAULT now()
);

COMMENT ON TABLE timetable.active_chain IS
    'Stores information about active chains within session';

CREATE OR REPLACE FUNCTION timetable.try_lock_client_name(worker_pid BIGINT, worker_name TEXT)
RETURNS bool AS
$CODE$
BEGIN
    IF pg_is_in_recovery() THEN
        RAISE NOTICE 'Cannot obtain lock on a replica. Please, use the primary node';
        RETURN FALSE;
    END IF;
    -- remove disconnected sessions
    DELETE
        FROM timetable.active_session
        WHERE server_pid NOT IN (
            SELECT pid
            FROM pg_catalog.pg_stat_activity
            WHERE application_name = 'pg_timetable'
        );
    DELETE 
        FROM timetable.active_chain 
        WHERE client_name NOT IN (
            SELECT client_name FROM timetable.active_session
        );
    -- check if there any active sessions with the client name but different client pid
    PERFORM 1
        FROM timetable.active_session s
        WHERE
            s.client_pid <> worker_pid
            AND s.client_name = worker_name
        LIMIT 1;
    IF FOUND THEN
        RAISE NOTICE 'Another client is already connected to server with name: %', worker_name;
        RETURN FALSE;
    END IF;
    -- insert current session information
    INSERT INTO timetable.active_session(client_pid, client_name, server_pid) VALUES (worker_pid, worker_name, pg_backend_pid());
    RETURN TRUE;
END;
$CODE$
STRICT
LANGUAGE plpgsql;

J.1.6.6. Хранилище секретов #

Хранилище секретов добавляется миграцией 00820 и полностью размещается в схеме timetable. Эта схема применяется без изменений в базе данных, где не установлено расширение pgcrypto; оно требуется только сеансам, которые непосредственно получают значение секрета.

Обоснование архитектуры, допускающей только запись, и модель угроз, от которых она призвана защищать, приведены в разделе Модель безопасности хранилища секретов.

J.1.6.6.1. pgcrypto — необязательная зависимость #

pg_timetable никогда не устанавливает pgcrypto, не требует его наличия и не проверяет его наличие. Миграция и схема timetable успешно применяются в базе данных без pgcrypto, даже если используемая роль не может установить это расширение. За установку расширения отвечает администратор базы данных; обращение к нему происходит только внутри timetable.resolve_secret() при вызове функции.

J.1.6.6.2. Объекты схемы #

Определения таблиц и функций приведены выше с помощью фрагмента pymdownx ddl.sql. Вкратце:

  • timetable.secret(client_name TEXT NOT NULL, secret_name TEXT NOT NULL, value_enc BYTEA NOT NULL, created_at / updated_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_by TEXT NOT NULL DEFAULT session_user). PRIMARY KEY (client_name, secret_name) — без суррогатного secret_id. CHECK (secret_name ~ '^[A-Za-z0-9_.-]+$'). REVOKE ALL FROM PUBLIC; по умолчанию права другим ролям не предоставляются.

  • timetable.secret_touch() — триггер BEFORE UPDATE, который обновляет updated_at / updated_by, чтобы выполненные вручную команды UPDATE не оставляли устаревшие данные аудита. Создаётся с помощью EXECUTE PROCEDURE (совместимо со всеми версиями Tantor BE в списке поддерживаемых версий) и обычной команды CREATE TRIGGER.

  • timetable.resolve_secret(p_name TEXT, p_client TEXT, p_key TEXT) RETURNS TEXT — LANGUAGE plpgsql, SECURITY DEFINER, STRICT, STABLE, SET search_path = pg_catalog, timetable. Поиск pgcrypto и вызов decrypt выполняются в динамическом SQL. Функция определяет схему расширения во время вызова по pg_catalog.pg_extension / pg_catalog.pg_namespace, поэтому она работает с public, отдельной схемой и схемой, заданной через ALTER EXTENSION pgcrypto SET SCHEMA .... Возвращает NULL, если пара (client_name, secret_name) не существует (при этом pgcrypto не требуется). Выдаёт ошибку feature_not_supported (SQLSTATE 0A000), если pgcrypto отсутствует: завершается с ошибкой только эта задача, а планировщик продолжает работу. При неверном ключе выдаёт ошибку Wrong key or corrupt data. Требуется LANGUAGE plpgsql (а не LANGUAGE sql), чтобы функция успешно создавалась в базе данных без pgcrypto.

  • timetable.secret_count() RETURNS BIGINT — LANGUAGE sql, SECURITY DEFINER, STABLE. Возвращает count(*) по таблице timetable.secret. Используется при проверке во время запуска планировщика, если ключ шифрования не настроен; не требует pgcrypto. Возвращает 0, если секретов нет, в том числе в базе данных, где не установлен pgcrypto.

J.1.6.6.3. Синтаксис ссылок #

${secret:name} в timetable.parameter.value (строковых конечных значениях jsonb) или timetable.task.database_connection во время выполнения заменяется расшифрованным значением из соответствующей строки timetable.secret для работающего клиента. Подставленные значения маскируются в execution_log.params, timetable.log и поле args трассировщика pgx; см. правила маскирования в спецификации.

Хранилище используется только при явном указании соответствующего синтаксиса. Цепочки, созданные до появления этой возможности, у которых parameter.value содержит пароль в явном виде, продолжат работать без изменений.

J.1.6.6.4. Модель прав доступа #
  • PUBLIC не имеет никаких прав на таблицу или функции.

  • Роль-владелец (роль, используемая планировщиком для подключения) может читать value_enc напрямую — границу конфиденциальности определяет ключ, а не модель прав доступа.

  • Схема не создаёт новую роль. Операторы, которым нужна отдельная роль для администрирования секретов, должны самостоятельно выполнить GRANT INSERT, UPDATE, DELETE ON timetable.secret TO admin_role; это действие оператора, а не роль, управляемая схемой.

  • Проверка при запуске планировщика (CheckSecretConfig) вызывает timetable.secret_count() ровно один раз, если ключ шифрования не задан, и не вызывает её вовсе, если ключ задан. Ошибка самой проверки записывается в журнал, но не приводит к остановке.

J.1.6.7. Справочник по OpenTelemetry #

Параметры командной строки OTel описаны в справочнике по параметрам командной строки.

J.1.6.7.1. Выбор протокола #

Транспортный протокол OTLP определяется автоматически на основе схемы URL конечной точки:

СхемаТранспорт
grpc://OTLP/gRPC
http://OTLP/HTTP (protobuf)
https://OTLP/HTTP с TLS

TLS включён по умолчанию для всех транспортов. В средах разработки используйте --otel-insecure, чтобы отключить проверку TLS.

J.1.6.7.2. Схема трассировки #

При каждом выполнении цепочки создаётся корневой спан chain.execute, содержащий дочерние спаны task.execute для каждой задачи в цепочке.

J.1.6.7.2.1. Span: chain.execute #
АтрибутЗначение
chain.idИдентификатор цепочки (целое число)
chain.nameИмя цепочки
client.nameимя клиента pg_timetable (--clientname)
J.1.6.7.2.2. Span: task.execute #
АтрибутЗначение
task.nameКоманда задачи
task.kindSQL, PROGRAM или BUILTIN
task.return_code0 при успешном выполнении, -1 при ошибке

Задачи, завершившиеся с ошибкой, создают событие ошибки OTel с сообщением об ошибке, что позволяет настраивать оповещения на основе трассировок и анализировать первопричины.

J.1.6.7.3. Метрические инструменты #

Все инструменты регистрируются с именем измерителя pg_timetable и имеют атрибут client.name для развёртываний с несколькими экземплярами.

ИнструментТипЕдиница измеренияОписание
pgtimetable.chain.startedСчётчик{execution}Запущенные выполнения цепочки
pgtimetable.chain.completedСчётчик{execution}Успешно завершённые выполнения цепочек
pgtimetable.chain.failedСчётчик{execution}Завершившиеся с ошибкой выполнения цепочек
pgtimetable.chain.durationГистограммаsПродолжительность выполнения цепочки по реальному времени
pgtimetable.task.executedСчётчик{execution}Выполненные задачи (с меткой task.kind)

В гистограмме используются следующие явно заданные границы интервалов (в секундах): 0.001, 0.01, 0.1, 0.5, 1, 5, 10, 30, 60, 120, 300

J.1.6.7.4. Аутентификация и безопасность #

Сервисы наблюдаемости SaaS (Honeycomb, Grafana Cloud, Datadog и т. д.) обычно требуют ключ API. Передайте его в пользовательском HTTP-заголовке через файл конфигурации YAML:

otel:
  endpoint: https://api.honeycomb.io
  traces: true
  headers:
    x-honeycomb-team: YOUR_API_KEY

Предупреждение

otel.headers можно задать только в файле конфигурации YAML — как параметр командной строки он недоступен, чтобы ключи API не попадали в историю командной оболочки или списки процессов. Значения заголовков никогда не записываются в журнал.

J.1.6.7.5. Доля выборки #
ЗначениеЭффект
1.0 (по умолчанию)Трассируется каждое выполнение цепочки
0.5Отслеживается ~50 % выполнений
0.0Трассировка не создаётся
J.1.6.7.6. Устойчивость #
  • Недоступный серверный процесс: pg_timetable запускается как обычно и записывает в журнал сообщение WARN. Сбои экспорта OTel никогда не прерывают планирование цепочек.

  • Корректное завершение работы: при получении SIGTERM pg_timetable отправляет накопленные фрагменты трассировки и метрики перед завершением. Тайм-аут отправки задаётся параметром --otel-shutdown-timeout (по умолчанию: 5 с).

J.1.6.7.7. Конфигурация YAML #
# - OpenTelemetry Settings -
otel:
  # OTLP exporter endpoint URL (grpc://, http://, https://)
  endpoint: ""

  # Enable distributed tracing (default: false)
  traces: false

  # Enable metrics export (default: false)
  metrics: false

  # OTel service.name resource attribute (default: pg_timetable)
  service-name: pg_timetable

  # Custom headers for OTLP export — use for API key auth (map of key: value)
  headers: {}

  # Disable TLS for OTLP connection — dev only (default: false)
  insecure: false

  # Trace sampling ratio 0.0–1.0 (default: 1.0 = 100%)
  sample-ratio: 1.0

  # Metrics export interval in seconds (default: 30)
  metric-period: 30

  # OTel flush timeout in seconds on shutdown (default: 5)
  shutdown-timeout: 5
J.1.6.7.8. Атрибуты ресурсов OTel #

Каждый спан и каждая точка данных метрики содержат следующие атрибуты ресурса, идентифицирующие экземпляр pg_timetable:

АтрибутЗначение
service.name--otel-service-name (по умолчанию: pg_timetable)
service.versionВерсия исполняемого файла pg_timetable
client.name--clientname значение

J.1.7. Концепции #

J.1.7.1. Модель планирования #

Планирование в pg_timetable охватывает три уровня абстракции, чтобы упростить повторное использование с другими параметрами или дополнительными расписаниями.

Команда: Базовый уровень, команда, определяет, что нужно сделать.

Задача: Второй уровень, задача, представляет собой элемент цепочки (шаг), на котором выполняется одна из команд. С помощью задач задаются порядок выполнения команд, передаваемые аргументы (если они есть) и способ обработки ошибок.

Цепочка: Третий уровень представляет связанные задачи, образующие цепочку задач. Цепочка определяет, следует ли, когда и как часто выполнять задание. Цепочка с расписанием NULL (без значения run_at) запускается на каждом такте цикла планировщика — по умолчанию каждые 60 секунд, то есть фактически каждую минуту.

Примечание

Если run_at (расписание) цепочки имеет значение NULL, она будет выполняться при каждом срабатывании планировщика (по умолчанию — каждую минуту). Это эквивалентно расписанию cron * * * * *.

Точные поля, типы и форматы параметров для каждого уровня описаны в разделе «Справочник команд, задач и цепочек».

J.1.7.2. Философия проектирования #

pg_timetable был создан, чтобы решить ряд постоянно возникающих эксплуатационных проблем с существующими планировщиками для Tantor BE. Это не просто ещё один cron внутри базы данных — это механизм оркестрации с определённым подходом, основанным на нескольких ключевых принципах работы автоматизации баз данных.

J.1.7.2.1. Цепочки, а не cron #

Традиционные планировщики — pg_cron, pgAgent и даже системный cron — работают по принципу «запустил и забыл»: в заданное время выполняют заданную команду, и на этом всё. Такой подход подходит для запуска VACUUM в полночь, но перестаёт работать, когда требуется последовательное выполнение: запустить извлечение данных в процессе ETL, дождаться завершения, выполнить преобразование, дождаться завершения, загрузить данные, дождаться завершения, а затем отправить письмо об успешном выполнении. Если же произойдёт ошибка, вместо этого нужно отправить оповещение и пропустить последующие шаги.

Основная единица pg_timetable — цепочка: упорядоченная последовательность задач, в которой результат каждого шага определяет дальнейшее выполнение. Задача может указывать на другую задачу, выполняемую в случае успеха, и на отдельную задачу, выполняемую при ошибке. Таким образом, планирование становится управлением рабочим процессом: вы не просто запускаете отдельные операторы, а задаёте логику выполнения, которая хранится в базе данных вместе с вашими данными.

Цепочечная модель также позволяет выполнять автономные задачи: шаг запускается и отделяется, позволяя цепочке продолжать работу без ожидания его завершения. Это вообще не относится к концепции cron — просто в реальных процессах автоматизации часто встречаются шаги, завершение которых не имеет значения для основного рабочего процесса.

J.1.7.2.2. На основе базы данных, но без привязки к ней #

Каждый планировщик заданий для Tantor BE хранит метаданные заданий в базе данных. Однако для большинства из них требуется расширение Tantor BE, а значит, настройка shared_preload_libraries, перезапуск сервера и зависимость от определённой основной версии Tantor BE.

pg_timetable — автономный исполняемый файл на Go. Он подключается к Tantor BE, как и любой другой клиент, — через libpq, используя строку подключения. Не нужно устанавливать расширение или перезапускать сервер; нет привязки к конкретной версии Tantor BE или модели развёртывания. Если к серверу можно подключиться с помощью psql, pg_timetable может планировать на нём выполнение задач.

У этой архитектуры есть и второе, менее очевидное следствие: выполнение на удалённых базах данных. Один экземпляр pg_timetable может планировать задания на нескольких серверах Tantor BE, в том числе расположенных на разных узлах, работающих под управлением разных версий и размещённых у разных облачных провайдеров. Большинство конкурирующих решений либо ограничены локальным сервером (pg_cron, работающий как фоновый процесс), либо могут обращаться к удалённым узлам, но требуют сложной настройки (pgAgent). Для pg_timetable каждая строка подключения — равноправная цель планирования с собственными цепочками, контекстом выполнения и пространством имён для журналирования.

Реализация на Go, а не на C или C++, также означает наличие единственного статически скомпонованного исполняемого файла, который одинаково работает в Linux, macOS, Windows и всех вариантах BSD — без среды выполнения, неожиданностей при динамической компоновке и необходимости в наборе инструментов компиляции при развёртывании.

J.1.7.2.3. Всё необходимое в комплекте #

pg_timetable включает функции, которые другие планировщики для Tantor BE оставляют внешним инструментам. Это сделано намеренно.

Встроенные задачи. Только pg_timetable поставляется с предопределёнными операциями — SendMail, Download, CopyFromFile, Sleep, Log и другими, — которые можно напрямую использовать в качестве шагов цепочки. Чтобы отправить электронное письмо при сбое цепочки ETL, не нужно вызывать сценарий оболочки: достаточно добавить задачу SendMail с нужными параметрами и подключить её к ветке обработки ошибок.

Параметры задач. Только pg_timetable поддерживает параметризованные задачи. Определение my_func($1, $2) может получать разные аргументы в зависимости от вызывающей его цепочки, что позволяет повторно использовать задачу в разных цепочках без дублирования. В сочетании с форматом COMMAND_CONFIG на основе YAML или JSON это также означает, что встроенные задачи принимают структурированную конфигурацию, а не непрозрачные строки командной оболочки.

Детализированное журналирование. Другие планировщики либо записывают сообщения в один приёмник, либо не документируют особенности журналирования. pg_timetable одновременно ведёт журналы на трёх уровнях (сеанс, задание, задача) и направляет их в три места: stdout/stderr, файл и таблицы базы данных. Средство журналирования в базу данных записывает структурированные строки в timetable.log, поэтому историю выполнения можно запрашивать с помощью SQL — вы можете выполнить SELECT для журнала аудита планировщика тем же инструментом, которым просматриваете данные приложения.

Управление выполнением. Тайм-ауты на уровне заданий и задач предотвращают неконтролируемое выполнение процессов. Ограничение одновременного выполнения (max_instances) не допускает одновременных запусков одной и той же цепочки. Возможность вручную запускать и завершать выполнение помогает при отладке — большинство планировщиков этого не поддерживает. Эти возможности не кажутся впечатляющими, но их отсутствие сразу ощущается в промышленной эксплуатации, а pg_timetable — единственный планировщик для Tantor BE, который предоставляет их все.

J.1.7.2.4. Проектирование с приоритетом операторов #

pg_timetable предполагает, что его основной пользователь — администратор базы данных или инженер по эксплуатации, который уже знаком с синтаксисом cron, работает с SQL и хочет, чтобы конфигурацию расписания можно было хранить в системе контроля версий и проверять так же, как миграции схемы.

Нет зависимости от графического интерфейса. Для задания расписаний pgAgent требуется графический интерфейс — синтаксис cron в качестве входных данных не принимается. В pg_timetable подход намеренно противоположный: расписания всегда задаются выражениями cron, строками интервалов или токенами, подобными cron (@reboot, @every), независимо от того, определяются ли они через timetable.add_job() в SQL или через файл YAML. Преобразования флажков в выражения cron нет, поскольку нет и самих флажков.

Конфигурация как код. Цепочки можно определять в SQL (с помощью вызова add_job() и связанных функций) или в файлах YAML, загружаемых при запуске. Оба варианта представляют собой обычный текст, который можно хранить в системе контроля версий и проверять в запросе на включение изменений. Для рабочих сред рекомендуется использовать YAML: это отделяет конфигурацию расписания от состояния во время выполнения, делает массовые обновления безопасными и естественным образом интегрируется с конвейерами CI/CD.

Разнообразие способов планирования. pg_timetable — единственный планировщик для Tantor BE, который одновременно поддерживает стандартное расписание cron, планирование по интервалам, выполнение при @reboot, запуск и остановку вручную, ограничения времени выполнения заданий и задач, отключение заданий, а также самоуничтожающиеся задания (выполняемые один раз и затем удаляемые). Это не просто перечень возможностей: за ним стоит подход, согласно которому планирование должно отвечать самым разным эксплуатационным потребностям, а инструмент не должен вынуждать вас переходить на другой планировщик лишь потому, что сценарий изменился с «выполнять каждый вторник» на «выполнить один раз при перезапуске планировщика» или «выполнить сейчас, потому что я занимаюсь отладкой».

J.1.7.2.5. Чем не является pg_timetable #

pg_timetable не является распределённым механизмом выполнения рабочих процессов. Он не координирует цепочки между несколькими экземплярами планировщика, не реализует выбор лидера и не предоставляет менеджер распределённых блокировок. Если вам требуется горизонтально масштабируемое выполнение заданий с переключением при отказе, вам скорее подойдут Apache Airflow или Temporal. pg_timetable рассчитан на модель эксплуатации с одним планировщиком на кластер баз данных, которая подходит для подавляющего большинства развёртываний Tantor BE.

pg_timetable не заменяет системный cron для задач, не связанных с базой данных. Если нужно запланировать очистку файловой системы или перезагрузку системы, используйте cron. Дополнительная сложность pg_timetable оправданна, когда запланированная работа связана с Tantor BE — напрямую (задачи SQL), косвенно (задачи оболочки, которые подключаются к Tantor BE) или на уровне эксплуатации (встроенные задачи, зависящие от состояния базы данных).

pg_timetable — не система мониторинга. Он поддерживает экспорт в OpenTelemetry и журналирование на уровне базы данных, но не заменяет правила оповещения Prometheus или панели мониторинга Grafana. Он сообщает, какие задания выполнил и успешно ли они завершились; настройка оповещений остаётся за вами.

J.1.7.2.6. Почему Go? Почему автономный вариант? #

Выбор Go в качестве языка реализации не был случайным. Планировщик для Tantor BE должен управлять одновременными подключениями к базе данных, длительно работающими горутинами задач, контролем тайм-аутов и обработкой сигналов — всё это естественным образом реализуется с помощью примитивов параллелизма Go. Один статически скомпонованный исполняемый файл устраняет проблемы с зависимостями времени выполнения, характерные для планировщиков на C/C++ (расхождение версий libpq, изменения ABI компилятора), а также избавляет от избыточного потребления ресурсов JVM, из-за которого планировщики на Java слишком тяжелы для вспомогательного процесса.

Автономная архитектура — в отличие от фонового рабочего процесса Tantor BE — позволяет развёртывать pg_timetable как службу systemd, контейнер Docker, вспомогательный контейнер Kubernetes или задание Nomad без изменения конфигурации сервера Tantor BE. Это также позволяет перезапускать, обновлять или переносить планировщик на другой узел, не затрагивая сервер базы данных. Это важно, когда база данных предоставляется как управляемый облачный сервис, в котором нельзя изменить shared_preload_libraries.

J.1.7.2.7. Дополнительная информация #

J.1.7.3. Модель безопасности хранилища секретов #

Хранилище секретов по замыслу допускает только запись — пути чтения значений в открытом виде нет; хранящиеся значения зашифрованы с помощью pgp_sym_encrypt (из расширения pgcrypto), расшифровываются только функцией timetable.resolve_secret() с атрибутом SECURITY DEFINER, когда вызывающая сторона передаёт ключ шифрования, и никогда не возвращаются в SQL в открытом виде за пределами разрешённого параметра. Суррогатного secret_id нет; строки идентифицируются только по (client_name, secret_name).

Работающий процесс планировщика является доверенной границей выполнения. Хранилище секретов обеспечивает дополнительную защиту от:

  • другие роли базы данных (Grafana, отчётность, нерегламентные сеансы администраторов баз данных),

  • подписчики логической репликации, и

  • Архивы pg_dump, созданные без ключа шифрования.

Это не обеспечивает дополнительной защиты от компрометации узла, на котором работает рабочий процесс, просмотра аргументов командной строки через ps / auditd или любой стороны, располагающей одновременно value_enc и значением PGTT_SECRET_KEY. Роль, от имени которой планировщик подключается к базе данных, может читать value_enc напрямую; конфиденциальность зависит от сохранности ключа шифрования, который никогда не хранится в базе данных.

Эта возможность повышает уровень защиты от других ролей базы данных, логических реплик и pg_dump, не имеющих ключа. Сама по себе она не обеспечивает соблюдение каких-либо конкретных нормативных требований к управлению секретами (хранение ключей по PCI-DSS, ротация по SOC 2).

Задачи PROGRAM (samples/Shell.sql) принимают массив argv в формате JSON. Полученные значения попадают в argv, и их можно увидеть через /proc/<pid>/cmdline и /proc/<pid>/environ на узле рабочего процесса. Это описанный компромисс версии v1, а не ошибка.

При --log-level=debug и --log-database-level=debug трассировщик pgx сохраняет записи о запросах в timetable.log. Регистратор pgx учитывает контекст: для запросов, выполняемых в контексте log.WithoutQueryArgs(ctx) (маркер, используемый ResolveSecrets*), поле args опускается, а sql сохраняется, поэтому ни открытый текст, ни ключ шифрования не попадают в timetable.log или журнал, выводимый в stdout или файл.

execution_log.params намеренно остаётся в неразрешённой форме ${secret:name}.

J.1.7.3.1. Компромиссы по сравнению с альтернативами #

.pgpass / .pg_service.conf на рабочем узле лучше подходят для паролей удалённого Postgres, чем ${secret:...}: в этом случае учётные данные вообще не попадают в базу данных. Сложность использования хранилища секретов оправданна для учётных данных, у которых нет локального аналога на узле, например паролей SMTP.

Переменные окружения или стандартный ввод лучше подходят, чем ${secret:...}, для чувствительных аргументов argv задачи PROGRAM в промышленной среде: передача дочернему процессу буквальной строки ${secret:x} привела бы к незаметной ошибке (сама строка-заполнитель, а не секрет), а не к явному отказу из-за отсутствия поддержки.