확장 설치하기

확장 설치하기 (Installing Extensions)

DuckDB 핵심(core) 확장을 설치하려면 INSTALL 명령을 사용해요. 예를 들어:

출처: 문서

INSTALL httpfs;

이 명령은 기본 저장소(core)에서 확장을 설치해요.

본문

확장 저장소 (Extension Repositories)

기본적으로 DuckDB 확장은 DuckDB 핵심 팀이 빌드하고 서명한 확장이 담긴 단일 저장소에서 설치돼요. 이렇게 하면 핵심 확장 집합의 안정성과 보안이 보장돼요. 이 확장들은 기본 core 저장소에 있으며, 그 저장소는 http://extensions.duckdb.org를 가리켜요.

핵심 저장소 외에도 DuckDB는 다른 저장소에서 확장을 설치하는 것을 지원해요. 예를 들어 core_nightly 저장소에는 DuckDB 최신 안정 릴리스용으로 빌드된 핵심 확장의 nightly 빌드가 들어 있어요. 이 덕분에 사용자들은 확장의 새 기능이 공식 출시되기 전에 미리 사용해 볼 수 있어요.

다른 저장소에서 확장 설치하기 (Installing Extensions from Different Repositories)

기본 저장소(core)에서 확장을 설치하려면:

INSTALL httpfs;

core 저장소에서 확장을 명시적으로 설치하려면:

INSTALL httpfs FROM core;
-- 또는
INSTALL httpfs FROM 'http://extensions.duckdb.org';

core nightly 저장소에서 확장을 설치하려면:

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

커스텀 저장소에서 확장을 설치하려면:

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

또는 custom_extension_repository 설정을 사용해 DuckDB가 사용하는 기본 저장소를 바꿀 수 있어요.

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

DuckDB에는 다음과 같은 미리 정의된 저장소가 있어요.

Alias	URL	Description
`core`	`http://extensions.duckdb.org`	DuckDB 핵심 확장
`core_nightly`	`http://nightly-extensions.duckdb.org`	`core`의 nightly 빌드
`community`	`http://community-extensions.duckdb.org`	DuckDB 커뮤니티 확장
`local_build_debug`	`./build/debug/repository`	DuckDB를 debug 모드로 소스 빌드할 때 생성되는 저장소 (개발용)
`local_build_release`	`./build/release/repository`	DuckDB를 release 모드로 소스 빌드할 때 생성되는 저장소 (개발용)

여러 저장소 다루기 (Working with Multiple Repositories)

특히 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();

이 결과는 다음과 같아요.

extensions_name	extensions_version	installed_from	install_mode
httpfs	62d61a417f	core	REPOSITORY
aws	42c78d3	core_nightly	REPOSITORY
...	...	...	...

확장 업그레이드를 위한 강제 설치 (Force Installing to Upgrade Extensions)

DuckDB가 확장을 설치할 때, 로컬 디렉터리에 복사해 캐시하고 이후의 네트워크 트래픽을 피해요. 이후의 INSTALL ⟨extension_name⟩ 호출은 확장을 다시 다운로드하는 대신 로컬 버전을 사용해요. 확장을 강제로 다시 다운로드하려면:

FORCE INSTALL extension_name;

강제 설치는 같은 이름의 확장을 다른 저장소의 확장으로 덮어쓰는 데에도 사용할 수 있어요.

예를 들어 먼저 spatial을 core 저장소에서 설치한 경우:

INSTALL spatial;

그런 다음 이 설치를 core_nightly 저장소의 spatial 확장으로 덮어쓰려면:

FORCE INSTALL spatial FROM core_nightly;

저장소 간 전환 (Switching between Repositories)

확장의 저장소를 전환하려면 FORCE INSTALL 명령을 사용해요. 예를 들어 httpfs를 core_nightly 저장소에서 설치했지만 core 사용으로 되돌리고 싶다면:

FORCE INSTALL httpfs FROM core;

클라이언트 API로 확장 설치하기 (Installing Extensions through Client APIs)

많은 클라이언트에서 확장을 로드하고 설치하는 SQL 방식이 선호돼요. 하지만 일부 클라이언트에는 확장을 설치하고 로드하는 전용 API가 있어요. 예를 들어 Python 클라이언트에는 전용 install_extension(name: str)과 load_extension(name: str) 메서드가 있어요. 특정 클라이언트 API에 대한 자세한 내용은 클라이언트 API 문서를 참고해요.

설치 위치 (Installation Location)

기본적으로 확장은 사용자 홈 디렉터리 아래에 설치돼요.

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

안정 DuckDB 릴리스의 경우 ⟨duckdb_version⟩은 해당 릴리스의 버전 태그와 같아요. nightly 빌드의 경우 빌드의 짧은 git 해시와 같아요. 예를 들어 macOS ARM64 (Apple Silicon)의 DuckDB v0.10.3 확장은 ~/.duckdb/extensions/v0.10.3/osx_arm64/에 설치돼요. nightly 빌드의 예시 설치 경로는 ~/.duckdb/extensions/fc2e4b26a6/linux_amd64가 될 수 있어요.

DuckDB가 확장을 저장하는 기본 위치를 바꾸려면 extension_directory 설정 옵션을 사용해요.

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

확장 로딩을 위한 여러 디렉터리를 지정하려면(예: 패키지 매니저나 air-gapped 환경) extension_directories 옵션을 사용해요.

SET extension_directories = ['/usr/lib/duckdb/extensions', '/opt/duckdb/extensions'];

home_directory 설정 옵션의 값은 확장 위치에 영향을 주지 않는다는 점을 기억하세요.

확장 제거하기 (Uninstalling Extensions)

현재 DuckDB는 확장을 제거하는 명령을 제공하지 않아요. 확장을 제거하려면 확장의 설치 위치로 이동해 .duckdb_extension 바이너리 파일을 삭제해요.

예를 들어:

rm ~/.duckdb/extensions/v1.2.1/osx_arm64/excel.duckdb_extension

공유 설치 위치 덕분에 확장은 _같은 DuckDB 버전_의 클라이언트 API 사이에서 공유할 수 있어요. 단, 같은 platform 또는 ABI를 공유해야 해요. 예를 들어 CLI 클라이언트 1.2.1로 macOS에 확장을 설치했다면, Python, R 등의 클라이언트 라이브러리가 사용자 홈 디렉터리에 접근할 수 있고 DuckDB 1.2.1을 사용한다면 그 확장을 사용할 수 있어요.

제한사항 (Limitations)

DuckDB의 확장 메커니즘에는 다음과 같은 제한이 있어요.

확장은 언로드할 수 없어요.
확장은 다시 로드할 수 없어요. 확장을 업데이트했다면 더 새로운 확장을 사용하려면 DuckDB 프로세스를 다시 시작해요.

확장 설치하기