Работа с расширениями

Платформы

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

Все официальные расширения распространяются для следующих платформ.

Для некоторых дистрибутивов Linux ARM (например, Python) распространяются два разных бинарных файла. Они нацелены на платформы linux_arm64 или linux_arm64_gcc4. Обратите внимание, что бинарные файлы расширений распространяются только для первой, но не для второй. Это означает, что на этих платформах версия вашей glibc должна быть 2.28 или выше, чтобы использовать распространяемые бинарные файлы расширений.

Некоторые расширения распространяются для следующих платформ:

• windows_amd64_mingw
• wasm_eh и wasm_mvp (см. расширения DuckDB-Wasm)

Для платформ, не указанных выше, мы не распространяем расширения официально (например, linux_arm64_android, linux_arm64_gcc4).

Обмен расширениями между клиентами

Общее место установки позволяет расширениям быть общими для клиентских API одной и той же версии DuckDB, если они используют ту же самую platform или ABI. Например, если расширение установлено с версией 0.10.0 клиента командной строки на macOS, оно доступно из библиотек клиентов Python, R и т. д., при условии, что у них есть доступ к домашнему каталогу пользователя и они используют версию DuckDB 0.10.0.

Репозитории расширений

По умолчанию, расширения DuckDB устанавливаются из одного репозитория, содержащего расширения, скомпилированные и подписанные командой разработчиков DuckDB. Это гарантирует стабильность и безопасность основного набора расширений. Эти расширения находятся в стандартном репозитории core, который указывает на http://extensions.duckdb.org.

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

Установка расширений из репозитория

Чтобы установить расширения из стандартного репозитория (стандартный репозиторий: core):

INSTALL httpfs;

Чтобы явно установить расширение из основного репозитория, выполните одно из следующих:

INSTALL httpfs FROM core;

Или:

INSTALL httpfs FROM 'http://extensions.duckdb.org';

Чтобы установить расширение из ночного репозитория:

INSTALL spatial FROM core_nightly;

Или:

INSTALL spatial FROM 'http://nightly-extensions.duckdb.org';

Чтобы установить расширение из пользовательского репозитория, неизвестного DuckDB:

INSTALL ⟨custom_extension⟩ FROM 'https://my-custom-extension-repository';

В качестве альтернативы, можно изменить стандартный репозиторий, используемый DuckDB, с помощью параметра custom_extension_repository:

SET custom_extension_repository = 'http://nightly-extensions.duckdb.org';

Хотя в качестве репозитория можно использовать любой URL или локальный путь, DuckDB в настоящее время содержит следующие предопределённые репозитории:

Работа с несколькими репозиториями

При работе с расширениями из разных репозиториев, особенно при смешивании core и core_nightly, важно отслеживать происхождение и версию разных расширений. По этой причине DuckDB отслеживает это в метаданных установки расширения. Например:

INSTALL httpfs FROM core;
INSTALL aws FROM core_nightly;
SELECT extension_name, extension_version, installed_from, install_mode FROM duckdb_extensions();

Это выводит:

Создание пользовательского репозитория

Репозиторий DuckDB — это HTTP, HTTPS, S3 или локальный файловый каталог, который предоставляет файлы расширений в определённой структуре. Эта структура описана в разделе “Загрузка расширений напрямую из S3” и одинакова для локальных путей и удалённых серверов, например:

base_repository_path_or_url
└── v1.0.0
    └── osx_arm64
        ├── autocomplete.duckdb_extension
        ├── httpfs.duckdb_extension
        ├── icu.duckdb_extension
        ├── inet.duckdb_extension
        ├── json.duckdb_extension
        ├── parquet.duckdb_extension
        ├── tpcds.duckdb_extension
        ├── tpcds.duckdb_extension
        └── tpch.duckdb_extension

См. extension-template репозиторий для всего необходимого кода и скриптов для настройки репозитория.

При установке расширения из пользовательского репозитория DuckDB будет искать как gzipped, так и не-gzipped версии. Например:

INSTALL icu FROM '⟨custom repository⟩';

Выполнение этой команды сначала будет искать icu.duckdb_extension.gz, затем icu.duckdb_extension в структуре каталога репозитория.

Если пользовательский репозиторий предоставляется через HTTPS или S3, требуется расширение httpfs. DuckDB попытается автозагрузить расширение httpfs при попытке установки из HTTPS или S3.

Принудительная установка для обновления расширений

При установке расширения DuckDB, оно копируется в локальный каталог для кеширования и предотвращения будущих сетевых запросов. Любые последующие вызовы INSTALL ⟨extension_name⟩ будут использовать локальную версию вместо повторной загрузки расширения. Чтобы принудительно перегрузить загрузку расширения, выполните:

FORCE INSTALL extension_name;

Принудительная установка также может использоваться для перезаписи расширения с тем же именем из другого репозитория.

Например, сначала устанавливается spatial из основного репозитория:

INSTALL spatial;

Затем, чтобы перезаписать эту установку расширением spatial из репозитория core_nightly:

FORCE INSTALL spatial FROM core_nightly;

Альтернативные подходы к загрузке и установке расширений

Загрузка расширений напрямую из S3

Загрузка расширения напрямую может быть полезна при создании службы Lambda или контейнера, использующего DuckDB. Расширения DuckDB хранятся в общедоступных ведрах S3, но структура каталогов этих ведер не индексируется. В результате необходимо использовать прямой URL-адрес файла. Чтобы загрузить файл расширения напрямую, используйте следующий формат:

http://extensions.duckdb.org/v⟨duckdb_version⟩/⟨platform_name⟩/⟨extension_name⟩.duckdb_extension.gz

Например:

http://extensions.duckdb.org/v1.1.3/windows_amd64/json.duckdb_extension.gz

Установка расширения по явным пути

INSTALL можно использовать с путём к файлу .duckdb_extension:

INSTALL 'path/to/httpfs.duckdb_extension';

Обратите внимание, что сжатые файлы .duckdb_extension.gz необходимо предварительно распаковать. Также можно указать удалённые пути.

Загрузка расширения по явным пути

LOAD можно использовать с путём к файлу .duckdb_extension . Например, если файл доступен по (относительному) пути path/to/httpfs.duckdb_extension, его можно загрузить следующим образом:

LOAD 'path/to/httpfs.duckdb_extension';

Это пропустит все установленные расширения и загрузит указанное расширение напрямую.

Обратите внимание, что использование удалённых путей для сжатых файлов в настоящее время невозможно.

Компиляция и установка расширений из исходного кода

Для компиляции и установки расширений из исходного кода см. руководство по сборке.

Статическая привязка расширений

Для статической привязки расширений следуйте инструкциям в разделе «Использование конфигурационных файлов расширения» документации разработчика.

Встроенные vs. Внешние расширения

Изначально, расширения DuckDB размещались исключительно в основном репозитории DuckDB, github.com/duckdb/duckdb. Эти расширения называются встроенными (in-tree). Позже, был добавлен концепция внешних расширений (out-of-tree), где расширения размещались в собственных репозиториях.

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

• Встроенные расширения используют версию DuckDB, а не свою собственную.
• Встроенные расширения не имеют отдельного раздела с заметками о релизе, их изменения отражаются в стандартных заметках о релизе DuckDB.
• Основные внешние расширения, как правило, хранятся в репозитории в github.com/duckdb/duckdb_⟨ext_name⟩ , но название может отличаться. См. полный список основных расширений для получения подробностей.

Ограничения

Механизм расширений DuckDB имеет следующие ограничения:

• После загрузки расширение нельзя переустановить.
• Расширения нельзя выгрузить.