Данные CREATE EXTENSION команда использует управляющий файл для каждого расширения; имя этого файла должно совпадать с именем расширения и иметь суффикс .control, и они должны быть размещены в каталоге установки SHAREDIR/extension директория. Также должен присутствовать как минимум один SQL файл сценария, соответствующий шаблону именования расширение--версия.sql (например, foo--1.0.sql для версии 1.0 расширения foo). По умолчанию файл(ы) сценария также размещаются в SHAREDIR/extension каталоге; но в управляющем файле может быть указан другой каталог для файлов сценариев.

Формат управляющего файла расширения аналогичен формату файла postgresql.conf , а именно списку parameter_name = присваиваний значений, по одному в строке. Допускаются пустые строки и комментарии, начинающиеся с # # are allowed. Обязательно заключайте в кавычки любое значение, не являющееся простым словом или числом.

В управляющем файле можно задать следующие параметры:

Помимо основного управляющего файла расширение.control, расширение может иметь вспомогательные управляющие файлы, именованные в стиле расширение--версия.control. При наличии они должны располагаться в каталоге файлов сценариев. Вспомогательные управляющие файлы имеют тот же формат, что и основной управляющий файл. Любые параметры, заданные во вспомогательном управляющем файле, переопределяют значения из основного управляющего файла при установке или обновлении до этой версии расширения. Однако данные параметры directory и default_version не могут быть заданы во вторичном управляющем файле.

Входящие в состав расширения SQL файлы сценариев могут содержать любые SQL-команды, за исключением команд управления транзакциями (BEGIN, COMMITи т. д.) и команд, которые невозможно выполнить внутри блока транзакции (таких как VACUUM). Это обусловлено тем, что файлы сценариев неявно выполняются внутри блока транзакции.

Входящие в состав расширения SQL файлы сценариев также могут содержать строки, начинающиеся с \echo, которые будут игнорироваться механизмом расширения (интерпретироваться как комментарии). Данная возможность обычно используется для генерации ошибки, если файл сценария передается в psql вместо загрузки с помощью CREATE EXTENSION (см. пример сценария в Раздел 5.1.17.7). В противном случае пользователи могут случайно загрузить содержимое расширения как обычные «разрозненных» объекты, а не как расширение, что создаст ситуацию, которую довольно трудно исправить.

Если скрипт расширения содержит строку @extowner@, то эта строка заменяется на (заключенное в соответствующие кавычки) имя пользователя, вызывающего команду CREATE EXTENSION или ALTER EXTENSION. Как правило, эта функциональность используется расширениями, помеченными как доверенные, для назначения владельцем выбранных объектов вызывающего пользователя вместо суперпользователя начальной загрузки. (Однако при этом следует проявлять осторожность. Например, назначение владельцем функции на языке C пользователя, не являющегося суперпользователем, создаст условия для повышения привилегий этого пользователя.)

В то время как файлы сценариев могут содержать любые символы, разрешенные указанной кодировкой, управляющие файлы должны содержать только символы ASCII, так как для Digital Q.DataBase знать, в какой кодировке представлен управляющий файл. На практике это имеет значение только в том случае, если необходимо использовать символы, отличные от ASCII, в комментариях к расширению. В данном случае рекомендуется не использовать управляющий файл комментарий параметр, но вместо этого используйте COMMENT ON EXTENSION внутри файла сценария для задания комментария.

Пользователи часто стремятся загрузить объекты, содержащиеся в расширении, в схему, отличную от той, которую предполагал автор расширения. Существует три поддерживаемых уровня перемещаемости:

Во всех случаях файл сценария будет выполняться с параметром search_path, search_path изначально установленным на целевую схему; то есть, CREATE EXTENSION выполняется эквивалент следующего:

SET LOCAL search_path TO @extschema@, pg_temp;

Это позволяет объектам, создаваемым файлом сценария, попадать в целевую схему. Файл сценария может изменять search_path search_path по своему усмотрению, но обычно это нежелательно. search_path восстанавливается в прежнее значение по завершении CREATE EXTENSION.

Целевая схема определяется схема параметром в управляющем файле, если он указан, в противном случае — SCHEMA опцией команды CREATE EXTENSION , если она указана, в противном случае — текущей схемой создания объектов по умолчанию (первой в search_pathвызывающей стороны). Когда в управляющем файле схема используется параметр schema, целевая схема будет создана, если она еще не существует, но в двух других случаях она уже должна существовать.

Если какие-либо необходимые расширения перечислены в requires в управляющем файле их целевые схемы добавляются к исходному значению параметра search_path, следующему за целевой схемой нового расширения. Это позволяет обеспечить видимость их объектов для файла сценария нового расширения.

В целях обеспечения безопасности pg_temp автоматически добавляется в конец search_path во всех случаях.

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

Если расширение ссылается на объекты, принадлежащие другому расширению, рекомендуется использовать квалифицированные имена (с указанием схемы). Для этого укажите @extschema:имя@ в файле сценария расширения, где имя — это имя другого расширения (которое должно быть перечислено в данном расширении requires список). Эта строка будет заменена именем (в двойных кавычках, если необходимо) целевой схемы этого расширения. Хотя такая нотация избавляет от необходимости делать жестко заданные предположения об именах схем в файле сценария расширения, её использование может привести к внедрению имени схемы другого расширения в установленные объекты данного расширения. (Как правило, это происходит, когда @extschema:имя@ используется внутри строкового литерала, такого как тело функции или search_path параметр. В других случаях ссылка на объект во время синтаксического анализа преобразуется в OID и не требует последующего поиска.) Если имя схемы другого расширения внедрено таким образом, следует предотвратить перемещение другого расширения после установки вашего, добавив имя другого расширения в no_relocate список.

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

Для решения этой проблемы в файле сценария расширения можно пометить созданную таблицу или последовательность как конфигурационное отношение, что позволит pg_dump включить содержимое таблицы или последовательности (но не её определение) в дампы. Для этого вызовите функцию pg_extension_config_dump(regclass, text) после создания таблицы или последовательности, например

CREATE TABLE my_config (key text, value text);
CREATE SEQUENCE my_config_seq;

SELECT pg_catalog.pg_extension_config_dump('my_config', '');
SELECT pg_catalog.pg_extension_config_dump('my_config_seq', '');

Таким способом можно пометить любое количество таблиц или последовательностей. Последовательности, связанные со serial или bigserial столбцами, также могут быть помечены.

Когда второй аргумент функции pg_extension_config_dump является пустой строкой, всё содержимое таблицы выгружается с помощью pg_dump. Обычно это корректно только в том случае, если таблица изначально пуста в том виде, в каком она была создана скриптом расширения. Если в таблице содержатся как исходные данные, так и данные, добавленные пользователем, второй аргумент функции pg_extension_config_dump предоставляет условие WHERE которое выбирает данные для выгрузки. Например, можно сделать следующее:

CREATE TABLE my_config (key text, value text, standard_entry boolean);

SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entry');

и затем обеспечить, чтобы значение standard_entry было истинным только в строках, созданных скриптом расширения.

Для последовательностей второй аргумент функции pg_extension_config_dump не имеет эффекта.

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

Вы можете изменить условие фильтрации, связанное с конфигурационной таблицей, вызвав pg_extension_config_dump снова. (Обычно это полезно в скрипте обновления расширения.) Единственный способ снять с таблицы статус конфигурационной — это отсоединить её от расширения с помощью ALTER EXTENSION ... DROP TABLE.

Обратите внимание, что связи по внешним ключам между этими таблицами определяют порядок, в котором они выгружаются утилитой pg_dump. В частности, pg_dump попытается выгрузить целевую таблицу (на которую ссылаются) перед ссылающейся таблицей. Поскольку связи по внешним ключам устанавливаются во время выполнения CREATE EXTENSION (до загрузки данных в таблицы), циклические зависимости не поддерживаются. При наличии циклических зависимостей данные все равно будут выгружены, однако восстановить такой дамп напрямую будет невозможно, и потребуется вмешательство пользователя.

Последовательности, связанные со serial или bigserial столбцами должны быть явно помечены для выгрузки своего состояния. Пометки их родительского отношения недостаточно для этой цели.

Одним из преимуществ механизма расширений является наличие удобных способов управления обновлениями SQL-команд, определяющих объекты расширения. Это реализуется путем связывания имени или номера версии с каждой выпущенной версией установочного скрипта расширения. Кроме того, если вы хотите, чтобы пользователи могли динамически обновлять свои базы данных с одной версии на следующую, следует предоставить скрипты обновления , которые вносят необходимые изменения для перехода от одной версии к следующей. Имена скриптов обновления строятся по шаблону расширение--old_version--target_version.sql (например, foo--1.0--1.1.sql содержит команды для изменения версии 1.0 расширения foo на версию 1.1).

При условии наличия подходящего сценария обновления команда ALTER EXTENSION UPDATE обновит установленное расширение до указанной новой версии. Сценарий обновления выполняется в той же среде, которую CREATE EXTENSION предоставляет для сценариев установки: в частности, search_path настраивается аналогичным образом, и любые новые объекты, созданные сценарием, автоматически добавляются в расширение. Кроме того, если сценарий удаляет объекты, входящие в расширение, они автоматически исключаются из его состава.

Если расширение имеет вторичные управляющие файлы, то параметры управления, используемые для сценария обновления, соответствуют целевой (новой) версии сценария.

ALTER EXTENSION может выполнять последовательности файлов сценариев обновления для выполнения запрошенного обновления. Например, если доступны только foo--1.0--1.1.sql и foo--1.1--2.0.sql и , ALTER EXTENSION применяет их последовательно, если запрошено обновление до версии 2.0 в то время как версия 1.0 уже установлена.

Digital Q.DataBase не делает никаких предположений о свойствах имен версий: например, системе неизвестно, следует ли 1.1 за 1.0. Система просто сопоставляет доступные имена версий и выбирает путь, требующий применения наименьшего количества сценариев обновления. (Имя версии может быть любой строкой, не содержащей -- а также начальных и конечных -.)

В некоторых случаях целесообразно предоставить «downgrade» сценарии, например foo--1.1--1.0.sql для обеспечения возможности отмены изменений, связанных с версией 1.1. В этом случае следует учитывать вероятность того, что сценарий отката может быть применен неожиданно, если он образует более короткий путь обновления. Рискованная ситуация возникает тогда, когда существует «прямой путь» — сценарий обновления, обеспечивающий переход сразу через несколько версий, и одновременно с ним сценарий отката к начальной точке этого прямого пути. В такой ситуации выполнение отката с последующим переходом по прямому пути может потребовать меньше шагов, чем последовательное обновление версий. Если сценарий отката удаляет какие-либо невосстановимые объекты, это приведет к нежелательным результатам.

Для проверки непредвиденных путей обновления используйте следующую команду:

SELECT * FROM pg_extension_update_paths('extension_name');

Здесь показана каждая пара различных известных имен версий для указанного расширения вместе с последовательностью шагов в пути обновления, которая будет использована для перехода от исходной версии к целевой, или NULL если доступный путь обновления отсутствует. Путь отображается в текстовом виде с -- разделителями. Вы можете использовать regexp_split_to_array(path,'--') если вам удобнее использовать формат массива.

Расширение, существующее в течение некоторого времени, вероятно, будет представлено в нескольких версиях, для которых автору потребуется написать сценарии обновления. Например, если вы выпустили foo расширение в версиях 1.0, 1.1и 1.2, должны присутствовать сценарии обновления foo--1.0--1.1.sql и foo--1.1--1.2.sql. До версии Digital Q.DataBase 10 также требовалось создавать новые файлы сценариев foo--1.1.sql и foo--1.2.sql которые напрямую собирают более новые версии расширения, иначе более новые версии нельзя было установить напрямую, а только путем установки 1.0 и последующего обновления. Это было трудоемко и приводило к дублированию, но теперь в этом нет необходимости, так как CREATE EXTENSION может автоматически следовать цепочкам обновлений. Например, если доступны только файлы сценариев foo--1.0.sql, foo--1.0--1.1.sql, и foo--1.1--1.2.sql то запрос на установку версии 1.2 удовлетворяется путем последовательного выполнения этих трех сценариев. Обработка выполняется так же, как если бы вы сначала установили 1.0 а затем обновили до 1.2. (Как и в случае с ALTER EXTENSION UPDATE, если доступно несколько путей, предпочтение отдается кратчайшему.) Организация файлов сценариев расширения в таком стиле позволяет сократить объем работ по сопровождению, необходимых для выпуска небольших обновлений.

Если вы используете вторичные (зависящие от версии) управляющие файлы с расширением, поддерживаемым в таком стиле, имейте в виду, что каждой версии требуется управляющий файл, даже если у нее нет отдельного сценария установки, так как этот управляющий файл будет определять способ выполнения неявного обновления до этой версии. Например, если foo--1.0.control определяет requires = 'bar' но fooв других управляющих файлах расширения это отсутствует, поэтому зависимость расширения от bar будет удалена при обновлении с 1.0 на другую версию.

Широко распространяемые расширения не должны делать предположений о базе данных, в которой они функционируют. Следовательно, функции, предоставляемые расширением, следует писать в защищенном стиле, исключающем возможность компрометации через атаки на путь поиска (search_path).

Для расширения, у которого свойство superuser установлено в значение true, также необходимо учитывать риски безопасности при выполнении действий в его скриптах установки и обновления. Злоумышленнику не составит труда создать объекты типа «троянский конь», которые скомпрометируют последующее выполнение небрежно написанного скрипта расширения, что позволит такому пользователю получить права суперпользователя.

Если расширение помечено как trusted, то схема установки может быть выбрана пользователем, выполняющим установку; при этом он может намеренно указать небезопасную схему в надежде получить права суперпользователя. Следовательно, доверенное расширение крайне уязвимо с точки зрения безопасности, и все команды его скриптов должны быть тщательно проверены, чтобы исключить любую возможность компрометации.

Рекомендации по безопасному написанию функций приведены в Раздел 5.1.17.6.1 ниже, а рекомендации по безопасному написанию установочных скриптов приведены в Раздел 5.1.17.6.2.

Ниже приведен полный пример SQL-только расширения: составного типа из двух элементов, который может хранить значения любого типа в своих полях с именами «k» и «v». Нетекстовые значения автоматически приводятся к типу text для хранения.

Файл сценария pair--1.0.sql выглядит следующим образом:

-- выдать ошибку, если сценарий запущен в psql напрямую, а не через CREATE EXTENSION
\echo Используйте "CREATE EXTENSION pair" для загрузки этого файла. \quit

CREATE TYPE pair AS ( k text, v text );

CREATE FUNCTION pair(text, text)
RETURNS pair LANGUAGE SQL AS 'SELECT ROW($1, $2)::@extschema@.pair;';

CREATE OPERATOR ~> (LEFTARG = text, RIGHTARG = text, FUNCTION = pair);

-- Параметр "SET search_path" проще в использовании, но квалифицированные имена работают быстрее.
CREATE FUNCTION lower(pair)
RETURNS pair LANGUAGE SQL
AS 'SELECT ROW(lower($1.k), lower($1.v))::@extschema@.pair;'
SET search_path = pg_temp;

CREATE FUNCTION pair_concat(pair, pair)
RETURNS pair LANGUAGE SQL
AS 'SELECT ROW($1.k OPERATOR(pg_catalog.||) $2.k,
               $1.v OPERATOR(pg_catalog.||) $2.v)::@extschema@.pair;';

Управляющий файл pair.control выглядит следующим образом:

# расширение pair
comment = 'Тип данных пары ключ/значение'
default_version = '1.0'
# нельзя перемещать из-за использования @extschema@
relocatable = false

Хотя для установки этих двух файлов в нужный каталог вряд ли понадобится makefile, вы можете использовать Makefile со следующим содержимым:

EXTENSION = pair
DATA = pair--1.0.sql

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

Этот makefile опирается на PGXS, который описан в Раздел 5.1.18. Команда make install установит управляющий файл и файлы сценариев в соответствующий каталог, указанный pg_config.

После установки файлов используйте команду CREATE EXTENSION для загрузки объектов в конкретную базу данных.