J.1. pg_timetable#
J.1. pg_timetable #
J.1.1. Обзор #
Версия: 7.1.0
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. Локально из скачанного пакета #
Скачайте пакет
pg_timetable, подходящий для вашей операционной системы, с сайта nexus-public.Выполните установку
pg_timetableс помощьюdb_extension_installer.shиз скачанного пакета:./db_extension_installer.sh \ --from-file=<path to pg_timetable package>
J.1.2.2. Автоматически из репозитория пакетов #
Установите значение переменной окружения
NEXUS_URL:export NEXUS_URL="nexus-public.tantorlabs.ru"
Выполните установку
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, запланируем однократное задание и проследим за его выполнением.
Загрузите исполняемый файл pg_timetable.
Убедитесь, что сервер Tantor BE запущен и в нём есть роль с правом
CREATEдля целевой базы данных, например:CREATE ROLE scheduler PASSWORD 'somestrong'; GRANT CREATE ON DATABASE my_database TO scheduler;
Создайте новое задание, например, для выполнения
VACUUMкаждую ночь в 00:30 по часовому поясу сервера Postgres.SELECT timetable.add_job('frequent-vacuum', '30 0 * * *', 'VACUUM');add_job --------- 3 (1 row)Запустите pg_timetable
pg_timetable postgresql://scheduler:somestrong@localhost/my_database --clientname=vacuumer
Готово!
J.1.4.2. Ваша первая YAML-цепочка #
В этом руководстве мы опишем цепочку в файле YAML, загрузим её и посмотрим, как pg_timetable выполнит её при запуске.
Убедитесь, что pg_timetable установлен и у вас есть роль с правом
CREATEв целевой базе данных. Если вы ещё не выполнили эти шаги, обратитесь к первому руководству.Создайте файл с именем
hello.yaml:chains: - name: "hello-yaml" schedule: "@reboot" live: true tasks: - name: "hello" kind: "BUILTIN" command: "Log" parameters: - "Hello from my first YAML chain!"Проверьте файл перед его загрузкой:
pg_timetable --file hello.yaml --validate postgresql://scheduler:somestrong@localhost/my_database
Вы увидите:
YAML file validation successful
Загрузите цепочку и запустите её с помощью pg_timetable. Цепочки
@rebootвыполняются сразу после запуска планировщика, поэтому результат будет виден немедленно:pg_timetable --file hello.yaml --clientname=yamltester postgresql://scheduler:somestrong@localhost/my_database
Во втором терминале проверьте, что создала цепочка:
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)Готово!
Полный список полей, типов задач и вариантов обработки ошибок приведён в руководстве по настройке цепочек YAML и справочнике «Схема цепочек YAML».
J.1.4.3. Обработка ошибок цепочки #
В этом руководстве мы запланируем цепочку, которая всегда завершается ошибкой, добавим обработчик ошибок, который регистрирует сбой и планирует повторную попытку с увеличивающейся задержкой, а затем проследим, как задержка растёт в течение нескольких попыток.
Убедитесь, что вы выполнили инструкции из раздела Ваша первая запланированная цепочка — мы будем использовать ту же роль
schedulerи базу данныхmy_database.Создайте обработчик повторных попыток. Он подсчитывает, сколько раз
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 $$;Запланируйте цепочку, которая каждый раз завершается с ошибкой, и назначьте для неё обработчик с
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планирует первый запуск немедленно, а последующие — каждый час; собственные повторные попытки обработчика позволяют запускать его повторно раньше этого срока.Запустите 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
Во втором терминале убедитесь, что каждая попытка была зарегистрирована:
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)Готово! Вы справились со сбоем цепочки, не контролируя её вручную.
Описание всех полей обработки ошибок на уровне задач и цепочек (ignore_error, on_error, autonomous)
см. в разделе Справочник по командам, задачам и цепочкам. Готовый к запуску вариант
этого шаблона с настраиваемыми ограничениями см. в файле
samples/DelayedRetry.sql
в разделе Примеры.
J.1.4.4. Запуск и остановка цепочек вручную #
В этом руководстве мы запустим pg_timetable в режиме отладки — при этом автоматическое планирование полностью отключено, а цепочки запускаются только вручную. Такой порядок работы используется при разработке, отладке и тестовых запусках.
Убедитесь, что вы выполнили инструкции из раздела Ваша первая запланированная цепочка — мы будем использовать ту же роль
schedulerи базу данныхmy_database.Создайте цепочку, которая приостанавливает выполнение на 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во всех примерах.Запустите 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игнорируются. Планировщик реагирует только на команды, введённые вручную.Запустите цепочку вручную:
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.Теперь запустите его снова и на этот раз остановите в процессе выполнения. Из 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.Готово! Теперь вы можете запускать и останавливать цепочки по требованию.
Несколько моментов, о которых следует помнить:
--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 подставит его во время выполнения, ни разу не записав пароль в открытом виде в журнал.
Убедитесь, что вы выполнили инструкции из раздела Ваша первая запланированная цепочка — мы будем использовать ту же роль
schedulerи базу данныхmy_database.Выберите ключ шифрования и запустите с ним pg_timetable:
pg_timetable postgresql://scheduler:somestrong@localhost/my_database --clientname=secrettester --secret-key=mysecretkey123
Оставьте его работающим; мы вернёмся к нему на шаге 5.
Во втором терминале установите
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.Создайте цепочку с задачей, которая подключается к базе данных, используя
${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указывает на действительно удалённый сервер; здесь же он указывает на тот же сервер, чтобы пример не зависел от внешних ресурсов.Перезапустите 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— значение имеют только имена и порядок сообщений.Убедитесь, что задача выполнилась, а пароль в открытом виде не попал в журнал:
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.Готово! Вы получили секрет во время выполнения, ни разу не сохранив и не записав его в журнал в виде открытого текста.
Сведения обо всех таблицах, функциях и правах доступа хранилища секретов см. в разделе
Справочник по хранилищу секретов. О схеме с доступом только на запись и её границе доверия см. в разделе
Модель безопасности хранилища секретов. Административные действия (предоставление прав отдельной роли администратора секретов, использование секретов в цепочках,
описанных в YAML) приведены в разделе Использование хранилища секретов. Более подробный пример с
отдельной таблицей для удалённых журналов см. в файле
samples/RemoteDB.sql
в разделе Примеры.
J.1.5. Практические руководства #
J.1.5.1. Планирование типовых заданий #
Различные примеры можно найти в разделе Примеры. Сведения о переходе с другого планировщика см. в разделе Миграция.
На практике обычно достаточно простых заданий. Под этим термином понимается следующее:
задание — это цепочка, содержащая только одну задачу (шаг);
оно не использует сложную логику, а простую команду;
это не требует сложной обработки транзакций, поскольку одна задача неявно выполняется как одна транзакция.
Для такой группы цепочек мы ввели специальную функцию timetable.add_job().
Полное описание параметров timetable.add_job() см. в разделе Схема базы данных.
J.1.5.1.1. Примеры #
Выполнять
public.my_func()в 00:05 каждый день в августе по часовому поясу сервера Postgres:SELECT timetable.add_job('execute-func', '5 0 * 8 *', 'SELECT public.my_func()');Запускать
VACUUMна 23-й минуте каждого второго часа с 0 до 20 каждый день по часовому поясу сервера Postgres:SELECT timetable.add_job('run-vacuum', '23 0-20/2 * * *', 'VACUUM');Обновлять материализованное представление каждые 2 часа:
SELECT timetable.add_job('refresh-matview', '@every 2 hours', 'REFRESH MATERIALIZED VIEW public.mat_view');Очищать таблицу журнала после перезапуска pg_timetable:
SELECT timetable.add_job('clear-log', '@reboot', 'TRUNCATE timetable.log');Переиндексировать по воскресеньям в полночь по часовому поясу сервера 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');передача пароля с помощью переменной окружения через оболочку
bashSELECT timetable.add_job('reindex', '0 0 * * 7', 'bash', '["-c", "PGPASSWORD=5m3R7K4754p4m reindexdb -U postgres -h 192.168.0.221 -v"]'::jsonb, 'PROGRAM');
Запускать задание на каждой итерации цикла планировщика (по умолчанию каждые 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:
Запросите сведения о цепочке и задачах:
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;Преобразовать в формат YAML:
chain_name→namerun_at→schedulelive→livemax_instances→max_instancesПоля задачи отображаются напрямую
Проверьте преобразование:
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
для работающего клиента.
Настройте
--secret-key(илиPGTT_SECRET_KEY) для процесса планировщика.Установите
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.Замените литерал в параметре на
"${secret:your_name}"(для полей jsonb) илиpassword=${secret:your_name}(для строк подключения).Необязательно: предоставьте отдельной административной роли доступ только на запись. Схема не предоставляет прав по умолчанию для
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.1. Все сигналы одновременно (рекомендуется) #
Самый простой способ настроить локальную работу с трассировками и метриками — использовать образ grafana/otel-lgtm. Он объединяет OTel Collector, Grafana, Tempo (трассировки) и Mimir (метрики) в одном контейнере — настройка не требуется.
# 1. Start the all-in-one observability stack docker run --rm -d \ -p 4317:4317 \ -p 4318:4318 \ -p 3000:3000 \ grafana/otel-lgtm # 2. Run pg_timetable with both signals enabled pg_timetable \ --otel-endpoint grpc://localhost:4317 \ --otel-traces \ --otel-metrics \ --otel-insecure \ postgresql://scheduler:pass@localhost/mydb
Откройте http://localhost:3000 (учётные данные по умолчанию: admin/admin), чтобы просматривать трассировки в Tempo
и метрики в Mimir через Grafana.
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. Задача #
Следующий строительный блок — задача, которая представляет собой отдельный шаг в списке команд цепочки. Пример задач, объединённых в цепочку:
Загрузить файлы с сервера
Импортировать файлы
Выполнить агрегацию
Построить отчёт
Удалить файлы с диска
Примечание
Все задачи цепочки в pg_timetable выполняются в рамках одной транзакции. Однако обратите внимание, что откатить задачи PROGRAM и BUILTIN невозможно.
J.1.6.3.2.1. Таблица timetable.task #
| Поле | Тип | Описание |
|---|---|---|
chain_id | bigint | Ссылка на цепочку; если NULL, задача считается отключённой |
task_order | DOUBLE PRECISION | Указывает порядковый номер задачи в цепочке |
kind | timetable.command_kind | Тип команды. Может быть SQL (по умолчанию), PROGRAM или BUILTIN |
command | text | Содержит команду SQL, путь к приложению или имя команды BUILTIN, которая будет выполнена |
run_as | text | Роль, от имени которой должна выполняться задача |
database_connection | text | Строка подключения к внешней базе данных, которую следует использовать |
ignore_error | boolean | Указывает, следует ли продолжать выполнение следующей задачи при возникновении ошибки (по умолчанию: false) |
autonomous | boolean | Указывает, должна ли задача выполняться вне транзакции цепочки. Полезно для VACUUM, CREATE DATABASE, CALL и т. д. |
timeout | integer | Прерывать любую задачу в цепочке, выполнение которой занимает больше указанного числа миллисекунд |
live | boolean | Признак готовности задачи к выполнению; при значении 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_id | bigint | Идентификатор задачи |
order_id | integer | Порядковый номер параметра. Несколько параметров обрабатываются один за другим в указанном порядке |
value | jsonb | Значение JSON, содержащее параметры |
J.1.6.3.2.3. Формат значения параметра #
В зависимости от типа команды аргумент может быть представлен разными значениями JSON.
J.1.6.3.2.5. PROGRAM #
Схема: массив строк
Пример:
'["-x", "Latin-ASCII", "-o", "orte_ansi.txt", "orte.txt"]'::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_name | text | Уникальное имя цепочки |
run_at | timetable.cron | Стандартное значение в стиле cron для часового пояса сервера Postgres или выражение @after, @every, @reboot. Если указано NULL, цепочка запускается каждую минуту |
max_instances | integer | Максимальное количество экземпляров этой цепочки, которые могут выполняться одновременно |
timeout | integer | Прерывать любую цепочку, выполнение которой занимает больше указанного числа миллисекунд |
live | boolean | Определяет, может ли цепочка быть выполнена, когда наступит время её выполнения по расписанию |
self_destruct | boolean | Удалить цепочку после успешного выполнения. В случае неудачи цепочка будет выполнена по расписанию ещё один раз |
exclusive_execution | boolean | Указывает, следует ли выполнять цепочку монопольно, приостановив выполнение всех остальных цепочек |
client_name | text | Указывает, какой клиент должен выполнять цепочку. Установите значение 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 | Столбец БД | Тип | Значение по умолчанию | Описание |
|---|---|---|---|---|
name | chain_name | TEXT | обязательно | Уникальный идентификатор цепочки |
schedule | run_at | cron | обязательно | Расписание в формате cron. Если не указано или пусто, по умолчанию используется * * * * * (каждую минуту) |
live | live | BOOLEAN | false | Активна ли цепочка |
max_instances | max_instances | INTEGER | null | Максимальное число одновременно выполняемых экземпляров |
timeout | timeout | INTEGER | 0 | Тайм-аут цепочки (мс) |
self_destruct | self_destruct | BOOLEAN | false | Удалить после успешного выполнения |
exclusive | exclusive_execution | BOOLEAN | false | Приостанавливать другие цепочки |
client_name | client_name | TEXT | null | Ограничить конкретным клиентом |
on_error | on_error | TEXT | null | SQL для обработки ошибок |
J.1.6.4.2.2. Уровень задачи #
| Поле YAML | Столбец БД | Тип | Значение по умолчанию | Описание |
|---|---|---|---|---|
name | task_name | TEXT | null | Описание задачи |
kind | kind | ENUM | 'SQL' | Тип команды (SQL/PROGRAM/BUILTIN) |
command | command | TEXT | обязательно | Команда для выполнения |
parameters | через timetable.parameter | Массив элементов любого типа | null | Массив значений параметров, хранящихся в отдельных строках JSONB с order_id |
run_as | run_as | TEXT | null | Роль для SET ROLE |
connect_string | database_connection | TEXT | null | Строка подключения |
ignore_error | ignore_error | BOOLEAN | false | Продолжать при ошибке |
autonomous | autonomous | BOOLEAN | false | Выполнять вне транзакции |
timeout | timeout | INTEGER | 0 | Время ожидания задачи (мс) |
live | live | BOOLEAN | true | Выполняется ли задача; отключённые задачи пропускаются |
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. Правила проверки #
Обязательные поля:
name,schedule,tasksиcommandдля каждой задачиУникальные имена: Имена цепочек должны быть уникальными в пределах базы данных
Допустимый Cron: Расписание должно быть в допустимом формате cron (5 полей)
Допустимый тип: Тип задачи должен быть одним из следующих: SQL, PROGRAM, BUILTIN
Типы параметров: Параметры могут быть любым типом, совместимым с JSON (строки, числа, логические значения, массивы, объекты) и хранятся как отдельные значения JSONB
Значения тайм-аутов: Должны быть неотрицательными целыми числами (миллисекунды)
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.5.2. Функции, связанные с заданиями #
-- add_task() will add a task to the same chain as the task with `parent_id`
CREATE OR REPLACE FUNCTION timetable.add_task(
IN kind timetable.command_kind,
IN command TEXT,
IN parent_id BIGINT,
IN order_delta DOUBLE PRECISION DEFAULT 10
) RETURNS BIGINT AS $$
INSERT INTO timetable.task (chain_id, task_order, kind, command)
SELECT chain_id, task_order + $4, $1, $2 FROM timetable.task WHERE task_id = $3
RETURNING task_id
$$ LANGUAGE SQL;
COMMENT ON FUNCTION timetable.add_task IS 'Add a task to the same chain as the task with parent_id';
-- add_job() will add one-task chain to the system
CREATE OR REPLACE FUNCTION timetable.add_job(
job_name TEXT,
job_schedule timetable.cron,
job_command TEXT,
job_parameters JSONB DEFAULT NULL,
job_kind timetable.command_kind DEFAULT 'SQL'::timetable.command_kind,
job_client_name TEXT DEFAULT NULL,
job_max_instances INTEGER DEFAULT NULL,
job_live BOOLEAN DEFAULT TRUE,
job_self_destruct BOOLEAN DEFAULT FALSE,
job_ignore_errors BOOLEAN DEFAULT TRUE,
job_exclusive BOOLEAN DEFAULT FALSE,
job_on_error TEXT DEFAULT NULL
) RETURNS BIGINT AS $$
WITH
cte_chain (v_chain_id) AS (
INSERT INTO timetable.chain (chain_name, run_at, max_instances, live, self_destruct, client_name, exclusive_execution, on_error)
VALUES (job_name, job_schedule,job_max_instances, job_live, job_self_destruct, job_client_name, job_exclusive, job_on_error)
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, job_kind, job_command, job_ignore_errors, TRUE
FROM cte_chain
RETURNING task_id
),
cte_param AS (
INSERT INTO timetable.parameter (task_id, order_id, value)
SELECT v_task_id, 1, job_parameters FROM cte_task, cte_chain
)
SELECT v_chain_id FROM cte_chain
$$ LANGUAGE SQL;
COMMENT ON FUNCTION timetable.add_job IS 'Add one-task chain (aka job) to the system';
-- notify_chain_start() will send notification to the worker to start the chain
CREATE OR REPLACE FUNCTION timetable.notify_chain_start(
chain_id BIGINT,
worker_name TEXT,
start_delay INTERVAL DEFAULT NULL
) RETURNS void AS $$
SELECT pg_notify(
worker_name,
format('{"ConfigID": %s, "Command": "START", "Ts": %s, "Delay": %s}',
chain_id,
EXTRACT(epoch FROM clock_timestamp())::bigint,
COALESCE(EXTRACT(epoch FROM start_delay)::bigint, 0)
)
)
$$ LANGUAGE SQL;
COMMENT ON FUNCTION timetable.notify_chain_start IS 'Send notification to the worker to start the chain';
-- notify_chain_stop() will send notification to the worker to stop the chain
CREATE OR REPLACE FUNCTION timetable.notify_chain_stop(
chain_id BIGINT,
worker_name TEXT
) RETURNS void AS $$
SELECT pg_notify(
worker_name,
format('{"ConfigID": %s, "Command": "STOP", "Ts": %s}',
chain_id,
EXTRACT(epoch FROM clock_timestamp())::bigint)
)
$$ LANGUAGE SQL;
COMMENT ON FUNCTION timetable.notify_chain_stop IS 'Send notification to the worker to stop the chain';
-- move_task_up() will switch the order of the task execution with a previous task within the chain
CREATE OR REPLACE FUNCTION timetable.move_task_up(IN task_id BIGINT) RETURNS boolean AS $$
WITH current_task (ct_chain_id, ct_id, ct_order) AS (
SELECT chain_id, task_id, task_order FROM timetable.task WHERE task_id = $1
),
tasks(t_id, t_new_order) AS (
SELECT task_id, COALESCE(LAG(task_order) OVER w, LEAD(task_order) OVER w)
FROM timetable.task t, current_task ct
WHERE chain_id = ct_chain_id AND (task_order < ct_order OR task_id = ct_id)
WINDOW w AS (PARTITION BY chain_id ORDER BY ABS(task_order - ct_order))
LIMIT 2
),
upd AS (
UPDATE timetable.task t SET task_order = t_new_order
FROM tasks WHERE tasks.t_id = t.task_id AND tasks.t_new_order IS NOT NULL
RETURNING true
)
SELECT COUNT(*) > 0 FROM upd
$$ LANGUAGE SQL;
COMMENT ON FUNCTION timetable.move_task_up IS 'Switch the order of the task execution with a previous task within the chain';
-- move_task_down() will switch the order of the task execution with a following task within the chain
CREATE OR REPLACE FUNCTION timetable.move_task_down(IN task_id BIGINT) RETURNS boolean AS $$
WITH current_task (ct_chain_id, ct_id, ct_order) AS (
SELECT chain_id, task_id, task_order FROM timetable.task WHERE task_id = $1
),
tasks(t_id, t_new_order) AS (
SELECT task_id, COALESCE(LAG(task_order) OVER w, LEAD(task_order) OVER w)
FROM timetable.task t, current_task ct
WHERE chain_id = ct_chain_id AND (task_order > ct_order OR task_id = ct_id)
WINDOW w AS (PARTITION BY chain_id ORDER BY ABS(task_order - ct_order))
LIMIT 2
),
upd AS (
UPDATE timetable.task t SET task_order = t_new_order
FROM tasks WHERE tasks.t_id = t.task_id AND tasks.t_new_order IS NOT NULL
RETURNING true
)
SELECT COUNT(*) > 0 FROM upd
$$ LANGUAGE SQL;
COMMENT ON FUNCTION timetable.move_task_down IS 'Switch the order of the task execution with a following task within the chain';
-- delete_task() will delete the task from a chain
CREATE OR REPLACE FUNCTION timetable.delete_task(IN task_id BIGINT) RETURNS boolean AS $$
WITH del_task AS (DELETE FROM timetable.task WHERE task_id = $1 RETURNING task_id)
SELECT EXISTS(SELECT 1 FROM del_task)
$$ LANGUAGE SQL;
COMMENT ON FUNCTION timetable.delete_task IS 'Delete the task from a chain';
-- delete_job() will delete the chain and its tasks from the system
CREATE OR REPLACE FUNCTION timetable.delete_job(IN job_name TEXT) RETURNS boolean AS $$
WITH del_chain AS (DELETE FROM timetable.chain WHERE chain.chain_name = $1 RETURNING chain_id)
SELECT EXISTS(SELECT 1 FROM del_chain)
$$ LANGUAGE SQL;
COMMENT ON FUNCTION timetable.delete_job IS 'Delete the chain and its tasks from the system';
-- pause_job() will pause the chain (set live = false)
CREATE OR REPLACE FUNCTION timetable.pause_job(IN job_name TEXT) RETURNS boolean AS $$
WITH upd_chain AS (UPDATE timetable.chain SET live = false WHERE chain.chain_name = $1 RETURNING chain_id)
SELECT EXISTS(SELECT 1 FROM upd_chain)
$$ LANGUAGE SQL;
COMMENT ON FUNCTION timetable.pause_job IS 'Pause the chain (set live = false)';
-- resume_job() will resume the chain (set live = true)
CREATE OR REPLACE FUNCTION timetable.resume_job(IN job_name TEXT) RETURNS boolean AS $$
WITH upd_chain AS (UPDATE timetable.chain SET live = true WHERE chain.chain_name = $1 RETURNING chain_id)
SELECT EXISTS(SELECT 1 FROM upd_chain)
$$ LANGUAGE SQL;
COMMENT ON FUNCTION timetable.resume_job IS 'Resume the chain (set live = true)';
J.1.6.5.2.1. Параметры timetable.add_job() #
Создает простую цепочку из одной задачи
Возвращает: BIGINT
J.1.6.5.2.2. Параметры #
| Параметр | Тип | Описание | По умолчанию |
|---|---|---|---|
job_name | text | Уникальное имя цепочки и команды | Обязательно |
job_schedule | timetable.cron | Расписание в формате cron с учётом часового пояса сервера Postgres. Если указано NULL, цепочка запускается каждую минуту | Обязательно |
job_command | text | SQL-команда, которая будет выполнена | Обязательно |
job_parameters | jsonb | Аргументы для команды цепочки | NULL |
job_kind | timetable.command_kind | Тип команды: SQL, PROGRAM или BUILTIN | SQL |
job_client_name | text | Указывает, какой клиент должен выполнять цепочку. Установите значение NULL, чтобы разрешить выполнение любому клиенту | NULL |
job_max_instances | integer | Максимальное число экземпляров этой цепочки, которые могут выполняться одновременно | NULL |
job_live | boolean | Определяет, может ли цепочка выполняться при наступлении запланированного времени | TRUE |
job_self_destruct | boolean | Удалить цепочку после выполнения | FALSE |
job_ignore_errors | boolean | Игнорировать ошибки во время выполнения | TRUE |
job_exclusive | boolean | Выполнять цепочку в исключительном режиме | FALSE |
Возвращает: идентификатор созданной цепочки
J.1.6.5.3. Функции, связанные с cron #
CREATE OR REPLACE FUNCTION timetable.cron_split_to_arrays(
cron text,
OUT mins integer[],
OUT hours integer[],
OUT days integer[],
OUT months integer[],
OUT dow integer[]
) RETURNS record AS $$
DECLARE
a_element text[];
i_index integer;
a_tmp text[];
tmp_item text;
a_range int[];
a_split text[];
a_res integer[];
max_val integer;
min_val integer;
dimensions constant text[] = '{"minutes", "hours", "days", "months", "days of week"}';
allowed_ranges constant integer[][] = '{{0,59},{0,23},{1,31},{1,12},{0,7}}';
BEGIN
a_element := regexp_split_to_array(cron, '\s+');
FOR i_index IN 1..5 LOOP
a_res := NULL;
a_tmp := string_to_array(a_element[i_index],',');
FOREACH tmp_item IN ARRAY a_tmp LOOP
IF tmp_item ~ '^[0-9]+$' THEN -- normal integer
a_res := array_append(a_res, tmp_item::int);
ELSIF tmp_item ~ '^[*]+$' THEN -- '*' any value
a_range := array(select generate_series(allowed_ranges[i_index][1], allowed_ranges[i_index][2]));
a_res := array_cat(a_res, a_range);
ELSIF tmp_item ~ '^[0-9]+[-][0-9]+$' THEN -- '-' range of values
a_range := regexp_split_to_array(tmp_item, '-');
a_range := array(select generate_series(a_range[1], a_range[2]));
a_res := array_cat(a_res, a_range);
ELSIF tmp_item ~ '^[0-9]+[\/][0-9]+$' THEN -- '/' step values
a_range := regexp_split_to_array(tmp_item, '/');
a_range := array(select generate_series(a_range[1], allowed_ranges[i_index][2], a_range[2]));
a_res := array_cat(a_res, a_range);
ELSIF tmp_item ~ '^[0-9-]+[\/][0-9]+$' THEN -- '-' range of values and '/' step values
a_split := regexp_split_to_array(tmp_item, '/');
a_range := regexp_split_to_array(a_split[1], '-');
a_range := array(select generate_series(a_range[1], a_range[2], a_split[2]::int));
a_res := array_cat(a_res, a_range);
ELSIF tmp_item ~ '^[*]+[\/][0-9]+$' THEN -- '*' any value and '/' step values
a_split := regexp_split_to_array(tmp_item, '/');
a_range := array(select generate_series(allowed_ranges[i_index][1], allowed_ranges[i_index][2], a_split[2]::int));
a_res := array_cat(a_res, a_range);
ELSE
RAISE EXCEPTION 'Value ("%") not recognized', a_element[i_index]
USING HINT = 'fields separated by space or tab.'+
'Values allowed: numbers (value list with ","), '+
'any value with "*", range of value with "-" and step values with "/"!';
END IF;
END LOOP;
SELECT
ARRAY_AGG(x.val), MIN(x.val), MAX(x.val) INTO a_res, min_val, max_val
FROM (
SELECT DISTINCT UNNEST(a_res) AS val ORDER BY val) AS x;
IF max_val > allowed_ranges[i_index][2] OR min_val < allowed_ranges[i_index][1] OR a_res IS NULL THEN
RAISE EXCEPTION '% is out of range % for %', tmp_item, allowed_ranges[i_index:i_index][:], dimensions[i_index];
END IF;
CASE i_index
WHEN 1 THEN mins := a_res;
WHEN 2 THEN hours := a_res;
WHEN 3 THEN days := a_res;
WHEN 4 THEN months := a_res;
ELSE
dow := a_res;
END CASE;
END LOOP;
RETURN;
END;
$$ LANGUAGE PLPGSQL STRICT;
CREATE OR REPLACE FUNCTION timetable.cron_months(
from_ts timestamptz,
allowed_months int[]
) RETURNS SETOF timestamptz AS $$
WITH
am(am) AS (SELECT UNNEST(allowed_months)),
genm(ts) AS ( --generated months
SELECT date_trunc('month', ts)
FROM pg_catalog.generate_series(from_ts, from_ts + INTERVAL '1 year', INTERVAL '1 month') g(ts)
)
SELECT ts FROM genm JOIN am ON date_part('month', genm.ts) = am.am
$$ LANGUAGE SQL STRICT;
CREATE OR REPLACE FUNCTION timetable.cron_days(
from_ts timestamptz,
allowed_months int[],
allowed_days int[],
allowed_week_days int[]
) RETURNS SETOF timestamptz AS $$
WITH
ad(ad) AS (SELECT UNNEST(allowed_days)),
am(am) AS (SELECT * FROM timetable.cron_months(from_ts, allowed_months)),
gend(ts) AS ( --generated days
SELECT date_trunc('day', ts)
FROM am,
pg_catalog.generate_series(am.am, am.am + INTERVAL '1 month'
- INTERVAL '1 day', -- don't include the same day of the next month
INTERVAL '1 day') g(ts)
)
SELECT ts
FROM gend JOIN ad ON date_part('day', gend.ts) = ad.ad
WHERE extract(dow from ts)=ANY(allowed_week_days)
$$ LANGUAGE SQL STRICT;
CREATE OR REPLACE FUNCTION timetable.cron_times(
allowed_hours int[],
allowed_minutes int[]
) RETURNS SETOF time AS $$
WITH
ah(ah) AS (SELECT UNNEST(allowed_hours)),
am(am) AS (SELECT UNNEST(allowed_minutes))
SELECT make_time(ah.ah, am.am, 0) FROM ah CROSS JOIN am
$$ LANGUAGE SQL STRICT;
CREATE OR REPLACE FUNCTION timetable.cron_runs(
from_ts timestamp with time zone,
cron text
) RETURNS SETOF timestamptz AS $$
SELECT cd + ct
FROM
timetable.cron_split_to_arrays(cron) a,
timetable.cron_times(a.hours, a.mins) ct CROSS JOIN
timetable.cron_days(from_ts, a.months, a.days, a.dow) cd
WHERE cd + ct > from_ts
ORDER BY 1 ASC;
$$ LANGUAGE SQL STRICT;
CREATE DOMAIN timetable.cron AS TEXT CHECK(
VALUE = '@reboot'
OR substr(VALUE, 1, 6) IN ('@every', '@after')
AND (substr(VALUE, 7) :: INTERVAL) IS NOT NULL
OR VALUE ~ '^(((\d+,)+\d+|(\d+(\/|-)\d+)|(\*(\/|-)\d+)|\d+|\*) +){4}(((\d+,)+\d+|(\d+(\/|-)\d+)|(\*(\/|-)\d+)|\d+|\*) ?)$'
AND timetable.cron_split_to_arrays(VALUE) IS NOT NULL
);
COMMENT ON DOMAIN timetable.cron IS 'Extended CRON-style notation with support of interval values';
-- is_cron_in_time returns TRUE if timestamp is listed in cron expression
CREATE OR REPLACE FUNCTION timetable.is_cron_in_time(
run_at timetable.cron,
ts timestamptz
) RETURNS BOOLEAN AS $$
SELECT
CASE WHEN run_at IS NULL THEN
TRUE
ELSE
date_part('month', ts) = ANY(a.months)
AND (date_part('dow', ts) = ANY(a.dow) OR date_part('isodow', ts) = ANY(a.dow))
AND date_part('day', ts) = ANY(a.days)
AND date_part('hour', ts) = ANY(a.hours)
AND date_part('minute', ts) = ANY(a.mins)
END
FROM
timetable.cron_split_to_arrays(run_at) a
$$ LANGUAGE SQL;
CREATE OR REPLACE FUNCTION timetable.next_run(cron timetable.cron) RETURNS timestamptz AS $$
SELECT * FROM timetable.cron_runs(now(), cron) LIMIT 1
$$ LANGUAGE SQL STRICT;
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(SQLSTATE0A000), если 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.kind | SQL, PROGRAM или BUILTIN |
task.return_code | 0 при успешном выполнении, -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 никогда не прерывают планирование цепочек.Корректное завершение работы: при получении
SIGTERMpg_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. Дополнительная информация #
Модель планирования — трёхуровневая абстракция (команда → задача → цепочка) и то, как эти уровни сочетаются
Справочник команд, задач и цепочек — точные поля и форматы параметров для каждого уровня
Планировщики PostgreSQL: сравнительная таблица — таблица возможностей, на основе которой были приняты многие из этих проектных решений
Доклад в CERN: планирование заданий в PostgreSQL — презентация Павло Голуба 2020 года об области задач, для которой был разработан pg_timetable
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} привела бы к незаметной ошибке (сама строка-заполнитель, а не секрет), а не к явному отказу из-за отсутствия поддержки.