콘텐츠로 이동

S3와 httpfs ​

DuckLocal은 DuckDB의 httpfs 확장 기능을 통해 S3와 S3 호환 스토리지의 객체를 읽을 수 있습니다. 제목 표시줄의 S3 버튼에서 설정합니다.

자격 증명 설정 ​

대화 상자에는 필드가 네 개 있습니다:

필드기본값설명
Endpoints3.amazonaws.comhttp://를 지정하면 그것을 쓰고, 그 외에는 HTTPS를 사용합니다
Regionus-east-1입력한 그대로 전송됩니다
Access Key ID—필수
Secret Access Key—필수, 가려져 표시되며 표시 전환 토글이 있습니다

확인하면 다음에 해당하는 작업이 실행됩니다:

sql
INSTALL httpfs; LOAD httpfs;
CREATE OR REPLACE SECRET ducklocal_s3 (
  TYPE s3, PROVIDER config,
  KEY_ID '…', SECRET '…',
  REGION '…', ENDPOINT '…'
);

자격 증명은 세션 동안에만 유효합니다. 디스크에 기록되지 않고, 데이터베이스를 열거나 전환하면 지워지므로 그 뒤에는 다시 설정해야 합니다. 다시 설정하는 것 외에 자격 증명을 지우는 별도 방법은 없습니다.

탐색 ​

설정하면 사이드바에 S3 루트가 나타납니다. 내용은 펼칠 때만 불러옵니다. 루트에는 버킷이 나열되고, 각 버킷이나 접두사에는 그 객체가 나열됩니다. 버킷과 접두사는 정렬되며, 객체는 읽기 쉬운 크기로 표시됩니다. 새로 고침 버튼으로 해당 단계를 다시 불러오거나 오류 후에 다시 시도하세요.

목록은 단계마다 1,000개로 제한되며, 응답이 더 있다고 알려도 마찬가지입니다. 더 깊은 페이지 이동도, 접두사 필터 상자도, 검색도 없습니다. 한 단계에 객체가 1,000개를 넘는 버킷은 실제로는 그렇지 않아도 완전한 것처럼 보입니다.

객체 쿼리 ​

키에 데이터 파일 확장자가 있는 객체를 클릭하면 활성 에디터에 다음 내용이 채워집니다:

sql
SELECT *
FROM 's3://bucket/key'
LIMIT 100;

이것은 평범한 쿼리입니다. 읽기가 httpfs를 거치므로 DuckDB의 read_parquet / read_csv_auto 동작이 그대로 적용되고, 푸시다운도 포함됩니다. 필터와 열 선택은 파일 읽기 쪽으로 밀려 들어갑니다. 쿼리는 활성 탭의 내용을 바꿉니다.

클릭할 수 있는 것은 데이터 파일로 인식된 키뿐입니다. 인식되는 확장자는 로컬 파일의 경우와 같습니다. 데이터 소스를 참고하세요.

제한 사항 ​

  • 탐색은 읽기 전용입니다. 브라우저에는 업로드, 파일로 내려받기, 삭제, 복사, 버킷 생성 동작이 없습니다. 쿼리는 여전히 원격 데이터를 내려받습니다.
  • 세션 토큰은 지원하지 않습니다. X-Amz-Security-Token 헤더를 전혀 보내지 않으므로 임시 STS 자격 증명은 동작하지 않습니다. 수명이 긴 키를 사용하거나 키와 시크릿만 받는 엔드포인트를 사용하세요.
  • 엔드포인트 방식은 대부분 자동입니다. S3 URL은 버킷을 두 가지 방식으로 지정할 수 있습니다. 가상 호스트 방식과 경로 방식입니다. 호스트에 amazonaws.com이 들어 있으면 가상 호스트 방식을, 아니면 경로 방식을 사용합니다. 자체 호스팅 게이트웨이에서는 보통 이대로가 맞지만, 다른 방식을 요구하는 게이트웨이에는 전환 수단이 없습니다.
  • 리전이 틀리면 DuckDB가 알려 주는 리전으로 한 번 다시 시도합니다. 그것도 실패하면 오류가 그대로 표시됩니다.
  • 네트워크가 필요합니다. INSTALL httpfs는 처음 사용할 때 확장 기능을 받아 옵니다. 탐색은 설정한 엔드포인트로 HTTP 또는 HTTPS 요청을 보냅니다(http://면 HTTP, 그 외에는 HTTPS). 이 요청에는 버킷 이름과 키 접두사 같은 메타데이터와 서명된 헤더의 인증 정보가 포함됩니다. 탐색은 로컬 데이터베이스 파일이나 쿼리 결과를 업로드하지 않습니다. 원격 객체에 대한 쿼리는 httpfs를 통해 데이터를 컴퓨터로 내려받습니다.

문제 해결 ​

증상가능한 원인
설정 직후 탐색이 바로 실패리전이나 엔드포인트가 잘못되었습니다. 사이드바에 표시되는 메시지를 확인하세요
자체 호스팅 엔드포인트에서 오류주소 지정 방식이 다르거나, 세션 토큰이 필요한 엔드포인트입니다
httpfs 설치 오류네트워크가 없거나, 확장 기능 다운로드를 차단하는 프록시가 있습니다
자격 증명이 사라진 것 같음데이터베이스를 열거나 전환해 설계대로 지워졌습니다

서명된 앱으로 패키징된 DuckLocal에서는 httpfs 확장 기능을 로드하려면 com.apple.security.cs.disable-library-validation 엔타이틀먼트가 필요합니다. 배포용 패키징 스크립트에는 이미 포함되어 있습니다.

Apache-2.0 라이선스로 공개되었습니다.