# S3와 httpfs

> DuckDB의 httpfs를 사용해 DuckLocal에서 Amazon S3와 S3 호환 스토리지를 쿼리합니다. 자격 증명 설정, 버킷 탐색, 원격 파일에 대한 SQL 실행을 설명합니다.

Source: https://ducklocal.app/docs/ko/s3

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

## 자격 증명 설정

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

| 필드 | 기본값 | 설명 |
| --- | --- | --- |
| Endpoint | `s3.amazonaws.com` | `http://`를 지정하면 그것을 쓰고, 그 외에는 HTTPS를 사용합니다 |
| Region | `us-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` 동작이 그대로 적용되고, 푸시다운도 포함됩니다.
필터와 열 선택은 파일 읽기 쪽으로 밀려 들어갑니다. 쿼리는 활성 탭의 내용을
바꿉니다.

클릭할 수 있는 것은 데이터 파일로 인식된 키뿐입니다. 인식되는 확장자는 로컬
파일의 경우와 같습니다. [데이터 소스](data-sources.md#supported-file-formats)를
참고하세요.

## 제한 사항 {#limitations}

- **탐색은 읽기 전용입니다.** 브라우저에는 업로드, 파일로 내려받기, 삭제, 복사,
  버킷 생성 동작이 없습니다. 쿼리는 여전히 원격 데이터를 내려받습니다.
- **세션 토큰은 지원하지 않습니다.** `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` 엔타이틀먼트가 필요합니다.
배포용 패키징 스크립트에는 이미 포함되어 있습니다.
