Расширения

Обзор

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

Расширения загружаются на всех клиентах (например, Python и R). Расширения, распространяемые через репозитории Core и Community, построены и протестированы на macOS, Windows и Linux. Поддерживаются все операционные системы для архитектур AMD64 и ARM64.

Список расширений

Для получения списка расширений, используйте duckdb_extensions.

SELECT extension_name, installed, description
FROM duckdb_extensions();

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

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

Бинарное распределение DuckDB поставляется с несколькими встроенными расширениями. Они статически связаны с двоичным файлом и могут использоваться как есть. Например, чтобы использовать встроенное json расширение для чтения файла JSON:

SELECT *
FROM 'test.json';

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

Установка дополнительных расширений

Для того, чтобы расширение, которое не является встроенным, стало доступным в DuckDB, необходимо выполнить два шага:

1. Установка расширения — это процесс загрузки двоичного файла расширения и проверки его метаданных. Во время установки DuckDB сохраняет загруженное расширение и некоторые метаданные в локальном каталоге. Из этого каталога DuckDB может затем загрузить расширение, когда это необходимо. Это означает, что установка должна происходить только один раз.

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

Установка и загрузка расширений имеют несколько ограничений.

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

Явное INSTALL и LOAD

В DuckDB расширения также могут быть явно установлены и загружены. Так могут быть установлены как неавтозагружаемые, так и автозагружаемые расширения. Для явной установки и загрузки расширения DuckDB имеет специальные SQL-команды LOAD и INSTALL. Например, чтобы установить и загрузить spatial расширение, выполните:

INSTALL spatial;
LOAD spatial;

С помощью этих команд DuckDB гарантирует, что расширение spatial установлено (игнорируя команду INSTALL, если оно уже установлено), а затем приступает к LOAD расширению spatial (снова игнорируя команду, если оно уже загружено).

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

Необязательно указать репозиторий, из которого должно быть установлено расширение, добавив FROM <repository> к команде INSTALL/FORCE INSTALL. Этот репозиторий может быть псевдонимом, например community, или прямым URL-адресом, заданным в виде строки в одинарных кавычках.

После установки/загрузки расширения можно использовать функцию duckdb_extensions для получения дополнительной информации.

Автозагрузка расширений

Для многих основных расширений DuckDB, явная загрузка и установка не нужна. DuckDB содержит механизм автозагрузки, который может установить и загрузить основные расширения, как только они будут использованы в запросе. Например, при выполнении:

SELECT *
FROM 'https://raw.githubusercontent.com/duckdb/duckdb-web/main/data/weather.csv';

DuckDB автоматически установит и загрузит httpfs расширение. Нет необходимости в явных командах INSTALL или LOAD.

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

Чтобы узнать, какие расширения могут быть загружены автоматически, обратитесь к списку основных расширений.

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

DuckDB поддерживает установку расширений сторонних разработчиков Расширения сообщества. Эти расширения предоставляются членами сообщества, но они построены, подписаны и распространены в централизованном репозитории.

Установка расширений через API клиентов

Для многих клиентов использование SQL для загрузки и установки расширений является предпочтительным методом. Однако некоторые клиенты имеют собственный API для установки и загрузки расширений. Например, клиентский API Python, который имеет специализированные методы install_extension(name: str) и load_extension(name: str). Для получения дополнительной информации по конкретному API клиента, обратитесь к документации API клиентов.

Обновление расширений

В то время как встроенные расширения связаны с выпуском DuckDB из-за того, что они встроены в двоичный файл DuckDB, устанавливаемые расширения могут и получают обновления. Чтобы убедиться, что все установленные расширения находятся на последней версии, вызовите:

UPDATE EXTENSIONS;

Для получения дополнительной информации о версии расширения см. Версионирование расширений.

Место установки

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

~/.duckdb/extensions/⟨duckdb_version⟩/⟨platform_name⟩/

Для стабильных релизов DuckDB значение ⟨duckdb_version⟩ будет равно тегу версии этого релиза. Для ночных сборок DuckDB оно будет равно короткому git-хэшу сборки. Например, расширения для версии DuckDB v0.10.3 на macOS ARM64 (Apple Silicon) установлены в ~/.duckdb/extensions/v0.10.3/osx_arm64/. Пример пути установки для ночной сборки DuckDB может быть ~/.duckdb/extensions/fc2e4b26a6/linux_amd64_gcc4.

Чтобы изменить расположение по умолчанию, в котором DuckDB хранит свои расширения, используйте опцию конфигурации extension_directory:

SET extension_directory = '/path/to/your/extension/directory';

Обратите внимание, что изменение значения опции конфигурации home_directory не повлияет на расположение расширений.

Бинарная совместимость

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

Подробные сведения о доступных платформах см. на странице Работа с расширениями.

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

Тот же API, который используется для основных расширений, доступен для разработки расширений. Это позволяет пользователям расширять функциональность DuckDB таким образом, чтобы она наилучшим образом соответствовала их области. Шаблон для создания расширений доступен в репозитории extension-template. Этот шаблон также содержит документацию по началу работы над созданием собственного расширения.

Подпись расширений

Расширения подписываются с помощью криптографического ключа, что также упрощает распространение (вот почему они предоставляются по HTTP, а не по HTTPS). По умолчанию DuckDB использует свои встроенные открытые ключи для проверки целостности расширения перед его загрузкой. Все расширения, предоставленные командой DuckDB core, подписаны.

Неподписанные расширения

Предупреждение. Загружайте неподписанные расширения только из надёжных источников. Также избегайте их загрузки по HTTP.

Если вы хотите загрузить свои собственные расширения или расширения от третьих сторон, вам необходимо включить флаг allow_unsigned_extensions. Для загрузки неподписанных расширений с помощью клиента CLI передайте флаг -unsigned при запуске:

duckdb -unsigned

Теперь можно загружать любые расширения, подписанные или нет:

LOAD './some/local/ext.duckdb_extension';

Для API клиентов необходимо установить опции конфигурации базы данных allow_unsigned_extensions, см. соответствующую документацию API клиента. Например, для клиента Python см. раздел Загрузки и установки расширений в документации по API Python.

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

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