Name	Name	Last commit message	Last commit date
Latest commit History 14 Commits
src	src
test	test
web	web
Makefile	Makefile
README.md	README.md
internals.md	internals.md
pgpro_scheduler--1.0.sql	pgpro_scheduler--1.0.sql
pgpro_scheduler.control	pgpro_scheduler.control

pgpro_scheduler - расширение PostgreSQL для управления расписанием задач

pgpro_scheduler это планировщик задач для СУБД PostgreSQL, который позволяет планировать выполнение задач в базе и контролировать их исполнение.

Задачи это наборы SQL команд. Расписание выполнения задач задается либо строкой cron, либо указанием конкретных дат запуска, либо JSON объектом, в котором указывается в какие дни часы и минуты задача должна быть запущена. Возможна комбинация методов описания расписания.

Каждая задача имеет возможность для вычисления времени следующего своего запуска. Набор SQL команд в задаче может обрабатываться в одной транзакции или же каждая команда может использовать свою индивидуальную транзакцию. Имеется возможность задания SQL команды, которая будет выполняться в случае аварийного завершения транзакции.

Installation

pgpro_scheduler это расширение PostgreSQL и не требует никаких специальных пререквизитов.

Перед сборкой расширения из исходного кода убедитесь, что переменная окружения PATH содержит путь к команде pg_config. Так же убедитесь, что у вас установлена версия PostgresSQL для разработчиков или PostgreSQL собран из исходного кода.

Процедура установки выглядит следующим образом:

$ cd pgpro_scheduler
$ make USE_PGXS=1
$ sudo make USE_PGXS=1 install
$ psql <DBNAME> -c "CREATE EXTNESION pgpro_scheduler"

Конфигурация

Расширение определяет ряд переменных в PostgreSQL (GUC), которые позволяют управлять его конфигурацией.

schedule.enable - двоичная переменная, которая определяет разрешено ли выполнение расширения. По умолчанию: false.
schedule.database - строковая переменная, указывает с какими базам может работать планировщик. Что бы указать несколько баз, нужно перечислить их имена через запятую. По умолчанию - пустая строка.
schedule.nodename - строковая переменная, содержит название узла. По умолчанию - master. Если расширение используется на одной машине, то переменная не имеет смысла.
schedule.max_workers - целочисленная переменная, содержит максимальное количество одновременно работающих задач для одной базы. По умолчанию - 2.
schedule.transaction_state - строковая переменная, устанавливается расширением в процессе работы. По умолчанию - undefined. Переменная используется для определения статуса завершения транзакции при вычислении следующего времени выполнения задачи. Возможные значения:
- success - транзакция завершилась успешно
- failure - транзакция завершилась аварийно
- running - транзакция в процессе исполнения
- undefined - транзакция не началась
Последние два значения не должны попадать в процедуру определения следующего значения. Это будет означать какую-то внутреннюю ошибку в работе планировщика.

Управление

Управление работой планировщика задач осуществляется через переменные PostgreSQL, которые описаны в предыдущем разделе.

Например, у вас существует свежая инсталляция PostgreSQL с установленным расширением планировщика. И вам требуется запустить планировщик на двух базах database1 и database2. При этом вы хотите что бы планировщик для базы database1 мог исполнять 5 задач одновременно, а для базы database2 - 3.

В $DATADIR/postgresql.conf должна присутствовать строка:

shared_preload_libraries = 'pgpro_scheduler'

Далее в psql введите следующие команды:

# ALTER SYSTEM SET schedule.enable = true;
# ALTER SYSTEM SET schedule.database = 'database1,database2';
# ALTER DATABASE database1 SET schedule.max_workers = 5;
# ALTER DATABASE database2 SET schedule.max_workers = 3;
# SELECT pg_reload_conf();

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

Пример записей в $DATADIR/postgresql.conf, если количество одновременно исполняемых задач в обоих базах одинаково:

shared_preload_libraries = 'pgpro_scheduler'
schedule.enable = on
schedule.database = 'database1,database2'
schedule.max_workers = 5

Планировщик задач работает с помощью Background Worker'ов. Поэтому должно быть правильно установлено значение переменной max_worker_processes. Минимальное значение переменной может быть расcчитано по следующей формуле:

N_min = 1 + N_databases + MAX_WORKERS₁ + ... + MAX_WORKERS_n

Где:

N_min - это минимальное значение переменной, которое требуется для работы конфигурации. Имейте в виду, что Background Workes'ы могут требоваться для работы других систем, например, параллельных запросов.
N_databases - это количество баз данных, для которых запускается планировщик.
MAX_WORKERS_n - это значение переменной schedule.max_workers в контексте каждой базы данных, для которой запускается планировщик.

SQL Схема

При установке расширения создается SQL схема schedule. Все функции для работы с планировщиком и служебные таблицы создаются в ней.

Прямой доступ к внутренним таблицам запрещен. Все управление осуществляется набором SQL функций, о котором будет рассказано далее.

SQL Типы

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

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 timestamp,   -- нижняя граница временного периода, во время
							-- которого допускается выполнение задачи,
							-- граница считается открытой, если значение NULL
	end_date timestamp,     -- верхняя граница временного периода, во время
							-- которого допускается выполнение задачи,
							-- граница считается открытой, если значение NULL
	use_same_transaction boolean,   -- если true, то набор команд будет 
									-- выполняться в одной транзакции
	last_start_available interval,  -- максимальное время, на которое может 
									-- быть отложен запуск задачи, если 
									-- нет свободных workers для ее
									-- выполнения во время по расписанию
	max_instances int,		-- максимальное количество копий задачи, которые
							-- могут быть запущенны одновременно
	max_run_time interval,  -- максимальное время выполнения задачи
	onrollback text,        -- SQL команда, которая будет выполнена в случае
							-- аварийного завершения транзакции
	next_time_statement text,   -- SQL команда, которая будет выполнена 
								-- после завершения основного набора SQL 
								-- команд, которая возвращает следующее
								-- время выполнения задачи
	active boolean,         -- true - если задача доступна для запуску по 
							-- расписанию
	broken boolean          -- true - задача имеет ошибки в конфигурации,
							-- которые не позволяют ее выполнять далее
);

###cron_job

Тип используется для информации о конкретном исполнении задачи.

CREATE TYPE schedule.cron_job AS(
	cron integer,           -- идентификатор задачи
	node text,              -- имя узла, на котором она выполняться
	scheduled_at timestamp, -- запланированное время выполнения
	name text,              -- имя задачи
	comments text,          -- комментарий к задаче
	commands text[],        -- sql команды для выполнения
	run_as text,            -- имя пользователя, с правами которого будет
							-- выполнен набор команд
	owner text,             -- имя пользователя, создавшего задачу
	use_same_transaction boolean,	-- если true, то набор команд 
							-- выполняется в одной транзакции
	started timestamp,      -- время, когда задача была запущена
	last_start_available timestamp,	-- время, до которого задача должна
							-- быть запущена
	finished timestamp,     -- время, когда задача была завершена
	max_run_time interval,  -- время, за которое задача должна выполнится,
							-- иначе она будет аварийно остановлена
	max_instances int,		-- количество возможных одновременных сущностей
							-- задачи, которые могут работать одновременно
	onrollback text,        -- SQL, который будет выполнен при аварийном 
							-- завершении транзакции
	next_time_statement text,	-- SQL для вычисления следующего времени запуска
	status text,			-- статус задачи: working, done, error 
	message text			-- сообщение, это может быть сообщение об
							-- ошибке, так и какая-то служебная информация
);