pg_variables. Функции для работы с переменными различных типов

В исходном дистрибутиве установлено по умолчанию: нет.

Связанные компоненты: отсутствуют.

Схема размещения: ext.

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

Примечание:

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

При создании переменные можно задать как нетранзакционные и транзакционные. По умолчанию переменные создаются нетранзакционными. Успешно созданная переменная продолжает существовать на протяжении всего сеанса, вне зависимости от возможных откатов транзакций. Переменные объединяются в пакеты (набор переменных). Это сделано для того, чтобы иметь переменные с разными именами или быстро удалить весь пакет переменных. Если пакет становится пустым, он автоматически удаляется.

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

В случае если вызовы функций pgv_free() или pgv_remove() откатываются, затрагиваемые транзакционные переменные восстанавливаются, в отличие от нетранзакционных, которые удаляются необратимо.

Функции расширения

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

Cкалярные переменные

Функция Описание

pgv_set(package text, name text, value anynonarray, is_transactional bool default false) Создание пакета с переменной скалярного типа

pgv_get(package text, name text, var_type anynonarray, strict bool default true) Получение значений переменной скалярного типа.
Функция проверяет создан пакет и переменная (если указанный пакет или переменная не существуют, будет выдана ошибка), а также тип переменной (при несоответствии заданного типа типу переменной будет выдана ошибка)

Функция	Описание
`pgv_set(package text, name text, value anynonarray, is_transactional bool default false)`	Создание пакета с переменной скалярного типа
`pgv_get(package text, name text, var_type anynonarray, strict bool default true)`	Получение значений переменной скалярного типа. Функция проверяет создан пакет и переменная (если указанный пакет или переменная не существуют, будет выдана ошибка), а также тип переменной (при несоответствии заданного типа типу переменной будет выдана ошибка)

Массивы

Функция Описание

pgv_set(package text, name text, value anyarray, is_transactional bool default false) Создание пакета с переменными-массивами

pgv_get(package text, name text, var_type anyarray, strict bool default true) Получение значений массива.
Функция проверяет создан пакет и переменная (если указанный пакет или переменная не существуют, будет выдана ошибка), а также тип переменной (при несоответствии заданного типа типу переменной будет выдана ошибка)

Функция	Описание
`pgv_set(package text, name text, value anyarray, is_transactional bool default false)`	Создание пакета с переменными-массивами
`pgv_get(package text, name text, var_type anyarray, strict bool default true)`	Получение значений массива. Функция проверяет создан пакет и переменная (если указанный пакет или переменная не существуют, будет выдана ошибка), а также тип переменной (при несоответствии заданного типа типу переменной будет выдана ошибка)

Записи

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

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

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

Доработка

Доработка не проводилась.

Ограничения

Ограничения отсутствуют.

Установка

Для установки расширения необходимо выполнить команду CREATE EXTENSION c правами superuser:

CREATE EXTENSION IF NOT EXISTS pg_variables WITH SCHEMA ext;

Настройка

Настройка не требуется.

Использование модуля

Определение переменных скалярного типа:

pgv_set(package text, name text, value anynonarray, is_transactional bool default false)

Входные параметры:
- package – имя пакета;
- name – имя переменной;
- value – значение переменной;
- is_transactional - признак транзакционной переменной (по умолчанию false)
Возвращаемое значение:
- void (пустое значение)
Команда определения нетранзакционной переменной:
```
SELECT pgv_set('package_name', 'var_text1', 'text variable'::text);
```
Команда определения транзакционной переменной:
```
SELECT pgv_set('package_name', 'trans_var_int', 7, true);
```
Получение значений переменных:

pgv_get(package text, name text, var_type anynonarray, strict bool default true)

Входные параметры:
- package – имя пакета;
- name – имя переменной;
- var_type – тип переменной;
- strict bool - логическое значение (по умолчанию true)
Возвращаемое значение:
- anynonarray/anynarray - значение переменной
Пример запроса:
```
SELECT pgv_get('package_name', 'var_int1', NULL::int);
```
Пример ответа:
```
pgv_get
---------
7
(1 row)
```
Получение списка переменных с помощью функции pgv_list()

Входные параметры:
- нет.
Возвращаемое значение:
- package - имя пакета;
- name - имя переменной;
- is_transactional (boolean) - признак транзакционной переменной (true/false).
Пример запроса:
```
SELECT * FROM pgv_list();
```
Пример ответа:
```
    package   |   name    | is_transactional
--------------+-----------+------------------
package_name1 | var_int3  | f
package_name1 | var_int4  | t
(2 rows)
```
Определение переменных-записей из таблицы БД:

pgv_insert(package text, name text, r record, is_transactional bool default false)

Входные параметры:
- package – имя пакета;
- name – имя переменной;
- r record – данные из таблицы (первый столбец записи r — первичный ключ);
- is_transactional - признак транзакционной переменной (по умолчанию false).
Возвращаемое значение:
- void (пусто)
Определим переменные-записи на основе данных из таблицы airports в БД:
```
SELECT pgv_insert('bookings','code',airports) FROM airports;
```

Получение значений из списка записей переменных:

pgv_select(package text, name text, value anynonarray)

Входные параметры:

package – имя пакета;
name – имя переменной;
value – значения переменных.

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

record/set of records - значения переменных-записей.

В переменных-записях, полученных в примере 4, выполним поиск по ключу, напр. найдем аэропорт Домодедово по его коду DME:

SELECT pgv_select('bookings','code','DME'::char(3));

Пример ответа:

                       pgv_select                        
-----------------------------------------------------------
(DME,Домодедово,Москва,37.906111,55.408611,Europe/Moscow)
(1 row)

Кроме этого, можно сделать выборку не конкретной записи, а выбрать все записи переменной, указать LIMIT, OFFSET как и для обычной таблицы:

SELECT pgv_select('bookings','code') LIMIT 10 OFFSET 50;

Пример ответа:

                       pgv_select                        
-----------------------------------------------------------
 (VVO,Владивосток,Владивосток,132.148017,43.398953,Asia/Vladivostok)
 (PEZ,Пенза,Пенза,45.0211,53.1106,Europe/Moscow)
 (DME,Домодедово,Москва,37.906111,55.408611,Europe/Moscow)
 (SKX,Саранск,Саранск,45.2123,54.1251,Europe/Moscow)
 (PES,Бесовец,Петрозаводск,34.1547,61.8852,Europe/Moscow)
 (NBC,Бегишево,Нижнекамск,52.06,55.34,Europe/Moscow)
 (BTK,Братск,Братск,101.698331,56.370556,Asia/Irkutsk)
 (OVB,Толмачево,Новосибирск,82.650656,55.012622,Asia/Novosibirsk)
 (KVX,Победилово,Киров,49.3483,58.5033,Europe/Moscow)
 (IAR,Туношна,Ярославль,40.157369454444,57.560666676667,Europe/Moscow)
(10 rows)

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

pgv_remove(package text, name text)

Входные параметры:
- package – имя пакета;
- name – имя переменной
Возвращаемое значение:
- void (пусто)
Удалим переменную var_int2 из пакета с именем package_name:
```
SELECT * FROM pgv_remove('package_name', 'var_int2');
```
Пример ответа:
```
pgv_remove
------------

(1 row)
```
Получение списка созданных пакетов и объема памяти, используемый переменными, с помощью функции pgv_stats()

Входные параметры:
- нет
Возвращаемое значение: TABLE(package text, allocated_memory bigint), где:
- package - имя пакета;
- allocated_memory (bigint) - объем памяти (в байтах)
Пример запроса:
```
SELECT * FROM pgv_stats();
```
Пример ответа:
```
    package    | allocated_memory
---------------+------------------
 package_name1 |            24576
 package_name2 |            16384
 package_name  |            32768
(3 rows)
```

Ссылки на документацию разработчика

Дополнительно поставляемый модуль pg_variables: https://github.com/postgrespro/pg_variables

Функции расширения​

Cкалярные переменные​

Массивы​

Записи​

Функции разного назначения​

Доработка​

Ограничения​

Установка​

Настройка​

Использование модуля​

Ссылки на документацию разработчика​