create_hash_partitions(relation         REGCLASS,
                       attribute        TEXT,
                       partitions_count INTEGER,
                       partition_name   TEXT DEFAULT NULL,
                       partition_data   BOOLEAN DEFAULT TRUE)

Выполняет HASH-секционирование для таблицы relation по целочисленному ключу attribute. Параметр partitions_count задаёт число создаваемых секций; он не может быть изменён впоследствии. Если параметр partition_data равен true, все данные будут автоматически копироваться из родительской таблицы в секции. Заметьте, что миграция данных может занять некоторое время, и таблица будет заблокирована до завершения транзакции. Чтобы мигрировать данные, не устанавливая блокировки, воспользуйтесь функцией partition_table_concurrently(). Для каждой секции вызывается обработчик создания секции, если он был установлен заранее (см. set_init_callback()).

create_range_partitions(relation       REGCLASS,
                        attribute      TEXT,
                        start_value    ANYELEMENT,
                        interval       ANYELEMENT,
                        count          INTEGER DEFAULT NULL
                        partition_data BOOLEAN DEFAULT TRUE)

create_range_partitions(relation       REGCLASS,
                        attribute      TEXT,
                        start_value    ANYELEMENT,
                        interval       INTERVAL,
                        count          INTEGER DEFAULT NULL,
                        partition_data BOOLEAN DEFAULT TRUE)

Выполняет RANGE-секционирование таблицы relation по ключу разбиения attribute. Аргумент start_value задаёт начальное значение, interval — диапазон значений внутри одной секции, count — число заранее создаваемых секций (если не задано, то pathman пытается определить это количество на основе значений ключа). Для каждой секции вызывается обработчик создания секции, если он был установлен заранее.

create_partitions_from_range(relation       REGCLASS,
                             attribute      TEXT,
                             start_value    ANYELEMENT,
                             end_value      ANYELEMENT,
                             interval       ANYELEMENT,
                             partition_data BOOLEAN DEFAULT TRUE)

create_partitions_from_range(relation       REGCLASS,
                             attribute      TEXT,
                             start_value    ANYELEMENT,
                             end_value      ANYELEMENT,
                             interval       INTERVAL,
                             partition_data BOOLEAN DEFAULT TRUE)

Выполняет RANGE-секционирование для заданного диапазона таблицы relation по ключу разбиения attribute. Для каждой секции вызывается обработчик создания секции, если он был установлен заранее.

partition_table_concurrently(relation REGCLASS)

Запускает фоновый рабочий процесс для переноса данных из родительской таблицы в секции. Этот рабочий процесс копирует данные в коротких транзакциях небольшими блоками (до 10000 строк в транзакции) и поэтому не оказывает значительного влияния на работу пользователей.

stop_concurrent_part_task(relation REGCLASS)

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

create_hash_update_trigger(parent REGCLASS)

Создаёт триггер на UPDATE для HASH-секций. По умолчанию триггер на изменение данных не создаётся по причине связанных с этим издержек. Триггер полезен в случаях, когда меняется значение ключевого атрибута.

create_range_update_trigger(parent REGCLASS)

Аналогично предыдущей функции, но для RANGE-секций.

split_range_partition(partition      REGCLASS,
                      value          ANYELEMENT,
                      partition_name TEXT DEFAULT NULL)

Разбивает RANGE-секцию partition на две по значению value. Для создаваемой секции вызывается обработчик создания секции, если он задан.

merge_range_partitions(partition1 REGCLASS, partition2 REGCLASS)

Объединяет две смежные RANGE-секции. Данные из partition2 копируются в partition1, после чего partition2 удаляется.

append_range_partition(p_relation     REGCLASS,
                       partition_name TEXT DEFAULT NULL,
                       tablespace     TEXT DEFAULT NULL)

Добавляет новую RANGE-секцию с диапазоном pathman_config.range_interval в конец списка секций.

prepend_range_partition(p_relation     REGCLASS,
                        partition_name TEXT DEFAULT NULL,
                        tablespace     TEXT DEFAULT NULL)

Добавляет новую RANGE-секцию с диапазоном pathman_config.range_interval в начало списка секций.

add_range_partition(relation       REGCLASS,
                    start_value    ANYELEMENT,
                    end_value      ANYELEMENT,
                    partition_name TEXT DEFAULT NULL,
                    tablespace     TEXT DEFAULT NULL)

Добавляет новую RANGE-секцию для таблицы relation с заданными границами диапазона.

drop_range_partition(partition TEXT, delete_data BOOLEAN DEFAULT TRUE)

Удаляет RANGE-секцию, а также все содержащиеся в ней данные, если установлен флаг delete_data.

attach_range_partition(relation    REGCLASS,
                       partition   REGCLASS,
                       start_value ANYELEMENT,
                       end_value   ANYELEMENT)

Присоединяет секцию к существующему отношению с RANGE-секционированием. Структура присоединяемой таблицы должна в точности повторять структуру родительской, включая удалённые столбцы. Если установлен, вызывается обработчик создания секции (см. pathman_config_params).

detach_range_partition(partition REGCLASS)

Отсоединяет секцию от существующего отношения с RANGE-секционированием.

disable_pathman_for(relation TEXT)

Полностью отключает механизм секционирования pg_pathman для заданной родительской таблицы и удаляет триггер на добавление, если он существует. При этом все секции и данные остаются без изменений.

drop_partitions(parent      REGCLASS,
                delete_data BOOLEAN DEFAULT FALSE)

Удаляет секции таблицы parent (как сторонние, так и локальные). Если параметр delete_data равен false (это значение по умолчанию), данные сначала копируются в родительскую таблицу.

set_enable_parent(relation REGCLASS, value BOOLEAN)

Включает/исключает родительскую таблицу в план запроса. В оригинальном планировщике PostgreSQL родительская таблица всегда включается в план запроса, даже если она пуста, что может повлечь дополнительные издержки. Вы можете исключить родительскую таблицу из рассмотрения, если не собираетесь никогда хранить в ней какие-либо данные. Значение по умолчанию зависит от параметра partition_data, заданного при изначальном создании секций (см. функции create_range_partitions() или create_partitions_from_range()). Если параметр partition_data имел значение true, значит, все данные уже были перенесены в секции, и родительская таблица отключается. В противном случае она включена.

set_auto(relation REGCLASS, value BOOLEAN)

Включает/отключает автоматическое создание секций (только для RANGE-секционирования). По умолчанию этот режим включён.

set_init_callback(relation REGCLASS, callback REGPROC DEFAULT 0)

Устанавливает обработчик создания секции, который будет вызываться для каждой присоединяемой или создаваемой секции (HASH или RANGE). Обработчик должен иметь следующую сигнатуру: part_init_callback(args JSONB) RETURNS VOID. В параметре arg передаётся набор полей, в зависимости от типа секционирования:

/* таблица abc с RANGE-секционированием (потомок abc_4) */
{
    "parent":    "abc",
    "parttype":  "2",
    "partition": "abc_4",
    "range_max": "401",
    "range_min": "301"
}

/* таблица abc с HASH-секционированием (потомок abc_0) */
{
    "parent":    "abc",
    "parttype":  "1",
    "partition": "abc_0"
}

CREATE TABLE IF NOT EXISTS pathman_config (
    partrel         REGCLASS NOT NULL PRIMARY KEY,
    attname         TEXT NOT NULL,
    parttype        INTEGER NOT NULL,
    range_interval  TEXT,

    CHECK (parttype IN (1, 2)) /* проверка допустимых типов частей */ );

В этой таблице хранится список секционированных таблиц.

CREATE TABLE IF NOT EXISTS pathman_config_params (
    partrel        REGCLASS NOT NULL PRIMARY KEY,
    enable_parent  BOOLEAN NOT NULL DEFAULT TRUE,
    auto           BOOLEAN NOT NULL DEFAULT TRUE,
    init_callback  REGPROCEDURE NOT NULL DEFAULT 0);

В этой таблице хранятся дополнительные параметры, переопределяющие стандартное поведение.

-- вспомогательная функция, возвращающая множество
CREATE OR REPLACE FUNCTION show_concurrent_part_tasks()
RETURNS TABLE (
    userid     REGROLE,
    pid        INT,
    dbid       OID,
    relid      REGCLASS,
    processed  INT,
    status     TEXT)
AS 'pg_pathman', 'show_concurrent_part_tasks_internal'
LANGUAGE C STRICT;

CREATE OR REPLACE VIEW pathman_concurrent_part_tasks
AS SELECT * FROM show_concurrent_part_tasks();

В этом представлении показываются все работающие в данный момент задачи параллельного разбиения.

-- вспомогательная функция, возвращающая множество
CREATE OR REPLACE FUNCTION show_partition_list()
RETURNS TABLE (
    parent     REGCLASS,
    partition  REGCLASS,
    parttype   INT4,
    partattr   TEXT,
    range_min  TEXT,
    range_max  TEXT)
AS 'pg_pathman', 'show_partition_list_internal'
LANGUAGE C STRICT;

CREATE OR REPLACE VIEW pathman_partition_list
AS SELECT * FROM show_partition_list();

В этом представлении показываются все существующие разделы, а также их родители и границы диапазонов (NULL для HASH-секций).

Рассмотрим пример HASH-секционирования таблицы. Для начала создадим таблицу с целочисленным столбцом.

        CREATE TABLE items (
        id       SERIAL PRIMARY KEY,
        name     TEXT,
        code     BIGINT);

        INSERT INTO items (id, name, code)
        SELECT g, md5(g::text), random() * 100000
        FROM generate_series(1, 100000) as g;
      

Теперь выполним функцию create_hash_partitions() с подходящими аргументами:

        SELECT create_hash_partitions('items', 'id', 100);
      

Этот запрос создаст новые секции и переместит в них данные из родительской таблицы.

Пример запроса, выполняющего фильтрацию по ключу разбиения:

        SELECT * FROM items WHERE id = 1234;
        id  |               name               | code
        ------+----------------------------------+------
        1234 | 81dc9bdb52d04dc20036dbd8313ed055 | 1855
        (1 row)

        EXPLAIN SELECT * FROM items WHERE id = 1234;
        QUERY PLAN
        ------------------------------------------------------------------------------------
        Append  (cost=0.28..8.29 rows=0 width=0)
        ->  Index Scan using items_34_pkey on items_34  (cost=0.28..8.29 rows=0 width=0)
        Index Cond: (id = 1234)
      

Заметьте, узел Append содержит только одно дочернее сканирование, соответствующее предложению WHERE.

Чтобы обратиться к родительской таблице, используйте модификатор ONLY:

        EXPLAIN SELECT * FROM ONLY items;
        QUERY PLAN
        ------------------------------------------------------
        Seq Scan on items  (cost=0.00..0.00 rows=1 width=45)
      

Рассмотрим пример RANGE-секционирования. Давайте создадим таблицу, содержащую сообщения журнала:

        CREATE TABLE journal (
        id      SERIAL,
        dt      TIMESTAMP NOT NULL,
        level   INTEGER,
        msg     TEXT);

        -- подобный индекс будет также создан для каждой секции
        CREATE INDEX ON journal(dt);

        -- сгенерировать некоторые данные
        INSERT INTO journal (dt, level, msg)
        SELECT g, random() * 6, md5(g::text)
        FROM generate_series('2015-01-01'::date, '2015-12-31'::date, '1 minute') as g;
      

Выполним функцию create_range_partitions(), чтобы создать секции, которые будут содержать данные за один день:

        SELECT create_range_partitions('journal', 'dt', '2015-01-01'::date, '1 day'::interval);
      

Этот запрос создаст 365 секций и переместит в них данные из родительской таблицы.

Новые секции добавляются автоматически триггером INSERT, но это можно сделать и вручную, с помощью следующих функций:

        -- добавить новую секцию с заданным диапазоном
        SELECT add_range_partition('journal', '2016-01-01'::date, '2016-01-07'::date);

        -- добавить новую секцию с диапазоном по умолчанию
        SELECT append_range_partition('journal');
      

Первая создаёт новую секцию с заданным диапазоном. Вторая создаёт новую секцию с диапазоном, заданным при первоначальном разбиении, и добавляет её в конец списка секций. Также можно присоединить существующую таблицу в качестве секции. Например, мы можем подключить таблицу архива (это может быть даже сторонняя таблица с другого сервера) с историческими данными:

        CREATE FOREIGN TABLE journal_archive (
        id      INTEGER NOT NULL,
        dt      TIMESTAMP NOT NULL,
        level   INTEGER,
        msg     TEXT)
        SERVER archive_server;

        SELECT attach_range_partition('journal', 'journal_archive', '2014-01-01'::date, '2015-01-01'::date);
      

Для слияния соседних секций используйте функцию merge_range_partitions():

        SELECT merge_range_partitions('journal_archive', 'journal_1');
      

Чтобы разделить секцию по значению, воспользуйтесь функцией split_range_partition():

        SELECT split_range_partition('journal_366', '2016-01-03'::date);
      

Чтобы отсоединить секцию, воспользуйтесь функцией detach_range_partition():

        SELECT detach_range_partition('journal_archive');
      

Пример запроса, выполняющего фильтрацию по ключу разбиения:

        SELECT * FROM journal WHERE dt >= '2015-06-01' AND dt < '2015-06-03';
        id      |         dt          | level |               msg
        --------+---------------------+-------+----------------------------------
        217441  | 2015-06-01 00:00:00 |     2 | 15053892d993ce19f580a128f87e3dbf
        217442  | 2015-06-01 00:01:00 |     1 | 3a7c46f18a952d62ce5418ac2056010c
        217443  | 2015-06-01 00:02:00 |     0 | 92c8de8f82faf0b139a3d99f2792311d
        ...
        (2880 rows)

        EXPLAIN SELECT * FROM journal WHERE dt >= '2015-06-01' AND dt < '2015-06-03';
        QUERY PLAN
        ------------------------------------------------------------------
        Append  (cost=0.00..58.80 rows=0 width=0)
        ->  Seq Scan on journal_152  (cost=0.00..29.40 rows=0 width=0)
        ->  Seq Scan on journal_153  (cost=0.00..29.40 rows=0 width=0)
        (3 rows)
      

Для включения/отключения всего модуля и отдельных узлов плана предназначены несколько переменных GUC:

Чтобы полностью отключить pg_pathman для ранее секционированной таблицы, воспользуйтесь функцией disable_pathman_for():

        SELECT disable_pathman_for('range_rel');
      

Все секции и данные останутся неизменными и будут обрабатываться стандартным механизмом секционирования PostgreSQL.