plpdebugger. Средство отладки plpgsql#

Версия: 1.1.

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

Связанные компоненты: plpgsql.

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

Доработка#

Не производилась.

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

Для корректной работы pldebugger необходимо наличие plpgsql - расширения по работе с plpgsql.

Внимание!

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

Установка#

Установка расширения для ALT SP8 и Astra Linux:

sudo dnf install /usr/pangolin-6.3/3rdparty/pldebugger/pangolin-pldebugger-1.1-{OS}.x86_64.rpm -y

Для других ОС:

sudo apt-get install /usr/pangolin-6.3/3rdparty/pldebugger/pangolin-pldebugger-1.1-{OS}.x86_64.rpm -y

Для использования расширения на развернутой СУБД необходимо установить его в целевую БД:

CREATE EXTENSION pldbgapi SCHEMA ext;

Расширение может быть добавлено в shared_preload_libraries:

shared_preload_libraries = 'plugin_debugger'

В случае, если расширение используется совместно с расширением plpgsql_check, библиотека расширения должна быть указана первой при перечислении в shared_preload_libraries:

shared_preload_libraries = 'plugin_debugger,plpgsql_check'

Настройка#

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

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

В данном разделе будут рассмотрены введенные расширением типы данных, а также функции, предоставляемые им.

Типы данных расширения#

Типы, добавляемые расширением:

breakpoint;
frame;
proxyinfo;
targetinfo;
var.

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

Функция	Входные аргументы	Тип возвращаемого значения	Описание
`pldbg_abort_target`	`session integer`	`boolean`	Останавливает выполнение/отладку кода в сессии с переданным в аргументе `PID`. Возвращает `true` или `false` в зависимости от успешности остановки
`pldbg_attach_to_port`	`portnumber integer`	`integer`	Функция подключается к целевому объекту отладки, прослушивающему заданный порт. Клиент отладчика вызывает эту функцию в ответ на уведомление `PLDBGBREAK` (уведомление содержит номер порта, к которому необходимо подключиться). Функция возвращает дескриптор сеанса, который идентифицирует конкретный сеанс отладки. При вызове любой из функций с префиксом `pldbg_*`, нужно указать дескриптор сеанса, возвращаемый функцией `pldbg_attach_to_port()`. Клиент отладчика может поддерживать несколько одновременных сеансов благодаря многократному вызову `pldbg_attach_to_port()` (с разными номерами портов) и отслеживанию возвращаемых дескрипторов сеанса
`pldbg_continue`	`session integer`	`breakpoint`	Функция отправляет команду `continue` целевому объекту отладчика, а затем ожидает, пока он достигнет следующего исполняемого оператора. На выходе возвращается запись типа `breakpoint`, характеризующая точку останова и содержащая идентификатор функции, а также номер строки, в которой целевой объект в данный момент остановлен
`pldbg_create_listener`		`integer`	Функция создает сеанс отладки. Возвращает `id` сессии сеанса отладки
`pldbg_deposit_value`	`session integer`, `varname text`, `linenumber integer`, `value text`	`boolean`	Функция перезаписывает значение заданной переменной (идентифицируемой по имени и номеру строки). Аргумент `value` определяется как выражение, результатом которого должно быть значение с типом, аналогичным типу заданной переменной (или приводимым к нему типом)
`pldbg_drop_breakpoint`	`session integer`, `func oid`, `linenumber integer`	`boolean`	Функция удаляет локальную точку останова в целевом процессе
`pldbg_get_breakpoints`	`session integer`	`setof breakpoint`	Функция возвращает набор точек останова. Каждая запись в результирующем наборе идентифицирует точку останова
`pldbg_get_proxy_info`	Отсутствуют	`proxyinfo`	Функция извлекает небольшую коллекцию параметров с сервера, которые связаны с версией сервера и версией протокола API, реализованного расширением для взаимодействия с ним внешних графических инструментов (например, pgAdmin). Функция может быть вызвана (из клиентского процесса отладчика), чтобы узнать, с какой версией прокси-API происходит взаимодействие - если этой функции не существует, можно предположить, что обмен данными осуществляется с прокси-API версии 1
`pldbg_get_source`	`session integer`, `func oid`	`text`	Функция возвращает исходный код для заданной функции. Клиент отладчика всегда должен извлекать исходный код, вызывая данную функцию, вместо чтения `pg_proc`. Если вместо этого производится чтение `pg_proc`, то считываемый исходный код может не совпадать с исходным кодом, фактически выполняемым целевым объектом (поскольку исходный код мог быть изменен в другой транзакции). `pldbg_get_source()` всегда извлекает исходный код из целевого объекта и гарантирует, что получаемый на выходе исходный код является исходным кодом, выполняемым целевым объектом
`pldbg_get_stack`	`session integer`	`setof frame`	Функция возвращает набор записей с фреймворками. Каждая запись в результирующем наборе содержит информацию об одном фреймворке стека. Каждая запись также содержит строку, которую можно использовать для отображения имени и значения каждого аргумента для конкретного вызова
`pldbg_get_target_info`	`signature text`, `targettype char`	`targetinfo`	Устаревшая функция, которая возвращает информацию о целевой отлаживаемой функции. Используется для обратной совместимости старых версий pgAdmin. Для новых приложений получение информации из каталога происходит напрямую
`pldbg_get_variables`	`session integer`	`setof var`	Функция возвращает набор записей `var`. Записи в результирующем наборе содержат информацию об одной рассматриваемой локальной переменной (или параметре) во фреймворке стека. Каждая запись содержит имя переменной, номер строки, в которой была объявлена переменная, а также флаг, сообщающий, является ли имя уникальным в пределах области действия функции. Если имя не является уникальным, клиент отладчика может использовать номер строки для различия переменных с одинаковыми именами. Помимо этого каждая запись содержит флаг, используемый для определения, является ли переменная константной; флаг, определяющий, является ли переменная нулевой, а также тип данных переменной (`OID`соответствующего `pg_type`) с ее значением. Чтобы просмотреть переменные, определенные в другом фреймворке стека, необходимо вызвать `pldbg_select_frame()` для переключения внимания отладчика на конкретный фреймворк
`pldbg_oid_debug`	`functionoid oid`	`integer`	Функция получает информацию о функции с переданным `OID` из `pg_proc` и в случае, если функция найдена, информация о ней получена, а пользователь, запустивший ее является суперпользователем, устанавливается локальная точка останова в начале данной функции. В случае успеха возвращается `0`, в противном случае - код ошибки
`pldbg_select_frame`	`session integer`, `frame integer`	`breakpoint`	Функция изменяет цель отладчика на указанный кадр (в стеке вызовов). При остановке отладчик переключается на наиболее глубоко вложенную функцию в стеке вызовов (так как это функция, которая выполняется в данный момент времени). Цель отладчика можно изменить на другие фреймворки стека с целью получения исходного кода для этого фреймворка, значения переменных в этом фреймворке и точек останова в целевом объекте. Отладчик остается на выбранном кадре до тех пор, пока он не будет изменен пользователем или пока целевой объект не остановится на другой точке останова. Функция возвращает запись типа `breakpoint`, содержащую идентификатор функции и номер строки, на которой целевой объект в данный момент остановлен
`pldbg_set_breakpoint`	`session integer`, `func oid`, `linenumber integer`	`boolean`	Функция регистрирует локальную точку останова в целевом процессе
`pldbg_set_global_breakpoint`	`session integer`, `func oid`, `linenumber integer`, `targetpid integer`	`boolean`	Функция регистрирует точку останова в глобальной структуре с точками останова. На вход принимает `id` сессии, в которой запущен отладчик, `OID` функции, которую планируется отлаживать, номер строки функции, на которую устанавливается точка останова, а также `PID` целевого процесса, в котором будет выполняться отлаживаемая функция
`pldbg_step_into`	`session integer`	`breakpoint`	Функция отправляет команду `step/into` целевому объекту отладчика, а затем ожидает, пока целевой объект достигнет следующего исполняемого оператора, и возвращает запись типа `breakpoint`
`pldbg_step_over`	`session integer`	`breakpoint`	Функция отправляет команду `step/over` целевому объекту отладчика, а затем ожидает, пока целевой объект достигнет следующего исполняемого оператора в текущей функции. Если целевой объект столкнется с точкой останова (например, в дочернем вызове) до перехода к следующей исполняемой строке, он остановится на точке останова. Функция возвращает запись типа `breakpoint`
`pldbg_wait_for_breakpoint`	`session integer`	`breakpoint`	Функция ожидает, пока целевой объект отладки достигнет точки останова. Необходимо вызвать функцию сразу после того, как `pldbg_attach_to_port()` вернет идентификатор сеанса. Функция `pldbg_wait_for_breakpoint()` почти идентична функциям `pldbg_step_into()`, `pldbg_step_over()` и `pldbg_continue()` (все они ожидают целевого объекта), но эта функция не отправляет команду целевому объекту первой. В качестве возвращаемого значения - запись типа `breakpoint`
`pldbg_wait_for_target`	`session integer`		Функция объявляет прокси-процесс активным отладчиком, ожидающим глобальных точек останова и возвращает дескриптор сеанса, который идентифицирует конкретный сеанс отладки. Когда вызывается любая из других функций `pldbg`, необходимо указать соответствующий дескриптор сеанса. Данный клиент отладчика может поддерживать несколько одновременных сеансов, вызывая `pldbg_attach_to_port()` много раз (с разными номерами портов) и отслеживая возвращаемые дескрипторы сеанса
`plpgsql_oid_debug`	`functionoid oid`	`integer`	Обертка для функции `pldbg_oid_debug (functionoid oid)`, создана для обратной совместимости старых версий pgAdmin

Схема взаимодействия#

Отладчик состоит из трех частей:

Клиент — среда, в которой вызываются функции API (консоль psql или некоторый графический интерфейс). Отображает исходный код, текущий фреймворк стека, переменные и т.п., позволяя пользователю устанавливать точки останова и пошагово выполнять код. Клиент может находиться на другом узле, отличном от сервера базы данных (например, PgAdmin).
Целевой сервер - серверная часть, которая запускает отлаживаемый код. Библиотека plugin_debugger.so должна быть загружена в целевой сервер.
Отладочный прокси - дополнительный серверный процесс, к которому подключен клиент. Функции API, методы pl_dbg*, а также библиотеки pldbgapi.so, выполняются именно на нем.

Клиент должен подключиться к отладочному прокси, используя обычное соединение libpq. Когда сеанс отладки активен, прокси вызывает функции API библиотеки plugin_debugger.so, которая в свою очередь подключается к целевому серверу на уровне ядра, прозрачным для клиента образом. Протокол между прокси и целевым сервером не видим для других пользователей. Методы pldbg_* из библиотек API предоставляют доступный интерфейс к средствам отладки.

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

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

pldebugger: https://github.com/EnterpriseDB/pldebugger.