Изучая исходный код PostgreSQL, можно повстречать сущность под названием Portal. Возникает закономерный вопрос — что это такое, а также где и для чего используется? Попробуем разобраться.

Чтобы вживую увидеть Portal, подключимся gdb к бэкенду PostgreSQL и поставим следующую точку останова:

Если теперь выполнить запрос:

… то будет получен такой стэктрейс:

Продолжая экспериментировать с разными запросами, мы убеждаемся, что их исполнение всегда происходит через PortalRun(), где portal фигурирует в качестве аргумента. За дальнейшими разъяснениями обратимся к исходному коду в portalmem.c и portal.h .

Из кода мы узнаем, что же собой представляет портал. Portal — это структура, отражающая состояние исполнения запроса. Один Portal соответствует одному SQL-запросу и, соответственно, имеет один возвращаемый результат.

Портал реализован, как структура PortalData . В ней немало полей. Все их мы разбирать не буем, ограничившись лишь парой наиболее интересных:

Портал имеет выделенный ему MemoryContext . C MemoryContext’ами к этому моменту мы уже знакомы.

Также каждому порталу присваивается ResourceOwner. Это отдельная важная структура, однако ее обсуждение выходит за рамки поста. Если в двух словах, то ResourceOwner отвечает за своевременное освобождение ресурсов, таких как открытые файлы, pin’ы на разделяемые буферы , и так далее.

Хук, вызываемый при освобождении портала. Как правило, это PortalCleanup() , объявленный в portalcmds.c .

Текст SQL-запроса. В PostgreSQL ≥ 8.4 здесь не может быть NULL.

Параметры запроса.

Чтобы посмотреть, как эта структура заполняется, в psql выполним:

Затем создадим точку останова на PortalRun() и выполним запрос:

Точка останова срабатывает дважды:

Значение полей при первом вызове функции:

… и при втором:

Видим, как через portalParams был передан аргумент для prepared statement .

Над порталами определен ряд функций, такие как CreatePortal(), PortalDrop(), PortalDefineQuery(), GetPortalByName() и другие. Полный список есть в portal.h , а датели реализации можно найти в portalmem.c . Заинтересованные читатели могут ознакомиться с этими функциями самостоятельно. Они простые.

Это базовые операции над порталами, а вся логика находится в файле pquery.c . Основных функций две — это PortalStart() :

… и PortalRun() :

В pquery.c есть комментарии относительно всех аргументов, возвращаемых значений, и т.д. Пример практического использования функций CreatePortal(), PortalDefineQuery(), PortalStart(), PortalRun() и PortalDrop() можно найти в функции exec_simple_query() , уже знакомой нам по представленным выше стектрейсам.

Конечно же, полная картина сложнее. Однако углубляться в изучение порталов еще сильнее как будто бы нет особого смысла. Даже разработчики PostgreSQL исключительно редко трогают порталы. В этом легко убедиться при помощи команды git log . Обычно достаточно в общих чертах понимать, что они из себя представляют. Если же когда-нибудь вам придется с головой погрузиться в детали реализации, то теперь у вас есть отправная точка. Для получения самой полной и актуальной информации рекомендуется читать код и ставить эксперименты под отладчиком.

Дополнение: В продолжение темы порталов вас может заинтересовать статья Внутренности PostgreSQL: сетевой протокол .