PostgreSQL: Разработка расширений (функций) на языке С / Хабр

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

Смысл использования языка С при разработке расширений для PostgreSQL по сравнению с интерпретируемыми (скриптовыми) языками можно свести к двум положениям: производительность и функциональность. Ну а по простому, код написанный на С будет работать намного быстрее, например, если функция вызывается миллион раз в запросе на каждую запись. А более конкретно, некоторые возможности PostgreSQL и вовсе нельзя сделать кроме как на С, например, в других языках не поддерживаются типы (особенно если возвращать значение из функции) ANYELEMENT, ANYARRAY и особенно важный VARIADIC.

Простая функция на языке С

Для примера напишем функцию, которая принимает два аргумента и складывает их. Этот пример рассмотрен в документации к PostgreSQL, но мы его чуть улучшим и соберем. Затем загрузим в PostgreSQL и напишем вызов из SQL функции.

#include "postgres.h"
#include "fmgr.h"
PG_MODULE_MAGIC;
PG_FUNCTION_INFO_V1(add_ab);
Datum add_ab(PG_FUNCTION_ARGS)
{
    int32 arg_a = PG_GETARG_INT32(0);
    int32 arg_b = PG_GETARG_INT32(1);
    PG_RETURN_INT32(arg_a + arg_b);
}

Файл add_func.c можно использовать как шаблон для разработки более сложного функционала. Также, пройдемся по коду

#include «postgresql.h»: этот заголовочный файл Вам придется подключать всегда, содержит различные базовые типы и функции.
#include «fmgr.h»: заголовочный файл содержит различные PG_* макросы.
PG_MODULE_MAGIC: макрос, определяющий что мы разрабатываем модуль для PostgreSQL выше версии 8.2.
PG_FUNC_INFO_V1: макрос, определяющий соглашения о вызовах функций внутри PostgreSQL. Если объявить функция без него, то будет соглашение о вызове Версии 0, иначе Версии 1.
Datum: тип возвращаемого значения. Вообще, это универсальный тип в PostgreSQL. Что-то наподобие VARIANT у Microsoft. По сути это просто «сырой» указатель на какие-то данные. Как их интерпретировать, решает пользователь данных.
add_ab(PG_FUNCTION_ARGS): параметры определяются макросом. Позволяет определить любое кол-во аргументов. Обязателен, даже если функция не принимает никаких аргументов.
int32 arg_a = PG_GETARG_INT32(0): макрос чтобы получить значение первого аргумента (начинается с нуля).
PG_RETURN_INT32(arg_a + arg_b): макрос позволяет сконструировать значение нужного типа и вернуть его из функции.

Теперь нам нужно правильно скомпилировать и собрать это. На выходе это будет динамически загружаемая разделяемая библиотека (*.so). Для этого удобней будет сделать через Makefile. В документации описаны ключи и пути, которые необходимо прописать, но мы соберем используя PGXS. Это окружение для разработчиков расширений, это означает что в Вашей системе должны быть установлены все необходимые -dev и -devel пакеты для PostgreSQL.

MODULES = add_func
PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)

Создаем SQL функцию

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

CREATE FUNCTION add(int, int)
  RETURNS int
AS '/usr/lib/postgresql/9.4/lib/add_func', 'add_ab'
LANGUAGE C STRICT;

Вот и всё! Теперь мы можем использовать эту функцию так,

SELECT add(1, 2);

Автоматизируем установку

Теперь немного автоматизируем установку. Это будет весьма полезно, когда Вам заранее неизвестно какая версия PostgreSQL используется, и по какому пути он установлен. Для этого создадим следующий файл,

CREATE FUNCTION add(int, int)
  RETURNS int
AS 'MODULE_PATHNAME', 'add_ab'
LANGUAGE C STRICT;

и добавим в Makefile строку,

MODULES = add_func
DATA_built = add_funcs.sql
PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)

Немного улучшим

Внесем некоторые изменения в наш пример, и сделаем некоторые улучшения.

Проверка аргументов

Помните в определении SQL функции add(int,int) мы использовали ключевое слово STRICT? Оно обозначает, что если хотя бы один из аргументов будет иметь значение NULL, то функция не отработает, и просто вернет NULL. Это похоже на поведение SQL операторов, например, если в операторе "+" хотя бы один аргумент NULL, то результат будет NULL.

Добавим в нашу функцию проверку аргументов, наподобие SQL агрегирующей функции sum(), которая игнорирует значения NULL и продолжает работу. Для этого нам нужно сделать,

Добиться того, чтобы функция отработала даже если один из аргументов имеет значение NULL
Если оба аргумента имеют значения NULL, то вернуть NULL

PG_FUNCTION_INFO_V1(add_ab_null);
Datum add_ab_null(PG_FUNCTION_ARGS)
{
    int32 not_null = 0;
    int32 sum = 0;
    if (!PG_ARGISNULL(0))
    {
        sum += PG_GETARG_INT32(0);
        not_null = 1;
    }
    if (!PG_ARGISNULL(1))
    {
        sum += PG_GETARG_INT32(1);
        not_null = 1;
    }
    if (not_null)
    {
        PG_RETURN_INT32(sum);
    }
    PG_RETURN_NULL();
}

И теперь проверим это,

CREATE FUNCTION add(int, int)
 RETURNS int
AS '$libdir/add_func', 'add_ab_null'
LANGUAGE C;

SELECT add(NULL, NULL) AS must_be_null, add(NULL, 1) AS must_be_one;
-[ RECORD 1 ]+--
must_be_null |
must_be_one  | 1

А вот как это же самое можно добиться стандартными средствами PostgreSQL,

SELECT (CASE WHEN (a IS null) AND (b IS null)
(THEN null
ELSE coalesce(a, 0) + coalesce(b,0)
END)
FROM (SELECT 1::int AS a, null::int AS b) s;
-[ RECORD 1 ]
 case | 1

Любое кол-во аргументов в функции

Как Вы уже заметили, для получения значения аргументов мы использовали макросы. Поэтому мы можем передать любое кол-во аргументов, а затем просто в цикле прочитать их значения,

if (!PG_ARGISNULL(i))
{
    sum += PG_GETARG_INT32(i);
    not_null = 1;
}

У Вас сразу же может возникнуть вопрос, но ведь можно же использовать массив для передачи значения аргументов. И в действительности так и нужно делать, но к сожалению из-за наличия собственного менеджера памяти в PostgreSQL, это не столь уж тривиальная задача. Но попробуем ее решить. В документации PostgreSQL есть пример где передается массив символов text[], но это не совсем то, что нам нужно. Попробуем адаптировать для наших целей,

#include "utils/array.h"     // подключаем заголовочный файл для работы с массивами
#include "catalog/pg_type.h" // INT4OID
PG_MODULE_MAGIC;
Datum add_int32_array(PG_FUNCTION_ARGS);
PG_FUNCTION_INFO_V1(add_int32_array);
Datum add_int32_array(PG_FUNCTION_ARGS)
{
    // подготовим массив для входных параметров.
    // В данном случае мы используем тип данных для обобщенного массива, который позволяет хранить не только целые int.
    ArrayType *input_array;
    int32 sum = 0;
    bool not_null = false;

    Datum *datums;
    bool *nulls;
    int count;
    int i;
    input_array = PG_GETARG_ARRAYTYPE_P(0); // инициализируем массив значением первого аргумента. Суффикс *_P в конце
                                            // макроса говорит о том что будет возвращен указатель, а не INT32

    // Проверим что мы действительно работаем с массивом целых чисел INT32 (INT4)
    Assert(ARR_ELEMTYPE(input_array) == INT4OID);

    // Удостоверимся что массив целых чисел одномерный
    if (ARR_NDIM(input_array) > 1)
        ereport(ERROR, (errcode(ERRCODE_ARRAY_SUBSCRIPT_ERROR), errmsg("1-dimensional array needed")));

    deconstruct_array(input_array, // одномерный массив
                      INT4OID,     // целых чисел
                      4,           // размер целого в байтах
                      true,        // int4 передается по значению
                      'i',         // выравнивание 'i'
                      &datums, &nulls, &count); // здесь результат 

    for(i = 0; i < count; i++)
    {
        // проверяем и пропускаем нулевые элементы
        if (nulls[i])
            continue;

        // суммируем, помня что там были не нулевые элементы
        sum += DatumGetInt32(datums[i]);
        not_null = true;
    }
    if (not_null)
        PG_RETURN_INT32(sum);

    PG_RETURN_NULL();
}

Как всегда, пройдемся по коду,

Нет специального типа для целочисленных массивов, поэтому мы используем обобщенный тип ArrayType, который сгодится для любого типа массивов
Для инициализации массива первым аргументом, мы использовали специальный макрос PG_GETARG_ARRAYTYPE_P
Также есть проверка, действительно ли массив одномерный ARR_NDIM
Тип OID для int4 (= 23) определен как INT4OID. Чтобы просмотреть определения для других типов, можно воспользоваться SQL,
```
select oid, typlen, typbyval, typalign from pg_type
where typname = 'int4';
-[ RECORD 1 ]
oid | 23
typlen | 4
typbyval | t
typalign | i
```

Теперь нам осталось научить PostgreSQL использовать это, объявив функцию, которая принимает аргумент int[],

CREATE OR REPLACE FUNCTION add_arr(int[]) RETURNS int
AS '$libdir/add_func', 'add_int32_array'
LANGUAGE C STRICT;

И проверим,

SELECT add_arr('{1,2,3,4,5,6,7,8,9}');
-[ RECORD 1 ]
add_arr | 45
SELECT add_arr(ARRAY[1,2,NULL]);
-[ RECORD 1 ]
add_arr | 3
SELECT add_arr(ARRAY[NULL::int]);
-[ RECORD 1 ]
add_arr |

Полезные ссылки

PostgreSQL: Server Programming Interface.

PostgreSQL: User Defined Functions in C

PostgreSQL Extension Network

PostgreSQL: Разработка расширений (функций) на языке С

Простая функция на языке С

Создаем SQL функцию

Автоматизируем установку

Немного улучшим

Проверка аргументов

Любое кол-во аргументов в функции

Рекомендации

Работа с памятью

Используем palloc() и pfree()

Инициализация структур

Подключаемые файлы

Полезные ссылки

Публикации