HTTP User-Agent

DuckDB가 HTTP 요청을 보낼 때 어떤 user-agent 문자열을 사용하는지, 그리고 확장별로 어떻게 달라지는지 알아볼게요.

출처: 공식문서

HTTP User-Agent

핵심 DuckDB는 기본 user-agent를 다음과 같이 설정합니다.

duckdb/v1.4.4(osx_arm64) cli 6ddac802ff

이 문자열에는 버전, 아키텍처, 클라이언트, buildref가 담겨 있어요. user-agent 문자열은 custom_user_agent 설정으로 바꿀 수도 있습니다. 자세한 내용은 Configuration을 참고하세요. 현재 생성되는 user-agent 문자열은 PRAGMA user_agent;로 확인할 수 있어요. (Configuration/Pragmas 참고)

또한 일부 확장은 자체 user-agent를 설정합니다. 대표적인 예시는 다음과 같아요.

확장 (Extensions)

Azure

Azure는 Azure SDK를 사용하며 이 SDK가 자체 user-agent를 설정합니다. Identity와 storage 호출에서 각각 다음과 같은 문자열을 볼 수 있어요.

Azure Identity 경유: azsdk-cpp-identity/1.11.0 (Darwin 25.2.0 arm64 Darwin Kernel Version 25.2.0: Tue Nov 18 21:07:05 PST 2025; root:xnu-12377.61.12~1/RELEASE_ARM64_T6020 Cpp/201402)
Azure Blob/ADLSv2 경유: azsdk-cpp-storage-blobs/12.15.0 (Darwin 25.2.0 arm64 Darwin Kernel Version 25.2.0: Tue Nov 18 21:07:05 PST 2025; root:xnu-12377.61.12~1/RELEASE_ARM64_T6020 Cpp/201402)

Delta (및 Unity Catalog)

Delta 확장은 위의 DuckDB 기본 user-agent로 태그된 DuckDB 코어 호출과, Delta Kernel에서 발생한 호출을 함께 사용합니다. 후자는 다음과 같은 형태일 수 있어요.

object_store/0.12.5

Unity Catalog 호출도 DuckDB 기본 user-agent와 위의 Delta 스타일 에이전트를 섞어 사용합니다.

HTTPFS - HTTPS/S3

HTTPFS 확장을 통한 호출은 위에서 본 DuckDB 기본 문자열을 사용합니다.

더 알아보기 (Learn more)

user-agent는 서버에서 요청 출처를 식별하는 데 쓰이므로, 직접 구성할 때는 custom_user_agent 설정을 이용하면 됩니다.
현재 값은 PRAGMA user_agent;로 확인할 수 있어요.