F.44. pg_variables

F.44.1. Введение

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

Учтите, что этот модуль не поддерживает транзакции и точки сохранения. Например:

SELECT pgv_set_int('vars', 'int1', 101);
BEGIN;
SELECT pgv_set_int('vars', 'int2', 102);
ROLLBACK;

SELECT * FROM pgv_list() order by package, name;
 package | name
---------+------
 vars    | int1
 vars    | int2
(2 rows)

F.44.2. Функции модуля

Реализованные в модуле pg_variables функции представлены в следующих таблицах. Этот модуль поддерживает скалярные типы и записи.

Для функций pgv_get_() требуется, чтобы существовал пакет и указанная переменная. Поэтому перед использованием функций pgv_get_() необходимо установить переменную с помощью функций pgv_set_().

Если пакет не существует, выдаётся следующая ошибка:

SELECT pgv_get_int('vars', 'int1');
ERROR:  unrecognized package "vars"

Если переменная не существует, вы получите следующую ошибку:

SELECT pgv_get_int('vars', 'int1');
ERROR:  unrecognized variable "int1"

Функции pgv_get_() проверяют тип переменной. Если тип переменной не соответствует типу функции, выдаётся ошибка:

SELECT pgv_get_text('vars', 'int1');
ERROR:  variable "int1" requires "integer" value

F.44.2.1. Целочисленные переменные

ФункцияВозвращает
pgv_set_int(package text, name text, value int)void
pgv_get_int(package text, name text, strict bool default true)int

F.44.2.2. Текстовые переменные

ФункцияВозвращает
pgv_set_text(package text, name text, value text)void
pgv_get_text(package text, name text, strict bool default true)text

F.44.2.3. Числовые переменные

ФункцияВозвращает
pgv_set_numeric(package text, name text, value numeric)void
pgv_get_numeric(package text, name text, strict bool default true)numeric

F.44.2.4. Переменные даты/времени

ФункцияВозвращает
pgv_set_timestamp(package text, name text, value timestamp)void
pgv_get_timestamp(package text, name text, strict bool default true)timestamp

F.44.2.5. Переменные даты/времени с часовым поясом

ФункцияВозвращает
pgv_set_timestamptz(package text, name text, value timestamptz)void
pgv_get_timestamptz(package text, name text, strict bool default true)timestamptz

F.44.2.6. Переменные даты

ФункцияВозвращает
pgv_set_date(package text, name text, value date)void
pgv_get_date(package text, name text, strict bool default true)date

F.44.2.7. Переменные Jsonb

ФункцияВозвращает
pgv_set_jsonb(package text, name text, value jsonb)void
pgv_get_jsonb(package text, name text, strict bool default true)jsonb

F.44.2.8. Записи

Следующие функции этого модуля предназначены для работы с наборами типа запись.

Для использования функций pgv_update(), pgv_delete() и pgv_select() должны существовать пакет и указанная переменная, в противном случае возникает ошибка. Поэтому перед использованием этих функций необходимо установить переменную с помощью функции pgv_insert().

Функции pgv_update(), pgv_delete() и pgv_select() проверяют тип переменной. Если типом переменной оказывается не тип записи, выдаётся ошибка.

ФункцияВозвращаетОписание
pgv_insert(package text, name text, r record)voidВставляет запись в набор переменных. Если указанный набор и переменная не существуют, они будут созданы. Первый столбец записи r будет считаться первичным ключом. Если будет найдена запись с таким же первичным ключом, возникнет ошибка. Так же возникнет ошибка, если у набора переменных окажется другая структура.
pgv_update(package text, name text, r record)booleanИзменяет запись с соответствующим первичным ключом (он задаётся в первом столбце r). Возвращает true, если запись была найдена. Если этот набор переменных имеет другую структуру, выдаётся ошибка.
pgv_delete(package text, name text, value anynonarray)booleanУдаляет запись с соответствующим первичным ключом (он задаётся в первом столбце r). Возвращает true, если запись была найдена.
pgv_select(package text, name text)set of recordВозвращает записи из набора переменных.
pgv_select(package text, name text, value anynonarray)recordВозвращает записи из набора переменных с соответствующими первичными ключами (первичный ключ задаётся в первом столбце r).
pgv_select(package text, name text, value anyarray)set of recordВозвращает записи из набора переменных с соответствующими первичными ключами (первичный ключ задаётся в первом столбце r).

F.44.2.9. Функции разного назначения

ФункцияВозвращаетОписание
pgv_exists(package text, name text)boolВозвращает true, если существует указанный пакет и переменная.
pgv_remove(package text, name text)voidУдаляет переменную с соответствующим именем. Указанный пакет и переменная должны существовать, иначе будет выдана ошибка.
pgv_remove(package text)voidУдаляет пакет с заданным именем и все переменные пакета. Указанный пакет должен существовать, иначе будет выдана ошибка.
pgv_free()voidУдаляет все пакеты и переменные.
pgv_list()table(package text, name text)Возвращает список пакетов и связанных с ними переменных.
pgv_stats()table(package text, used_memory bigint)Показывает список задействованных пакетов и объём занимаемой ими памяти (в байтах).

Заметьте, что pgv_stats() работает только в Postgres Pro 9.6 и новее.

F.44.3. Примеры

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

SELECT pgv_set_int('vars', 'int1', 101);
SELECT pgv_set_int('vars', 'int2', 102);

SELECT pgv_get_int('vars', 'int1');
 pgv_get_int 
-------------
         101
(1 row)

SELECT pgv_get_int('vars', 'int2');
 pgv_get_int 
-------------
         102
(1 row)

Допустим, у нас есть таблица tab:

CREATE TABLE tab (id int, t varchar);
INSERT INTO tab VALUES (0, 'str00'), (1, 'str11');

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

SELECT pgv_insert('vars', 'r1', tab) FROM tab;

SELECT pgv_select('vars', 'r1');
 pgv_select
------------
 (1,str11)
 (0,str00)
(2 rows)

SELECT pgv_select('vars', 'r1', 1);
 pgv_select
------------
 (1,str11)
(1 row)

SELECT pgv_select('vars', 'r1', 0);
 pgv_select
------------
 (0,str00)
(1 row)

SELECT pgv_select('vars', 'r1', ARRAY[1, 0]);
 pgv_select
------------
 (1,str11)
 (0,str00)
(2 rows)

SELECT pgv_delete('vars', 'r1', 1);

SELECT pgv_select('vars', 'r1');
 pgv_select
------------
 (0,str00)
(1 row)

Вы можете получить список пакетов и переменных:

SELECT * FROM pgv_list() order by package, name;
 package | name 
---------+------
 vars    | int1
 vars    | int2
 vars    | r1
(3 rows)

И получить объём занятой ими памяти:

SELECT * FROM pgv_stats() order by package;
 package | used_memory
---------+-------------
 vars    |       16736
(1 row)

Вы можете удалять переменные или целые пакеты:

SELECT pgv_remove('vars', 'int1');
SELECT pgv_remove('vars');

Вы можете удалить все пакеты и переменные:

SELECT pgv_free();