F.44. pg_variables

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

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

Примечание

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

postgres=# SELECT pgv_set('vars', 'int1', 101);
BEGIN;
postgres=# SELECT pgv_set('vars', 'int2', 102);
ROLLBACK;

postgres=# SELECT * FROM pgv_list() ORDER BY package, name;
 package | name
---------+------
 vars    | int1
 vars    | int2
(2 rows)

F.44.2. Установка

Расширение pg_variables включено в состав Postgres Pro. Установив Postgres Pro, вы должны выполнить команду CREATE EXTENSION, чтобы подготовить pg_variables к работе, следующим образом:

CREATE EXTENSION pg_variables;

F.44.3. Функции

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

F.44.3.1. Скалярные переменные

Следующие функции поддерживают скалярные переменные:

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

Для функции pgv_get() вы должны сначала создать пакет и переменную, воспользовавшись функцией pgv_set(). Если указанный пакет или переменная не существуют, происходит ошибка:

postgres=# SELECT pgv_get('vars', 'int1');
ERROR:  unrecognized package "vars"
postgres=# SELECT pgv_get('vars', 'int1');
ERROR:  unrecognized variable "int1"

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

SELECT pgv_get('vars', 'int1', NULL::text);
ERROR:  variable "int1" requires "integer" value

F.44.3.2. Записи

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

ФункцияВозвращаетОписание
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 recordsВозвращает записи из набора переменных.
pgv_select(package text, name text, value anynonarray)recordВозвращает записи из набора переменных с соответствующими первичными ключами (первичный ключ задаётся в первом столбце r).
pgv_select(package text, name text, value anyarray)set of recordsВозвращает записи из набора переменных с соответствующими первичными ключами (первичный ключ задаётся в первом столбце r).

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

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

ФункцияВозвращаетОписание
pgv_exists(package text, name text)boolВозвращает true, если существует пакет и переменная.
pgv_exists(package 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)Возвращает список созданных пакетов и объём памяти, используемый переменными, в байтах. Эта функция поддерживает только Postgres Pro 9.6 и выше.

F.44.3.4. Целочисленные переменные (устаревшее)

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

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

F.44.3.5. Текстовые переменные (устаревшее)

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

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

F.44.3.6. Числовые переменные (устаревшее)

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

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

F.44.3.7. Переменные даты/времени (устаревшее)

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

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

F.44.3.8. Переменные даты/времени с часовым поясом (устаревшее)

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

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

F.44.3.9. Переменные даты (устаревшее)

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

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

F.44.3.10. Переменные 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.4. Примеры

Определение значений int1 и int2 с помощью функции pgv_set() и получение их значений с использованием функции pgv_get():

postgres=# SELECT pgv_set('vars', 'int1', 101);
postgres=# SELECT pgv_set('vars', 'int2', 102);

postgres=# SELECT pgv_get('vars', 'int1', NULL::int);
 pgv_get
-------------
         101
(1 row)

postgres=# SELECT pgv_get('vars', 'int2', NULL::int);
 pgv_get
-------------
         102
(1 row)

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

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

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

postgres=# SELECT pgv_insert('vars', 'r1', tab) FROM tab;

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

postgres=# pgv_select('vars', 'r1', 1);
 pgv_select
------------
 (1,str11)
(1 row)

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

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

postgres=# SELECT pgv_delete('vars', 'r1', 1);

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

Просмотреть имеющиеся пакеты и переменные:

postgres=# SELECT * FROM pgv_list() ORDER BY package, name;
 package | name 
---------+------
 vars    | int1
 vars    | int2
 vars    | r1
(3 rows)

Получение объёма памяти, занятой переменными, в байтах:

postgres=# SELECT * FROM pgv_stats() ORDER BY package;
 package | used_memory
---------+-------------
 vars    |       16736
(1 row)

Удаление избранных переменных или пакетов:

postgres=# SELECT pgv_remove('vars', 'int1');
postgres=# SELECT pgv_remove('vars');

Удаление всех пакетов и переменных:

postgres=# SELECT pgv_free();

F.44.5. Авторы

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