Записки программиста

В рамках статьи Учимся писать расширения на языке C для PostgreSQL мы познакомились со структурой расширений для постгреса, узнали, как писать для них тесты, и даже затронули вопрос обновления расширений и использования интерфейса SPI. Но заметка вышла из серии «с места в карьер», без глубокого погружения в детали. А между тем, погружаться есть во что. Хотелось бы заполнить кое-какие пробелы, и начать, пожалуй, следует с Datum и вызова сторонних функций.

Рассмотрим конкретный пример. Допустим, я хочу преобразовать строку в тип Timestamp, или наоборот. Вот как это можно сделать:

Здесь строка tstamp_str преобразуется в Timestamp. Затем Timestamp преобразуется обратно в char*. Эта строка возвращается в виде результата с SQL-типом TEXT.

Тип Datum и макросы DirectFunctionCall* к этому моменту нам уже знакомы, поэтому не будем на них задерживаться. Куда интереснее другое. Как я узнал, что для сериализации Timestamp в строку есть функция timestamp_out, а для десериализации — timestamp_in? И откуда я знаю, сколько у них аргументов?

В постгресе для любого типа есть текстовое представление. Это нужно для того, чтобы пользователь мог вводить значения разных типов в каком-нибудь psql, а также для отображения значений, прочитанных из таблиц. Функции, преобразующие строку к заданному типу и обратно называются <type>_in и <type>_out. Также есть функции для преобразования одного типа в другой. Они называются <type1>_<type2>. Например, для преобразования Date в Timestamp есть функция date_timestamp.

Узнать, что принимает функция и что она возвращает, можно в psql:

Если вы ищите функцию, но не знаете точно, как она называется, можно открыть файл src/include/catalog/pg_proc.dat в исходном коде PostgreSQL.

Важно! Обращайте внимание на volatility функций! Здесь функция является STABLE, то есть, ее поведение зависит от параметров сессии. Это может быть или не быть проблемой, смотря что за задачу вы решаете. Если ваша функция использует STABLE-функции, она тоже должна быть объявлена, как STABLE.

Функция timestamp_in принимает три аргумента. Хотя, казалось бы, мы просто хотим преобразовать строку в Timestamp. Зачем нужно два «лишних» аргумента? Оказывается, что второй аргумент (typelem) на самом деле игнорируется. Третий аргумент (typmod) позволяет производить не очень понятные мне манипуляции. Если вам интересно в этом разобраться, можете почитать полную реализацию в src/backend/utils/adt/timestamp.c. В приведенном примере указывается значение typemod = -1, что означает не производить никаких манипуляций.

Разные функции <type>_in принимают разное количество аргументов, так что будьте внимательны. Например, date_in принимает только cstring. Другой важный момент заключается в том, что cstring — это не то же самое, что text! Первый представляет собой буквально char*, тогда как второй — это объект, представляющий SQL-тип TEXT. Вы не можете передавать text в функцию, ожидающую cstring, или возвращать cstring там, где следует возвращать text. Также ни в коем случае нельзя путать макрос DatumGetTextP с DatumGetCString, и так далее. Если функция вернула cstring, а нам нужен text, можно воспользоваться макросом CStringGetTextDatum. Этот макрос и используется в приведенном примере. Для преобразования в обратную сторону есть TextDatumGetCString.

Важно! В зависимости от платформы, на которой собран постгрес, Datum может хранить 64-х битные числа либо по значению, либо по ссылке. Это означает, что сравнивать два Datum’а напрямую нельзя, даже если вы знаете, что в нем лежит Timestamp! Такой код будет прекрасно работать на x64, но развалится на 32-х битных системах.

Для закрепления материала рассмотрим еще один пример:

Здесь мы имеем дело с перегруженной функцией:

Тонкости работы с часовыми поясами в PostgreSQL ранее были рассмотрены в отдельной статье. Главное, что нужно знать — тип TimestampTz представляет собой время в UTC, точно так же, как и Timestamp. Разница только в том, как эти типы показываются пользователю. TimestampTz отображается в часовом поясе сессии, который можно поменять командой SET TIME ZONE.

Приведенная функция приводит переданное время во время в заданном часовом поясе. Время передается первым аргументом, а часовой пояс вторым. Если часовой пояс не указан, используется значение по умолчанию Europe/Moscow.

Пример интересен тем, что фактически он делает timestamptz AT TIME ZONE tzname. Но как я узнал, что это эквивалентно timestamptz_zone(tzname, timestamptz)? Если поискать строку AT TIME ZONE по исходному коду PostgreSQL, можно быстро наткнуться на src/backend/parser/gram.y:

Не нужно быть экспертом во Flex и Bison, чтобы понять — здесь вызывается функция timezone. Это перегруженная функция и в зависимости от аргументов будет вызвана та или иная функция на языке C. Смотрим на \df+ и видим:

В аргументах text и timestamptz, возвращаемое значение — timestamp. То, что нужно. Этой версии соответствует сишная функция timestamptz_zone. Вот и ответ.

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

Дополнение: В продолжение темы см Расширения PostgreSQL: логирование и исключения, Расширения PostgreSQL: управление памятью, Внутренности PostgreSQL: как добавить новую функцию и далее по ссылкам.

Метки: C/C++, PostgreSQL, СУБД.