F.43. pgpro_scheduler
pgpro_scheduler
— это встроенное в Postgres Pro Enterprise расширение, позволяющее планировать и контролировать задания, а также управлять их выполнением в базе данных Postgres Pro Enterprise. С pgpro_scheduler
вы можете:
Задавать сложные расписания в виде объектов
jsonb
или строкcrontab
.Динамически вычислять время следующего запуска для повторяющихся заданий.
Выполнять SQL-команды задания в одной или в нескольких последовательных транзакциях, если требуется.
Назначать задания для немедленного или отложенного однократного выполнения одновременно с обычными планируемыми заданиями.
По сравнению с внешними планировщиками pgpro_scheduler
имеет следующие преимущества:
Любой пользователь может планировать задания независимо.
Планированием заданий можно управлять «на лету», не перезапуская базу данных.
pgpro_scheduler
отличается очень лёгкой реализацией, так как для планирования и контроля заданий, а также для управления ими он использует фоновые рабочие процессы. И при этомpgpro_scheduler
не задействует никакие клиентские подключения.Для большей стабильности в каждой базе данных имеется собственный руководящий планировщик, а каждое запланированное задание выполняется в отдельном рабочем процессе.
Примечание
pgpro_scheduler
находится в состоянии ожидания на ведомом сервере и будет активирован, когда ведущий станет ведомым.
Примечание
Обратите внимание, что для всех выполненных заданий в представлении pg_stat_activity в любом случае будет отображаться имя суперпользователя базы данных, который используется рабочим процессом.
F.43.1. Установка и подготовка
Расширение pgpro_scheduler
включено в состав Postgres Pro Enterprise. Установив Postgres Pro Enterprise, выполните следующие действия, чтобы подготовить pgpro_scheduler
к работе:
Добавьте
pgpro_scheduler
в параметрshared_preload_libraries
в файлеpostgresql.conf
:shared_preload_libraries = 'pgpro_scheduler'
Создайте расширение
pgpro_scheduler
, выполнив следующий запрос:CREATE EXTENSION pgpro_scheduler;
Расширение
pgpro_scheduler
необходимо создать в каждой базе данных, где вы планируете его использовать.
Завершив установку и подготовку, настройте pgpro_scheduler
в вашей базе данных.
F.43.2. Конфигурирование
Для настройки pgpro_scheduler
необходимо иметь права суперпользователя.
Чтобы настроить pgpro_scheduler
, измените следующие параметры в файле postgresql.conf
:
Укажите имена баз данных, для которых вам нужно будет настраивать задания, через запятую:
schedule.database
= 'база1
,база2
'Для ограничения рабочей нагрузки в вашей системе задайте максимальное число рабочих процессов, которые могут выполняться одновременно в каждой базе данных:
schedule.max_workers
= 5Дополнительно можно задать число рабочих процессов, доступных для одного выполнения задания:
schedule.max_parallel_workers
= 3По умолчанию для одноразовых заданий выделяются два процесса. Они не учитываются в ограничении
schedule.max_workers
. Таким образом, одноразовые задания могут выполняться параллельно с заданиями, планируемыми по графику, даже если все процессы в количествеschedule.max_workers
заняты.Выполните
pg_reload_conf()
, чтобы изменения вступили в силу:SELECT
pg_reload_conf()
;
Важно
Модифицируя переменную schedule.max_workers
, обязательно оставьте достаточное количество рабочих процессов для остальной системы, так как эти процессы могут требоваться и другим подсистемам. Значение schedule.max_workers
не может превышать общее число рабочих процессов, установленное переменной max_worker_processes
для СУБД Postgres Pro.
Расширение pgpro_scheduler
запускает отдельные рабочие процессы для системы, для каждой базы данных и для каждого выполняемого задания. Например, если вы работаете с двумя базами данных и установили максимальное число рабочих процессов и параллельных процессов, равным 5 и 3, соответственно, pgpro_scheduler
может использовать до 19 процессов максимум: один процесс, руководящий всей системой, два процесса, контролирующих две базы данных, и в каждой базе ещё по 5 рабочих процессов для планируемых и по 3 для одноразовых заданий. Если все рабочие процессы в этом количестве окажутся заняты, задания будут ожидать освобождения рабочего процесса. Планируемые и одноразовые задания помещаются в отдельные очереди.
Если потребуется, вы можете изменить число рабочих процессов позже. На уже запущенные процессы это не влияет.
Поведение pgpro_scheduler
можно также динамически настраивать из командной строки. Данный пример показывает, как можно установить различное число рабочих процессов для разных баз данных:
ALTER SYSTEM SETschedule.database
= 'database1
,database2
'; ALTER DATABASEdatabase1
SETschedule.max_workers
= 5; ALTER DATABASEdatabase2
SETschedule.max_workers
= 3; ALTER SYSTEM SETschedule.max_parallel_workers
= 3; SELECTpg_reload_conf()
;
Настроив pgpro_scheduler
, включите его в вашей системе так:
SELECT schedule.enable();
Если эта функция возвратит true
, значит pgpro_scheduler
готов к использованию, и вы можете приступать к планированию заданий, как описано в Подразделе F.43.3.1 и Подразделе F.43.3.2.
Примечание
Если перезапустить сервер, pgpro_scheduler
по умолчанию не будет запускаться автоматически. Чтобы поменять это поведение, присвойте параметру schedule.auto_enabled значение on
.
См. также
F.43.3. Использование
F.43.3.1. Создание планируемых заданий
Чтобы создать и запланировать задание, вызовите функцию create_job()
, которая принимает параметры планирования в виде объекта jsonb
:
schedule.create_job(options
jsonb
)
В объекте jsonb
вы должны задать одну или несколько SQL-команд в ключе commands
и задать расписание выполнения в одном из следующих ключей:
dates
— одна дата или массив дат в форматеtimestamp with time zone
cron
— строка в традиционном форматеcrontab
, включающем пять полей. В первом поле задаётся минута, во втором — час, в третьем — день месяца, в четвёртом — номер месяца, а в пятом — номер дня недели. Также может использоваться расширенный форматcrontab
с шестью полями. В этом формате первое поле задаёт секунду. Если вы задаёте строку в формате с шестью полями и секунды не имеют значения, задайте в первом поле 0.Также вместо строки
crontab
можно указать одно из следующих ключевых слов, определяющих, когда будет запускаться задание:@every_second
— каждую секунду@hourly
— в начале каждого часа@daily
— в начале каждого дня@midnight
— в начале каждого дня@weekly
— в начале каждой недели@monthly
— в начале каждого месяца@yearly
— в начале каждого года@annually
— в начале каждого года
rule
— объектjsonb
, содержащий один или несколько следующих ключей:seconds
— секунды; массив целых чисел в диапазоне [0, 59]minutes
— минуты; массив целых чисел в диапазоне [0, 59]hours
— часы; массив целых чисел в диапазоне [0, 23]days
— дни месяца; массив целых чисел в диапазоне [1, 31]months
— месяцы; массив целых чисел в диапазоне [1, 12]wdays
— дни недели; массив целых чисел в диапазоне [0, 6], где 0 — воскресенье.onstart
— целое значение 0 или 1. Еслиonstart
равняется 1, задание выполняется, только когда включёнpgpro_scheduler
.
Для сложных случаев использования ключи dates
, cron
и rule
можно комбинировать.
В результате pgpro_scheduler
создаёт активное задание с заданным расписанием и возвращает идентификатор задания.
Подсказка
Для заданий с простым расписанием вы можете использовать следующий упрощённый синтаксис:
schedule.create_job(cron
,commands
) schedule.create_job(dates
,commands
)
За подробностями обратитесь к описанию функции schedule.create_job().
Если потребуется, вы можете позже изменить один или несколько параметров расписания с помощью функций set_job_attribute()
и set_job_attributes()
, соответственно.
Если все рабочие процессы в указанное время заняты, задание ждёт, пока не появится свободный процесс. По умолчанию ожидание может продолжаться вечно. Вы можете ограничить максимальное время ожидания, установив ключ last_start_available
в формате interval. В случае тайм-аута pgpro_scheduler
отменяет выполнение задания.
Примеры:
Создание задания, которое будет запускаться каждый день в 15:00 и дополнительно, 31 декабря 2017 г. в 19:00, а также 4 апреля 2020 г. в 13:00:
SELECT schedule.create_job('{"commands": "SELECT 15", "cron": "0 15 * * *", "dates": [ "2017-12-31 19:00", "2020-04-04 13:00" ]}');
Ограничение периода, в течение которого задание будет ожидать выполнения, до 30 секунд после запланированного времени:
SELECT schedule.create_job('{"commands": "SELECT pg_sleep(100)", "cron": "15 */2 * * *", "last_start_available": "30 seconds" }');
Примечание
Как в запланированных, так и в одноразовых заданиях управлять основными транзакциями нельзя, в частности использовать COMMIT
и ROLLBACK
. Однако можно создавать автономные транзакции и управлять ими.
F.43.3.1.1. Указание интервала времени для выполнения задания
В дополнение к обычному расписанию вы можете задать интервал времени, в котором может выполняться запланированное задание. Чтобы pgpro_scheduler
выполнял задание только в указанном интервале, определите ключи start_date
и end_date
в формате timestamp with time zone
. Вы можете задать только один из этих ключей, чтобы ограничить только время начала и время окончания, соответственно. Если вы определите интервал времени для задания, pgpro_scheduler
будет исполнять это задание только в этом интервале. Если запущенное задание продолжает выполняться по достижении конца интервала, pgpro_scheduler
завершает его и исключает из дальнейшего плана выполнения.
Примеры:
Создание задания, выполнение которого начнётся только после 11:00 1 мая 2017 г.:
SELECT schedule.create_job('{"commands": "SELECT now()", "cron": "2 17 * * *", "start_date": "2017-05-01 11:00" }');
Создание задания, которое будет выполняться в интервале от 11:00 1 мая до 15:00 4 июня 2017 г.:
SELECT schedule.create_job('{"commands": "SELECT now()", "cron": "2 17 * * *", "start_date": "2017-05-01 11:00", "end_date": "2017-06-04 15:00" }');
F.43.3.1.2. Выполнение SQL-команд в отдельных транзакциях
В ключе commands
значения могут задаваться в виде текста или массива. Если вы задаёте в нём отдельные команды SQL в виде текста, через точку с запятой, всё задание будет выполняться в одной транзакции. Если же требуется, чтобы каждая SQL-команда выполнялась в отдельной транзакции, передайте команды SQL в виде массива. Это поведение можно изменить, установив для параметра use_same_transaction
значение true
. В этом случае SQL-команды в массиве будут выполняться в одной транзакции.
Примеры:
Создание задания, которое будет выполняться полностью в одной транзакции:
SELECT schedule.create_job('{"commands": "SELECT 1; SELECT 2; SELECT 3;", "cron": "23 23 */2 * *" }');
Выполнение команд в отдельных транзакциях:
SELECT schedule.create_job('{"commands": [ "SELECT 1", "SELECT 2", "SELECT 3" ], "cron": "23 23 */2 * *" }');
Создание задания, которое будет выполняться полностью в одной транзакции, когда команды передаются в виде массива:
SELECT schedule.create_job('{"commands": [ "SELECT 1", "SELECT 2", "SELECT 3" ], "cron": "23 23 */2 * *", "use_same_transaction": true }');
F.43.3.1.3. Вычисление времени следующего запуска запланированного задания
Для повторяющихся заданий время следующего запуска может быть вычислено с помощью SQL-оператора, задаваемого в ключе next_time_statement
. В этом случае первый раз задание запускается по расписанию, а все остальные запуски задания производятся в вычисляемое время.
По завершении задания pgpro_scheduler
выполняет SQL-оператор, заданный в ключе next_time_statement
, который должен вычислить время следующего запуска и выдать результат типа timestamp with time zone
. Если возвращаемое значение имеет другой тип или происходит ошибка, pgpro_scheduler
помечает задание как нерабочее и отменяет его дальнейшее выполнение. Этот процесс повторяется при каждом последующем запуске.
Подсказка
Когда задание завершается, pgpro_scheduler
устанавливает состояние транзакции в переменной schedule.transaction_state
, в формате text
. Вы можете использовать эту переменную в команде next_time_statement
для динамического вычисления времени следующего запуска в зависимости от состояния транзакции. В момент выполнения next_time_statement
переменная schedule.transaction_state
должна содержать состояние основной транзакции — success
(успех) или failure
(сбой). Другие варианты состояния указывают на внутреннюю ошибку pgpro_scheduler
.
Примеры:
Создание задания, которое запускается сначала в 10:45, а затем через день после завершения:
SELECT schedule.create_job('{"commands": "SELECT random()", "cron": "45 10 * * *", "next_time_statement": "SELECT now() + ''1 day''::interval" }');
F.43.3.1.4. Определение дополнительных условий для выполнения задания
Расширение pgpro_scheduler
позволяет определять дополнительные условия для выполнения задания:
Устанавливать интервалы времени для выполнения задания в ключе
max_run_time
. Если время выполнения задания истекает,pgpro_scheduler
отменяет задание.Определять максимальное время ожидания выполнения задания с использованием ключа
last_start_available
. Если происходит тайм-аут,pgpro_scheduler
отменяет задание.Планировать выполнение задания с правами другого пользователя, указав ключ
run_as
(при наличии прав суперпользователя).Задавать SQL-команду, которая будет выполняться, если основная команда завершается ошибкой, в ключе
onrollback
.
Примеры:
Ограничение времени выполнения до 5 секунд:
SELECT schedule.create_job('{"commands": "SELECT pg_sleep(10)", "cron": "15 */10 * * *", "max_run_time": "5 seconds" }');
Ограничение периода ожидания выполнения задания до 30 секунд после запланированного времени:
SELECT schedule.create_job('{"commands": "SELECT pg_sleep(100)", "cron": "15 */2 * * *", "last_start_available": "30 seconds" }');
Запуск задания с правами пользователя robot
:
SELECT schedule.create_job('{"commands": "SELECT session_user", "cron": "5 */5 * * *", "run_as": "robot" }');
Определение SQL-команды, которая будет выполняться в случае сбоя основной команды:
SELECT schedule.create_job('{"commands": "SELECT ''zzz''", "cron": "55 */12 * * *", "onrollback": "SELECT ''Cannot select zzz''" }');
F.43.3.2. Назначение одноразовых заданий
Вы можете назначать задания для однократного выполнения, используя функцию schedule.submit_job()
. Для таких заданий используется отдельный набор рабочих процессов в количестве, определённом переменной schedule.max_parallel_workers
, и они могут выполняться одновременно с планируемыми заданиями. По умолчанию одновременно могут выполняться два одноразовых задания. Если вы назначите больше заданий, они будут ждать в очереди появления свободного рабочего процесса.
Чтобы выполнить одноразовое задание немедленно, передайте команды SQL в аргументе query
. Например:
schedule.submit_job(query := 'select 1');
Вместо того, чтобы передавать параметры запроса SQL непосредственно, вы можете определить в аргументе query
нумерованные местозаполнители, например, $1 и $2, и передать в аргументе params
массив параметров так, чтобы каждому местозаполнителю соответствовал элемент массива. Для краткости имена параметров query
и params
можно опустить:
schedule.submit_job(query := 'select $1, $2', params := '{"text 1", "text 2"}')
Чтобы запустить одноразовое задание в определённое время, воспользуйтесь аргументом run_after
:
schedule.submit_job('select ''flowers''', run_after := '2017-03-08 08:00:01');
Также вы можете отложить запуск задания до завершения заданий, указанных в аргументе depends_on
. Например, чтобы запустить задание после завершения заданий под номерами 23, 15 и 334, выполните:
schedule.submit_job('select ''well done''', depends_on := '{23, 15, 334}')
Если требуется, выполнение задания можно переназначить, вызвав функцию schedule.resubmit()
внутри запроса в аргументе query
. Например:
schedule.submit_job('select 1, schedule.resubmit(run_after := ''5'')');
Параметр run_after
задаёт интервал времени, после которого задание будет перезапущено, в секундах. По умолчанию интервал равен 1 секунде.
Переназначенное задание будет выполняться не больше раз, чем задано в аргументе resubmit_limit
. По достижении этого предела задание переходит в состояние done
(завершено), с соответствующим сообщением об ошибке.
Если вы хотите отменить переназначенное задание, выполните:
schedule.cancel_job(ид_задания
bigint
);
Для наблюдения за одноразовыми заданиями воспользуйтесь представлениями pgpro_scheduler
job_status и all_job_status.
Все функции, предназначенные для управления одноразовыми заданиями, описаны в Подразделе F.43.4.6.3.
F.43.3.3. Изменение и удаление запланированных заданий
Когда новое задание создаётся с помощью функции create_job()
, оно становится активным и ждёт выполнения по заданному расписанию. Используя идентификатор задания, возвращённый функцией create_job()
, вы можете изменить параметры расписания или удалить задание. Для изменения свойств заданий используются функции set_job_attribute()
или set_job_attributes()
:
Для изменения одного свойства задания вызовите функцию
set_job_attribute()
, передав ей в параметрах идентификатор задания, имя изменяемого свойства и новое значение для него.Для изменения сразу нескольких свойств задания воспользуйтесь функцией
set_job_attributes()
. В этом случае вы можете задать все эти свойства в одном объектеjsonb
. Все ключи, которые можно использовать в расписании заданий, рассматриваются в описании функцииcreate_job()
.
Чтобы временно отключить выполнение задания по расписанию, вызовите функцию deactivate_job()
:
schedule.deactivate_job(job_id
integer
)
Повторно активизировать задание позже можно, выполнив функцию activate_job()
:
schedule.activate_job(job_id
integer
)
Чтобы безвозвратно удалить задание из планировщика, воспользуйтесь функцией drop_job()
:
schedule.drop_job(job_id
integer
)
F.43.3.4. Наблюдение за запланированными заданиями
Для наблюдения за выполнением заданий в системе в целом необходимо иметь права суперпользователя. Без таких прав можно наблюдать только за заданиями, принадлежащими вам. Для отслеживания запланированных заданий pgpro_scheduler
предоставляет ряд функций, которые возвращают записи cron_rec
или cron_job
:
get_job()
— выдаёт информацию о задании.get_owned_cron()
— выдаёт список заданий, принадлежащих пользователю.get_cron()
— выдаёт список заданий, выполняемых пользователем.get_active_jobs()
— возвращает список заданий, выполняемых в момент вызова функции.get_log()
— возвращает список всех завершённых заданий.get_user_log()
— возвращает список завершённых заданий, выполненных указанным пользователем.clean_log()
— удаляет все записи с информацией о завершённых заданиях.
Чтобы узнать больше о каждой функции, обратитесь к Подразделу F.43.4.6.
F.43.3.5. Аудит изменений расписания
Расширение pgpro_scheduler
позволяет включить аудит изменений расписания, чтобы выяснить, кто допустил ошибку, если в выполнении запланированных заданий произошли неожиданные изменения.
По умолчанию pgpro_scheduler
не сохраняет информацию об изменениях в расписании заданий. Чтобы включить эту возможность, установите для параметра schedule.enable_history значение true
. Когда этот параметр включён, pgpro_scheduler
сохраняет изменения расписания в таблице schedule.cron__history
, а информацию обо всех удалённых заданиях записывает в таблицу schedule.cron__deleted
. Сохранённая в этих таблицах история никогда не удаляется, так что суперпользователь может пересмотреть изменения в расписании, внесённые любым пользователем в любой момент времени.
Подробнее сохраняемая информация описывается в Подразделе F.43.4.5.
F.43.3.6. Планирование заданий в кластере multimaster
Используя pgpro_scheduler
, вы можете управлять заданиями по расписанию и одноразовыми заданиями в кластере, настроенном с применением multimaster. pgpro_scheduler
может управлять заданиями только на том узле, где он установлен. Таким образом, вы должны установить и включить pgpro_scheduler
на всех узлах, где вы хотите планировать задания. Экземпляры pgpro_scheduler
на разных узлах будут управлять заданиями независимо, но выполненные задания будут реплицироваться на другие узлы.
Даже если вы намерены планировать задания только на одном узле, pgpro_scheduler
рекомендуется развернуть на нескольких узлах. В этом случае, если узел с запланированными заданиями откажет, эти задания возьмёт на себя другой экземпляр pgpro_scheduler
. Если pgpro_scheduler
работает на нескольких узлах, для выполнения задания выбирается узел с наименьшим идентификатором. Шаблон именования идентификаторов определяется переменной конфигурации schedule.nodename.
F.43.4. Справка
F.43.4.1. Переменные GUC
schedule.enabled
(boolean
)Устаревшая переменная. Определяет, включён ли
pgpro_scheduler
в данной системе.По умолчанию:
false
.Для
pgpro_scheduler
версии 2.5 или выше вы можете установить параметр schedule.auto_enabled, чтобыpgpro_scheduler
включался при запуске сервера, или пользоваться функциямиschedule.enable()
/schedule.disable()
, чтобы включать/отключать его, когда требуется. Проверить, работает лиpgpro_scheduler
в данный момент, можно с помощью функцииschedule.is_enabled()
.schedule.auto_enabled
(boolean
)Определяет, будет ли
pgpro_scheduler
включаться при запуске сервера.По умолчанию:
false
.schedule.database
(text
)Задаёт базы данных, для которых включён
pgpro_scheduler
. Имена баз данных должны разделяться запятыми.По умолчанию: пустая строка.
schedule.database_to_connect
(text
)База данных, к которой подключается
pgpro_scheduler
, чтобы получить метаданные кластера Postgres Pro Enterprise. Указанную базу данных нельзя удалить, пока работаетpgpro_scheduler
. Изменить этот параметр можно только при перезапуске сервера.По умолчанию:
postgres
.schedule.schema
(text
)Устаревший параметр. Задаёт имя схемы, в которой планировщик сохраняет свои таблицы и функции. Если вам нужно изменить схему по умолчанию, воспользуйтесь командой ALTER EXTENSION.
По умолчанию:
schedule
.schedule.nodename
(text
)Указывает имя узла кластера, на котором работает
pgpro_scheduler
. Эту переменную не нужно изменять или использовать в конфигурации кластера с одним сервером.В кластере, где работает
multimaster
, имя узла оканчивается его идентификатором в конфигурацииmultimaster
. Например, если идентификатор узла равен 3, переменнаяschedule.nodename
получает значениеmtm-node-3
. Однако если вы явно зададите переменнуюschedule.nodename
в файлеpostgresql.conf
или с помощью командыALTER
,pgpro_scheduler
будет использовать заданное значение, не обращая внимания на идентификатор узла.По умолчанию:
primary
.schedule.max_workers
(integer
)Задаёт максимальное число одновременно работающих запланированных по расписанию заданий в одной базе.
По умолчанию:
2
.schedule.max_parallel_workers
(integer
)Задаёт максимальное число параллельных потоков, которые могут использоваться для выполнения одноразовых заданий.
По умолчанию:
2
.schedule.transaction_state
(text
)Внутренняя переменная, содержащая состояние выполняемого задания.
pgpro_scheduler
использует эту переменную для вычисления времени следующего запуска задания. Возможные значения:success
— транзакция завершилась успешно.failure
— транзакция завершилась сбоем.running
— транзакция в процессе выполнения.undefined
— транзакция ещё не запускалась.
В момент выполнения
next_time_statement
переменнаяschedule.transaction_state
должна содержать либоsuccess
(успех), либоfailure
(сбой). Другие значения указывают на внутреннюю ошибкуpgpro_scheduler
.schedule.enable_history
(boolean
)Включает протоколирование всех изменений расписания; при этом фиксируется и время изменения, и имя пользователя, который его внёс. Если добавляется новое задание или изменяется расписание существующего, эта информация сохраняется в таблице
schedule.cron__history
. Если задание удаляется, информация о нём сохраняется в таблицеschedule.cron__deleted
. Если вы впоследствии выключите параметрschedule.enable_history
, уже записанная история изменений не будет удалена.По умолчанию:
false
F.43.4.2. SQL-схема
Для размещения своих внутренних таблиц и функций расширение pgpro_scheduler
использует SQL-схему schedule
. Обращаться к его внутренним таблицам напрямую не следует. Для управления планированием заданий используйте функции, предоставляемые расширением pgpro_scheduler
.
F.43.4.3. Типы SQL
Планировщик pgpro_scheduler
определяет следующие типы, используемые некоторыми функциями pgpro_scheduler
.
F.43.4.3.1. cron_rec
Этот тип содержит информацию о запланированном задании.
CREATE TYPE schedule.cron_rec AS( id integer, -- идентификатор задания node text, -- имя узла, на котором -- оно будет выполняться name text, -- имя задания comments text, -- комментарий к заданию rule jsonb, -- правила расписания commands text[], -- SQL-команды, которые будут выполнены run_as text, -- имя пользователя, запускающего задание owner text, -- имя пользователя-владельца задания start_date timestamptz, -- нижняя граница окна выполнения задания; -- NULL, если дата начала не ограничена end_date timestamptz, -- верхняя граница окна выполнения задания; -- NULL, если дата окончания не ограничена use_same_transaction boolean, -- true, если набор SQL-команд -- будет выполняться в одной -- транзакции last_start_available interval, -- макс. время, на которое может -- откладываться запуск задания, если -- нет доступных рабочих процессов max_run_time interval, -- макс. время выполнения onrollback text, -- SQL-команда, которая будет выполнена -- при сбое основной транзакции max_instances int, -- макс. число экземпляров задания, которые -- могут быть запущены одновременно next_time_statement text, -- SQL-оператор, который будет вычислять -- время следующего запуска active boolean, -- true, если задание запланировано -- успешно broken boolean -- true, если в конфигурации задания есть -- ошибки, препятствующие его -- дальнейшему выполнению );
F.43.4.3.2. cron_job
Этот тип содержит информацию о выполнении определённого задания.
CREATE TYPE schedule.cron_job AS( cron integer, -- идентификатор задания node text, -- имя узла, на котором -- оно будет выполняться scheduled_at timestamptz, -- запланированное время выполнения name text, -- имя задания comments text, -- комментарий к заданию commands text[], -- SQL-команды, которые будут выполнены run_as text, -- имя пользователя, запускающего задание owner text, -- имя пользователя-владельца задания use_same_transaction boolean, -- true, если набор SQL-команд -- будет выполняться в одной -- транзакции started timestamptz, -- время, когда задание было запущено last_start_available timestamp, -- макс. время, до которого может -- откладываться запуск задания, если -- нет доступных рабочих процессов finished timestamptz, -- время, когда задание было завершено max_run_time interval, -- максимальная длительность выполнения onrollback text, -- SQL-команда, которая будет выполнена -- при сбое основной транзакции next_time_statement text, -- SQL-оператор, который будет вычислять -- время следующего запуска max_instances int, -- макс. число одновременно выполняемых -- экземпляров задания status job_status_t, -- состояние задания: working (выполняется), -- done (завершено), error (ошибка) message text -- сообщение об ошибке );
F.43.4.3.3. job_status_t
Тип-перечисление. Может принимать следующие значения:
working
— задание выполняется.done
— выполнение задания завершено.error
— выполнение задания завершилось ошибкой.
F.43.4.3.4. job_at_status_t
Тип-перечисление. Может принимать следующие значения:
submitted
— задание поступило в очередь, но ещё не начинало выполняться.processing
— задание выполняется.done
— выполнение задания завершено.
F.43.4.3.5. timetable_job_type_t
Тип-перечисление. Может принимать следующие значения:
periodical
— запланированное задание.onetime
— одноразовое задание.
F.43.4.3.6. timetable_job_status_t
Тип-перечисление. Может принимать следующие значения:
inprogress
— задание выполняется.done
— выполнение задания завершено.error
— выполнение задания завершилось ошибкой.submitted
— задание поступило в очередь, но ещё не начинало выполняться.
F.43.4.4. Представления
В составе расширения pgpro_scheduler
есть несколько представлений для наблюдения за состоянием выполнения одноразовых заданий:
F.43.4.4.1. Представление job_status
Показывает состояние одноразовых заданий, принадлежащих текущему пользователю.
Таблица F.33. Представление job_status
Имя столбца | Тип столбца | Описание |
---|---|---|
id | bigint | Идентификатор задания. |
node | text | Имя узла, выбранного для выполнения задания. |
name | text | Имя задания. |
comments | text | Комментарии к заданию. |
run_after | timestamp with time zone | Время, после которого должно начаться выполнение задания. |
query | text | SQL-команды, выполняемые заданием. |
params | text[] | Массив параметров для SQL-запроса. |
depends_on | bigint[] | Массив идентификаторов заданий, от которых зависит выполнение данного задания. |
run_as | text | Пользователь (или роль), права которого используются для выполнения задания. |
attempt | bigint | Число попыток выполнения. |
resubmit_limit | bigint | Максимально допустимое число переназначений задания. |
max_wait_interval | interval | Максимальный интервал времени, на который может быть отложено выполнение задания, если в назначенное время все доступные рабочие процессы будут заняты. |
max_duration | interval | Интервал времени, в течение которого может выполняться задание. |
submit_time | timestamp with time zone | Время, когда задание было добавлено в очередь выполнения. |
canceled | boolean | Определяет, было ли задание отменено пользователем. |
start_time | timestamp with time zone | Время, когда началось выполнение задания. |
is_success | boolean |
|
error | text | Сообщение об ошибке. |
done_time | timestamp with time zone | Время, когда завершилось выполнение задания. |
status | job_at_status_t | Состояние задания. За подробностями обратитесь к Подразделу F.43.4.3.4. |
F.43.4.4.2. Представление all_job_status
Показывает состояние всех одноразовых заданий. Для обращения к этому представлению необходимо иметь права суперпользователя.
Таблица F.34. Представление all_job_status
Имя столбца | Тип столбца | Описание |
---|---|---|
id | bigint | Идентификатор задания. |
node | text | Имя узла, выбранного для выполнения задания. |
name | text | Имя задания. |
comments | text | Комментарии к заданию. |
run_after | timestamp with time zone | Время, после которого должно начаться выполнение задания. |
query | text | SQL-команды, выполняемые заданием. |
params | text[] | Массив параметров для SQL-запроса. |
depends_on | bigint[] | Массив идентификаторов заданий, от которых зависит выполнение данного задания. |
run_as | text | Пользователь (или роль), права которого используются для выполнения задания. |
owner | text | Пользователь, создавший задание. |
attempt | bigint | Число попыток выполнения. |
resubmit_limit | bigint | Максимально допустимое число переназначений задания. |
max_wait_interval | interval | Максимальный интервал времени, на который может быть отложено выполнение задания, если в назначенное время все доступные рабочие процессы будут заняты. |
max_duration | interval | Интервал времени, в течение которого может выполняться задание. |
submit_time | timestamp with time zone | Время, когда задание было добавлено в очередь выполнения. |
canceled | boolean | Определяет, было ли задание отменено пользователем. |
start_time | timestamp with time zone | Время, когда началось выполнение задания. |
is_success | boolean |
|
error | text | Сообщение об ошибке. |
done_time | timestamp with time zone | Время, когда завершилось выполнение задания. |
status | job_at_status_t | Состояние задания. За подробностями обратитесь к Подразделу F.43.4.3.4. |
F.43.4.5. Таблицы аудита
В следующих таблицах сохраняются все изменения расписания, если параметр schedule.enable_history
имеет значение true
. Если вы впоследствии отключите schedule.enable_history
, ранее записанная история изменений сохранится.
F.43.4.5.1. Таблица schedule.cron__history
В этой таблице регистрируются изменения в расписании заданий. Когда назначается новое задание или изменяется расписание существующего, в эту таблицу добавляется новая строка, содержащая следующую информацию:
Вся информация о запланированном задании, которая определена в типе данных
cron_rec
. Подробнее типcron_rec
описан в Подразделе F.43.4.3.submitter
— имя пользователя, изменившего расписание.version_id
— уникальный идентификатор, назначаемый каждому изменению в расписании.submit_time
— время изменения расписания.
F.43.4.5.2. Таблица schedule.cron__deleted
В этой таблице регистрируются все задания, удаляемые из расписания:
cron
— идентификатор удалённого задания.submitter
— имя пользователя, удалившего задание.submit_time
— время удаления задания.
F.43.4.6. Функции
pgpro_scheduler
предоставляет два отдельных набора функций для управления заданиями, выполняемыми по расписанию, и одноразовыми заданиями, а также несколько функций общего назначения для включения/отключения расширения pgpro_scheduler
в вашей базе данных и отображения его текущего состояния:
Важно
Для конкретного задания можно использовать только те функции, которые предназначены для данного типа задания.
F.43.4.6.1. Функции общего назначения
Эти функции предназначены для управления расширением pgpro_scheduler
.
-
schedule.enable()
Включает
pgpro_scheduler
для текущего экземпляра Postgres Pro Enterprise.Возвращаемые значения:
true
, если планировщикpgpro_scheduler
включён и готов к использованию.false
, если выполнить команду не удалось.
-
schedule.is_enabled()
Проверяет, работает ли
pgpro_scheduler
.Возвращаемые значения:
true
, если планировщикpgpro_scheduler
включён и готов к использованию.false
, если планировщикpgpro_scheduler
в настоящее время не работает.
-
schedule.disable()
Отключает
pgpro_scheduler
для текущего экземпляра Postgres Pro Enterprise.Возвращаемые значения:
true
, если планировщикpgpro_scheduler
отключён.false
, если выполнить команду не удалось.
-
schedule.start()
Запускает
pgpro_scheduler
для текущей подключённой базы данных.Возвращаемые значения:
true
—pgpro_scheduler
запущен успешно.false
— в случае сбоя команды или еслиpgpro_scheduler
уже запущен.
-
schedule.stop()
Останавливает
pgpro_scheduler
для текущей подключённой базы данных.Возвращаемые значения:
true
—pgpro_scheduler
остановлен.false
— в случае сбоя команды или еслиpgpro_scheduler
не работает.
-
schedule.status()
Возвращает состояние фоновых рабочих процессов
pgpro_scheduler
:pid
— идентификатор фонового рабочего процесса. Если этот идентификатор равенNULL
, фоновый рабочий процесс не работает.database
— имя базы данных, к которой подключён фоновый рабочий процесс.type
— тип фонового рабочего процесса:supervisor
— распределяет запланированные задания между базами данных.database manager
распределяет запланированные задания внутри базы данных.cron job executor
выполняет задания по графику.at job executor
выполняет разовые задания.
-
schedule.version()
Возвращает версию
pgpro_scheduler
.
F.43.4.6.2. Функции для управления планируемыми заданиями
-
schedule.create_job(
options
jsonb
) Создаёт активное задание и возвращает его идентификатор.
Альтернативный синтаксис:
schedule.create_job(
cron
text
,commands
text
[,node
text
]) schedule.create_job(cron
text
,commands
text
[] [,node
text
]) schedule.create_job(dates
timestamp with time zone
,commands
text
[,node
text
]) schedule.create_job(dates
timestamp with time zone
, commandstext[]
[,node
text
]) schedule.create_job(dates
timestamp with time zone[]
,commands
text
[,node
text
]) schedule.create_job(dates
timestamp with time zone[]
,commands
text[]
[,node
text
])Аргументы:
options
— объектjsonb
, определяющий все свойства задания. Если задаётся параметрdata
, никакие другие параметры определять не нужно. Все поддерживаемые ключиjsonb
перечислены в Таблице F.35.Type:
jsonb
cron
— строка в стилеcrontab
, задающая график выполнения.Тип:
text
dates
— точная дата или массив дат для выполнения задания.Тип:
timestamp with time zone
,timestamp with time zone[]
commands
— SQL-операторы, которые будут выполняться. Вы можете передать в этом параметре одну или несколько SQL-команд через точку с запятой либо массив SQL-команд. SQL-команды, передаваемые в массиве, будут выполняться в отдельных транзакциях.Тип:
text
,text[]
node
— имя узла, на котором выполняются запланированные задания. Этот аргумент может понадобиться при планировании заданий в кластере с несколькими ведущими серверами.Тип:
text
Возвращаемые значения:
Идентификатор созданного задания.
Таблица F.35. Ключи
jsonb
, предназначенные для планирования заданийКлюч Тип Описание cron
text
Строка в стиле crontab, определяющая график выполнения. Она может иметь традиционный формат
crontab
с пятью полями или расширенный, с шестью (в нём первое поле содержит секунду). Ключcron
можно комбинировать с ключамиrule
иdates
, но нельзя опустить их все. Также вместо строкиcrontab
можно указать одно из следующих слов, определяющих, когда будет запускаться задание:@every_second
— каждую секунду@hourly
— в начале каждого часа@daily
— в начале каждого дня@midnight
— в начале каждого дня@weekly
— в начале каждой недели@monthly
— в начале каждого месяца@yearly
— в начале каждого года@annually
— в начале каждого года
dates
timestamp with time zone
,timestamp with time zone[]
Точная дата или массив дат, когда должно выполняться запланированное задание. Ключ dates
можно комбинировать с ключамиrule
иcron
, но нельзя опустить их все.rule
jsonb
Объект
jsonb
, определяющий расписание задания. Обязательный ключ, если ключиcron
иdates
не определены. Объектrule
содержит один или несколько из следующих ключей:seconds
— секунды; массив целых чисел в диапазоне [0, 59]minutes
— минуты; массив целых чисел в диапазоне [0, 59]hours
— часы; массив целых чисел в диапазоне [0, 23]days
— дни месяца; массив целых чисел в диапазоне [1, 31]months
— месяцы; массив целых чисел в диапазоне [1, 12]wdays
— дни недели; массив целых чисел в диапазоне [0, 6], где 0 — воскресенье.onstart
— целое значение 0 или 1. Еслиonstart
равняется 1, задание выполняется, только когда включёнpgpro_scheduler
.
commands
text
,text[]
SQL-операторы, которые будут выполняться. Вы можете передать в этом параметре один или несколько SQL-параметров через точку с запятой либо массив SQL-операторов. SQL-операторы, передаваемые в массиве, по умолчанию будут выполняться в отдельных транзакциях. Изменить это поведение позволяет ключ use_same_transaction
.name
text
Необязательное свойство. Имя задания. node
text
Необязательное свойство. Имя узла, на котором выполняются запланированные задания. Этот аргумент может понадобиться при планировании заданий в кластере с несколькими ведущими серверами. comments
text
Необязательные комментарии к запланированному заданию. run_as
text
Необязательное свойство. Пользователь, от имени которого будет выполняться задание. start_date
timestamp with time zone
Необязательное свойство. Начало интервала, в котором возможно выполнение задания. Может содержать NULL
.end_date
timestamp with time zone
Необязательное свойство. Конец интервала, в котором возможно выполнение задания. Может содержать NULL
.use_same_transaction
boolean
Необязательное свойство. Если равняется true
, устанавливает, что SQL-операторы, переданные в массиве, будут выполняться в одной транзакции. По умолчанию:false
last_start_available
interval
Необязательное свойство. Максимальное время, на которое может быть отложено выполнение задания, если в запланированный момент все рабочие процессы оказались заняты. Например, если задать в этом ключе '00:02:34', задание будет ждать выполнения 2 минуты 34 секунды. Если значение этого ключа — NULL
, задание будет ожидать выполнения вечно. Значение по умолчанию:NULL
.max_instances
integer
Необязательное свойство. Максимальное число экземпляров одного задания, которые могут выполняться одновременно. По умолчанию: 1. max_run_time
interval
Необязательное свойство. Максимальное время, в течение которого может выполняться запланированное задание. Если значение этого ключа — NULL
или не установлено, ограничение по времени отсутствует. Значение по умолчанию:NULL
.onrollback
text
Необязательное свойство. SQL-оператор, который будет выполняться при сбое основной транзакции. next_time_statement
text
Необязательное свойство. SQL-оператор, который будет вычислять время следующего запуска задания. Подробнее об этом рассказывается в Подразделе F.43.3.1.3. -
schedule.set_job_attributes(
job_id
integer
,data
jsonb
) Изменяет свойства существующего задания.
Аргументы:
job_id
— идентификатор существующего задания.data
— объектjsonb
с набором изменяемых свойств. Список ключей с описанием их структуры приведён в Таблице F.35.
Возвращаемые значения:
true
— свойства задания изменены успешно.false
— свойства задания не были изменены.
Чтобы изменить свойства задания, необходимо быть его владельцем или иметь права суперпользователя.
-
schedule.set_job_attribute(
job_id
integer
,name
text
,value
text
||anyarray
) Изменяет свойство существующего задания.
Аргументы:
job_id
— идентификатор существующего задания.name
— имя свойства.value
— значение свойства.
Список изменяемых свойств заданий приведён в Таблице F.35. Некоторые свойства представляются массивами и они должны передаваться как массивы. Если передать для свойства значение неверного типа, будет выдано исключение.
Возвращаемые значения:
true
— свойство задания изменено успешно.false
— свойство задания не было изменено.
Чтобы изменить свойства задания, необходимо быть его владельцем или иметь права суперпользователя.
-
schedule.deactivate_job(
job_id
integer
) Деактивирует задание и приостанавливает его последующее выполнение.
Аргументы:
job_id
— идентификатор существующего задания.
Возвращаемые значения:
true
— задание было деактивировано успешно.false
— деактивировать задание не удалось.
-
schedule.activate_job(
job_id
integer
) Активирует задание, в результате чего оно начинает выполняться по расписанию.
Аргументы:
job_id
— идентификатор существующего задания.
Возвращаемые значения:
true
— задание активировано успешно.false
— активировать задание не удалось.
-
schedule.drop_job(
job_id
integer
) Удаляет задание.
Аргументы:
job_id
— идентификатор существующего задания.
Возвращаемые значения:
true
— задание было удалено успешно.false
— задание не было удалено.
-
schedule.get_job(
job_id
integer
) Возвращает информацию об указанном задании.
Аргументы:
job_id
— идентификатор существующего задания.
Возвращаемые значения:
Объект типа
cron_rec
.
Описание типа
cron_rec
можно найти в Подразделе F.43.4.3.-
schedule.get_owned_cron(
username
text
) Получает список заданий, принадлежащих указанному пользователю.
Аргументы:
username
— имя пользователя, может отсутствовать.
Возвращаемые значения:
Набор записей типа
cron_rec
. Эти записи содержат информацию обо всех заданиях, принадлежащих указанному пользователю. Если параметрusername
опущен, подразумевается имя текущего пользователя сеанса. Получать задания, принадлежащие другому пользователю, может только суперпользователь.
Описание типа
cron_rec
можно найти в Подразделе F.43.4.3.-
schedule.get_cron()
Получает список заданий, выполняемых пользователем сеанса.
Возвращаемые значения:
Набор записей типа
cron_rec
. Эти записи содержат информацию обо всех заданиях, выполняемых пользователем сеанса. Получать задания может только суперпользователь.
Описание типа
cron_rec
можно найти в Подразделе F.43.4.3.-
schedule.get_active_jobs(
username
text
) Получает список заданий, в настоящее время выполняемых указанным пользователем.
Аргументы:
username
— имя пользователя, может отсутствовать.
Если параметр
username
опущен, подразумевается имя текущего пользователя сеанса. Получать задания, выполняемые другим пользователем, может только суперпользователь.Возвращаемые значения:
Набор записей типа
cron_job
.
Описание типа
cron_job
можно найти в Подразделе F.43.4.3.-
schedule.get_active_jobs()
Возвращает список заданий, выполняемых в текущий момент. Вызывать эту функцию может только суперпользователь.
Возвращаемые значения:
Набор записей типа
cron_job
.
Описание типа
cron_job
можно найти в Подразделе F.43.4.3.-
schedule.get_log()
Возвращает список всех завершённых заданий. Вызывать эту функцию может только суперпользователь.
Возвращаемые значения:
Набор записей типа
cron_job
.
Описание типа
cron_job
можно найти в Подразделе F.43.4.3.-
schedule.get_user_log(
username
text
) Возвращает список завершённых заданий, выполненных указанным пользователем.
Аргументы:
username
— имя пользователя, может отсутствовать.
Если параметр
username
опущен, подразумевается имя текущего пользователя сеанса. Получать список заданий, выполненных другим пользователем, может только суперпользователь.Возвращаемые значения:
Набор записей типа
cron_job
.
Описание типа
cron_job
можно найти в Подразделе F.43.4.3.-
schedule.clean_log()
Удаляет все записи с информацией о завершённых заданиях. Вызывать эту функцию может только суперпользователь.
Возвращаемые значения:
Число удалённых записей.
-
schedule.nodename()
Возвращает имя текущего узла.
F.43.4.6.3. Функции для управления одноразовыми заданиями
-
schedule.submit_job(
query
text
[параметры...
]) Назначает задания для немедленного или отложенного однократного выполнения. По умолчанию задание назначается для немедленного выполнения и оно может выполняться одновременно с другими запланированными заданиями. Чтобы назначить задание с отсроченным запуском, время запуска можно задать в аргументе
run_after
или передать в аргументеdepends_on
массив идентификаторов некоторых заданий для запуска данного задания сразу после их завершения.Аргументы:
query
— SQL-команды, которые будут выполнены.Тип:
text
params
— массив параметров для SQL-запроса, которые могут подменять нумерованные местозаполнители в аргументеquery
, как например, $1, $2 и т. д. По умолчанию:NULL
Type:
text[]
run_after
— время, после которого начнётся выполнение задания. Если в этом аргументе передаётсяNULL
, задание будет выполнено немедленно. Чтобы отложить запуск задания, также можно задать аргументdepends_on
. По умолчанию:NULL
Тип:
timestamp with time zone
node
— имя узла, на котором будет выполняться задание. По умолчанию:NULL
Тип:
text
max_duration
— максимальное время, в течение которого может выполняться это задание. Если заданное ограничение превышается, задание останавливается принудительно. Если в этом аргументе передаётсяNULL
или он опускается, продолжительность выполнения не ограничивается. По умолчанию:NULL
Тип:
interval
max_wait_interval
— максимальное время, на которое может быть отложено выполнение задания, если в запланированный момент все рабочие процессы оказались заняты. Например, если задать в этом ключе '00:02:34', задание будет ждать выполнения 2 минуты 34 секунды. Если значение этого ключа —NULL
или не определено, задание может ожидать выполнения вечно. По умолчанию:NULL
Тип:
interval
run_as
— пользователь (или роль), права которого используются для выполнения задания. Если вrun_as
передаётсяNULL
, задание выполняется с правами текущего пользователя. Чтобы задать этот аргумент, необходимо иметь права суперпользователя. По умолчанию:NULL
Тип:
text
depends_on
— массив идентификаторов заданий. Созданное задание будет запущено сразу после того, как будут завершены все указанные задания. Этот аргумент является альтернативой параметруrun_after
. По умолчанию:NULL
Тип:
bigint[]
name
— имя задания. По умолчанию:NULL
Тип:
text
comments
— комментарии к заданию.Тип:
text
resubmit_limit
— максимальное число раз, которое задание может назначаться повторно. За подробностями обратитесь к описанию функцииschedule.resubmit()
. По умолчанию: 100Тип:
bigint
Возвращаемые значения:
Идентификатор созданного задания.
Тип:
bigint
-
schedule.get_self_id()
Возвращает идентификатор задания, в контексте выполнения которого вызывается эта функция. Возвращаемый идентификатор имеет тип
bigint
. Эта функция должна вызываться в запросе, задаваемом в параметреquery
функцииschedule.submit_job()
. Если вызвать её иначе, возникает исключение.Возвращаемые значения:
Идентификатор задания.
-
schedule.cancel_job(
job_id
bigint
) Отменяет все последующие запуски указанного задания. Если задание уже выполняется, оно не будет прервано, но повторно назначить его будет нельзя. Чтобы вызывать эту функцию, необходимо быть владельцем задания или иметь права суперпользователя.
Аргументы:
job_id
— идентификатор задания, которое нужно отменить.
Возвращаемые значения:
true
, если операция завершена успешно.false
, если выполнить операцию не удалось.
-
schedule.resubmit(
run_after
interval
defaultNULL
) Задаёт время запуска для следующего выполнения задания, без прерывания текущего выполнения. Эта функция должна вызываться внутри запроса, задаваемого в аргументе
query
функцииschedule.submit_job()
. В другом контексте она выдаёт исключение. Если эта функция вызывается несколько раз в процессе выполнения одного задания, решающим будет последний вызов функции.Аргументы:
run_after
— интервал времени, после которого задание будет повторно назначено для выполнения. Если указан положительный временной интервал меньше секунды, то он округляется до 1 секунды. Интервалы более 1 секунды округляются до целых значений. Если передаётся 0, задание перезапускается сразу после выполнения. По умолчанию: 1 секундаТип:
interval
Возвращаемые значения:
Число секунд, после которого задание будет повторно назначено для выполнения.
F.43.4.6.4. Функции для управления планируемыми и одноразовыми заданиями
Таблица F.36. Столбцы schedule.timetable
Имя столбца | Тип столбца | Описание |
---|---|---|
id | bigint | Идентификатор задания, уникальный среди заданий этого типа. |
type | timetable_job_type_t | Тип задания. За подробностями обратитесь к Подразделу F.43.4.3.5. |
node | text | Имя узла, выбранного для выполнения задания. |
name | text | Имя задания. |
comments | text | Комментарии к заданию. |
commands | text[] | Массив SQL-команд, выполняемых заданием. |
scheduled_at | timestamp with time zone | Время, на которое запланировано выполнение задания. |
start_time | timestamp with time zone | Время, когда началось выполнение задания. |
done_time | timestamp with time zone | Время, когда завершилось выполнение задания. |
status | timetable_job_status_t | Состояние задания. За подробностями обратитесь к Подразделу F.43.4.3.6. |
error | text | Сообщение об ошибке. |
F.43.5. Авторы
Postgres Professional, Москва, Россия