F.41. pgpro_scheduler
Пред. НаверхПриложение F. Дополнительно поставляемые модулиНачало След.

F.41. pgpro_scheduler

F.41.1. Установка и подготовка
F.41.2. Конфигурирование
F.41.3. Использование
F.41.4. Справка
F.41.5. Авторы

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.41.1. Установка и подготовка

Расширение pgpro_scheduler включено в состав Postgres Pro Enterprise. Установив Postgres Pro Enterprise, выполните следующие действия, чтобы подготовить pgpro_scheduler к работе:

  1. Добавьте pgpro_scheduler в параметр shared_preload_libraries в файле postgresql.conf: 

    shared_preload_libraries = 'pgpro_scheduler'

  2. Создайте расширение pgpro_scheduler, выполнив следующий запрос: 

    CREATE EXTENSION pgpro_scheduler;

    Расширение pgpro_scheduler необходимо создать в каждой базе данных, где вы планируете его использовать.

Завершив установку и подготовку, настройте pgpro_scheduler в вашей базе данных.

F.41.2. Конфигурирование

Для настройки pgpro_scheduler необходимо иметь права суперпользователя.

Чтобы настроить pgpro_scheduler, измените следующие параметры в файле postgresql.conf:

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

    schedule.database = 'база1,база2'

    Это можно не делать, если pgpro_scheduler используется в кластере multimaster.

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

    schedule.max_workers = 5

  3. Дополнительно можно задать число рабочих процессов, доступных для одного выполнения задания:

    schedule.max_parallel_workers = 3

    По умолчанию для одноразовых заданий выделяются два процесса. Они не учитываются в ограничении schedule.max_workers. Таким образом, одноразовые задания могут выполняться параллельно с заданиями, планируемыми по графику, даже если все процессы в количестве schedule.max_workers заняты.

  4. Выполните 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 SET schedule.database = 'database1,database2';
ALTER DATABASE database1 SET schedule.max_workers = 5;
ALTER DATABASE database2 SET schedule.max_workers = 3;
ALTER SYSTEM SET schedule.max_parallel_workers = 3;
SELECT pg_reload_conf();

Настроив pgpro_scheduler, включите его в вашей системе так: 

SELECT schedule.enable();

Если эта функция возвратит true, значит pgpro_scheduler готов к использованию, и вы можете приступать к планированию заданий, как описано в Подразделе F.41.3.1 и Подразделе F.41.3.2.

Примечание

Если перезапустить сервер, pgpro_scheduler по умолчанию не будет запускаться автоматически. Чтобы поменять это поведение, присвойте параметру schedule.auto_enabled значение on.

См. также

Подраздел F.41.4.1

F.41.3. Использование

F.41.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" }');
F.41.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.41.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.41.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.41.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.41.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.41.4.6.3.

F.41.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.41.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.41.4.6.

F.41.3.5. Аудит изменений расписания

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

По умолчанию pgpro_scheduler не сохраняет информацию об изменениях в расписании заданий. Чтобы включить эту возможность, установите для параметра schedule.enable_history значение true. Когда этот параметр включён, pgpro_scheduler сохраняет изменения расписания в таблице schedule.cron__history, а информацию обо всех удалённых заданиях записывает в таблицу schedule.cron__deleted. Сохранённая в этих таблицах история никогда не удаляется, так что суперпользователь может пересмотреть изменения в расписании, внесённые любым пользователем в любой момент времени.

Подробнее сохраняемая информация описывается в Подразделе F.41.4.5.

F.41.3.6. Планирование заданий в кластере multimaster

Используя pgpro_scheduler, вы можете управлять заданиями по расписанию и одноразовыми заданиями в кластере, настроенном с применением Раздел F.31. pgpro_scheduler может управлять заданиями только на том узле, где он установлен. Таким образом, вы должны установить и включить pgpro_scheduler на всех узлах, где вы хотите планировать задания. Экземпляры pgpro_scheduler на разных узлах будут управлять заданиями независимо, но выполненные задания будут реплицироваться на другие узлы.

Даже если вы намерены планировать задания только на одном узле, pgpro_scheduler рекомендуется развернуть на нескольких узлах. В этом случае, если узел с запланированными заданиями откажет, эти задания возьмёт на себя другой экземпляр pgpro_scheduler. Если pgpro_scheduler работает на нескольких узлах, для выполнения задания выбирается узел с наименьшим идентификатором. Шаблон именования идентификаторов определяется переменной конфигурации schedule.nodename.

F.41.4. Справка

F.41.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. Имена баз данных должны разделяться запятыми.

Если pgpro_scheduler работает в кластере multimaster, имя единственной базы данных считывается из переменной multimaster.conn_strings.

По умолчанию: пустая строка.

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.node_id . Например, если multimaster.node_id = 3, переменная schedule.nodename получает значение mtm-node-3. Однако если вы явно зададите переменную schedule.nodename в файле postgresql.conf или воспользовавшись командой ALTER, pgpro_scheduler будет использовать заданное значение, не учитывая переменную multimaster.node_id.

По умолчанию: master.

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.41.4.2. SQL-схема

Для размещения своих внутренних таблиц и функций расширение pgpro_scheduler использует SQL-схему schedule. Обращаться к его внутренним таблицам напрямую не следует. Для управления планированием заданий используйте функции, предоставляемые расширением pgpro_scheduler.

F.41.4.3. Типы SQL

Планировщик pgpro_scheduler определяет следующие типы, используемые некоторыми функциями pgpro_scheduler.

F.41.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.41.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.41.4.3.3. job_status_t

Тип-перечисление. Может принимать следующие значения:

  • working — задание выполняется.

  • done — выполнение задания завершено.

  • error — выполнение задания завершилось ошибкой.

F.41.4.3.4. job_at_status_t

Тип-перечисление. Может принимать следующие значения:

  • submitted — задание поступило в очередь, но ещё не начинало выполняться.

  • processing — задание выполняется.

  • done — выполнение задания завершено.

F.41.4.4. Представления

В составе расширения pgpro_scheduler есть несколько представлений для наблюдения за состоянием выполнения одноразовых заданий:

F.41.4.4.1. Представление job_status

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

Таблица F.28. Представление job_status

Имя столбцаТип столбцаОписание
idbigintИдентификатор задания.
nodetextИмя узла, на котором выполняется задание.
nametextИмя задания.
commentstextКомментарии к заданию.
run_aftertimestamp with time zoneВремя, после которого должно начаться выполнение задания.
querytextSQL-команды, выполняемые заданием.
paramstext[]Массив параметров для SQL-запроса.
depends_onbigint[]Массив идентификаторов заданий, от которых зависит выполнение данного задания.
run_astextПользователь (или роль), права которого используются для выполнения задания.
attemptbigintЧисло попыток выполнения.
resubmit_limitbigintМаксимально допустимое число переназначений задания.
max_wait_intervalintervalМаксимальный интервал времени, на который может быть отложено выполнение задания, если в назначенное время все доступные рабочие процессы будут заняты.
max_durationintervalИнтервал времени, в течение которого может выполняться задание.
submit_timetimestamp with time zoneВремя, когда задание было добавлено в очередь выполнения.
canceledbooleanОпределяет, было ли задание отменено пользователем.
start_timetimestamp with time zoneВремя начала выполнения задания.
is_successboolean

  • true — задание было выполнено успешно.

  • false — выполнение задания завершилось с ошибками.

errortextСообщение об ошибке.
done_timetimestamp with time zoneВремя, когда завершилось выполнение задания.
statusjob_at_status_tСостояние задания. За подробностями обратитесь к Подразделу F.41.4.3.4.

F.41.4.4.2. Представление all_job_status

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

Таблица F.29. Представление all_job_status

Имя столбцаТип столбцаОписание
idbigintИдентификатор задания.
nodetextИмя узла, на котором выполняется задание.
nametextИмя задания.
commentstextКомментарии к заданию.
run_aftertimestamp with time zoneВремя, после которого должно начаться выполнение задания.
querytextSQL-команды, выполняемые заданием.
paramstext[]Массив параметров для SQL-запроса.
depends_onbigint[]Массив идентификаторов заданий, от которых зависит выполнение данного задания.
run_astextПользователь (или роль), права которого используются для выполнения задания.
ownertextПользователь, создавший задание.
attemptbigintЧисло попыток выполнения.
resubmit_limitbigintМаксимально допустимое число переназначений задания.
max_wait_intervalintervalМаксимальный интервал времени, на который может быть отложено выполнение задания, если в назначенное время все доступные рабочие процессы будут заняты.
max_durationintervalИнтервал времени, в течение которого может выполняться задание.
submit_timetimestamp with time zoneВремя, когда задание было добавлено в очередь выполнения.
canceledbooleanОпределяет, было ли задание отменено пользователем.
start_timetimestamp with time zoneВремя начала выполнения задания.
is_successboolean

  • true — задание было выполнено успешно.

  • false — выполнение задания завершилось с ошибками.

errortextСообщение об ошибке.
done_timetimestamp with time zoneВремя, когда завершилось выполнение задания.
statusjob_at_status_tСостояние задания. За подробностями обратитесь к Подразделу F.41.4.3.4.

F.41.4.5. Таблицы аудита

В следующих таблицах сохраняются все изменения расписания, если параметр schedule.enable_history имеет значение true. Если вы впоследствии отключите schedule.enable_history, ранее записанная история изменений сохранится.

F.41.4.5.1. Таблица schedule.cron__history

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

  • Вся информация о запланированном задании, которая определена в типе данных cron_rec. Подробнее тип cron_rec описан в Подразделе F.41.4.3.

  • submitter — имя пользователя, изменившего расписание.

  • version_id — уникальный идентификатор, назначаемый каждому изменению в расписании.

  • submit_time — время изменения расписания.

F.41.4.5.2. Таблица schedule.cron__deleted

В этой таблице регистрируются все задания, удаляемые из расписания:

  • cron — идентификатор удалённого задания.

  • submitter — имя пользователя, удалившего задание.

  • submit_time — время удаления задания.

F.41.4.6. Функции

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

Важно

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

F.41.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.41.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, commands text[] [, 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.30.

    Type: jsonb

  • cron — строка в стиле crontab, задающая график выполнения.

    Тип: text

  • dates — точная дата или массив дат для выполнения задания.

    Тип: timestamp with time zone, timestamp with time zone[]

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

    Тип: text, text[]

  • node — имя узла, на котором выполняются запланированные задания. Этот аргумент может понадобиться при планировании заданий в кластере с несколькими ведущими серверами.

    Тип: text

Возвращаемые значения:

  • Идентификатор созданного задания.

Таблица F.30. Ключи jsonb, предназначенные для планирования заданий

КлючТипОписание
crontext

Строка в стиле crontab, определяющая график выполнения. Она может иметь традиционный формат crontab с пятью полями или расширенный, с шестью (в нём первое поле содержит секунду). Ключ cron можно комбинировать с ключами rule и dates, но нельзя опустить их все. Также вместо строки crontab можно указать одно из следующих слов, определяющих, когда будет запускаться задание:

  • @every_second — каждую секунду

  • @hourly — в начале каждого часа

  • @daily — в начале каждого дня

  • @midnight — в начале каждого дня

  • @weekly — в начале каждой недели

  • @monthly — в начале каждого месяца

  • @yearly — в начале каждого года

  • @annually — в начале каждого года

datestimestamp with time zone, timestamp with time zone[]Точная дата или массив дат, когда должно выполняться запланированное задание. Ключ dates можно комбинировать с ключами rule и cron, но нельзя опустить их все.
rulejsonb

Объект 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.

commandstext, text[]SQL-операторы, которые будут выполняться. Вы можете передать в этом параметре один или несколько SQL-параметров через точку с запятой либо массив SQL-операторов. SQL-операторы, передаваемые в массиве, по умолчанию будут выполняться в отдельных транзакциях. Изменить это поведение позволяет ключ use_same_transaction.
nametextНеобязательное свойство. Имя задания.
nodetextНеобязательное свойство. Имя узла, на котором выполняются запланированные задания. Этот аргумент может понадобиться при планировании заданий в кластере с несколькими ведущими серверами.
commentstextНеобязательные комментарии к запланированному заданию.
run_astextНеобязательное свойство. Пользователь, от имени которого будет выполняться задание.
start_datetimestamp with time zoneНеобязательное свойство. Начало интервала, в котором возможно выполнение задания. Может содержать NULL.
end_datetimestamp with time zoneНеобязательное свойство. Конец интервала, в котором возможно выполнение задания. Может содержать NULL.
use_same_transactionbooleanНеобязательное свойство. Если равняется true, устанавливает, что SQL-операторы, переданные в массиве, будут выполняться в одной транзакции. По умолчанию: false
last_start_availableintervalНеобязательное свойство. Максимальное время, на которое может быть отложено выполнение задания, если в запланированный момент все рабочие процессы оказались заняты. Например, если задать в этом ключе '00:02:34', задание будет ждать выполнения 2 минуты 34 секунды. Если значение этого ключа — NULL, задание будет ожидать выполнения вечно. Значение по умолчанию: NULL.
max_instancesintegerНеобязательное свойство. Максимальное число экземпляров одного задания, которые могут выполняться одновременно. По умолчанию: 1.
max_run_timeintervalНеобязательное свойство. Максимальное время, в течение которого может выполняться запланированное задание. Если значение этого ключа — NULL или не установлено, ограничение по времени отсутствует. Значение по умолчанию: NULL.
onrollbacktextНеобязательное свойство. SQL-оператор, который будет выполняться при сбое основной транзакции.
next_time_statementtextНеобязательное свойство. SQL-оператор, который будет вычислять время следующего запуска задания. Подробнее об этом рассказывается в Подразделе F.41.3.1.3.

schedule.set_job_attributes(job_id integer, data jsonb)

Изменяет свойства существующего задания.

Аргументы:

  • job_id — идентификатор существующего задания.

  • data — объект jsonb с набором изменяемых свойств. Список ключей с описанием их структуры приведён в Таблице F.30.

Возвращаемые значения:

  • true — свойства задания изменены успешно.

  • false — свойства задания не были изменены.

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

schedule.set_job_attribute(job_id integer, name text, value text || anyarray)

Изменяет свойство существующего задания.

Аргументы:

  • job_id — идентификатор существующего задания.

  • name — имя свойства.

  • value — значение свойства.

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

Возвращаемые значения:

  • 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.41.4.3.

schedule.get_owned_cron(username text)

Получает список заданий, принадлежащих указанному пользователю.

Аргументы:

  • username — имя пользователя, может отсутствовать.

Возвращаемые значения:

  • Набор записей типа cron_rec. Эти записи содержат информацию обо всех заданиях, принадлежащих указанному пользователю. Если параметр username опущен, подразумевается имя текущего пользователя сеанса. Получать задания, принадлежащие другому пользователю, может только суперпользователь.

Описание типа cron_rec можно найти в Подразделе F.41.4.3.

schedule.get_cron(username text)

Получает список заданий, выполняемых указанным пользователем.

Аргументы:

  • username — имя пользователя, может отсутствовать.

Возвращаемые значения:

  • Набор записей типа cron_rec. Эти записи содержат информацию обо всех заданиях, выполняемых пользователем. Если параметр username опущен, подразумевается имя текущего пользователя сеанса. Получать задания, выполняемые другим пользователем, может только суперпользователь.

Описание типа cron_rec можно найти в Подразделе F.41.4.3.

schedule.get_active_jobs(username text)

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

Аргументы:

  • username — имя пользователя, может отсутствовать.

Если параметр username опущен, подразумевается имя текущего пользователя сеанса. Получать задания, выполняемые другим пользователем, может только суперпользователь.

Возвращаемые значения:

  • Набор записей типа cron_job.

Описание типа cron_job можно найти в Подразделе F.41.4.3.

schedule.get_active_jobs()

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

Возвращаемые значения:

  • Набор записей типа cron_job.

Описание типа cron_job можно найти в Подразделе F.41.4.3.

schedule.get_log()

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

Возвращаемые значения:

  • Набор записей типа cron_job.

Описание типа cron_job можно найти в Подразделе F.41.4.3.

schedule.get_user_log(username text)

Возвращает список завершённых заданий, выполненных указанным пользователем.

Аргументы:

  • username — имя пользователя, может отсутствовать.

Если параметр username опущен, подразумевается имя текущего пользователя сеанса. Получать список заданий, выполненных другим пользователем, может только суперпользователь.

Возвращаемые значения:

  • Набор записей типа cron_job.

Описание типа cron_job можно найти в Подразделе F.41.4.3.

schedule.clean_log()

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

Возвращаемые значения:

  • Число удалённых записей.

schedule.nodename()

Возвращает имя текущего узла.

F.41.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 default NULL)

Задаёт время запуска для следующего выполнения задания, без прерывания текущего выполнения. Эта функция должна вызываться внутри запроса, задаваемого в аргументе query функции schedule.submit_job(). В другом контексте она выдаёт исключение. Если эта функция вызывается несколько раз в процессе выполнения одного задания, решающим будет последний вызов функции.

Аргументы:

  • run_after — интервал времени, после которого задание будет повторно назначено для выполнения. По умолчанию: 1 сек.

    Тип: interval

Возвращаемые значения:

  • Число секунд, после которого задание будет повторно назначено для выполнения.

F.41.5. Авторы

Postgres Professional, Москва, Россия

Пред. Начало След.
F.40. pg_prewarm Наверх F.42. pg_query_state