Quack Reference

Quack Reference (Quack 참조)

이 페이지는 [quack 확장]({% link docs/current/core_extensions/quack.md %})이 노출하는 모든 함수, 설정, 로그 타입을 나열해요. 프로토콜 둘러보기는 [Overview]({% link docs/current/quack/overview.md %})부터 시작하는 것이 좋아요.

출처: 문서

본문

함수 참조 (Function Reference)

서버 관리 (Server Management)

함수	설명
`quack_serve(uri, token := 'token_value', allow_other_hostname := false, disable_ssl := false)`	`uri`에서 서버를 시작해요. 기본적으로 localhost 전용이에요. `token`을 전달해 서버의 인증 토큰을 명시적으로 설정하고(최소 4자), 그렇지 않으면 자동 생성돼요. listen URI, URL, auth 토큰을 반환해요.
`quack_stop(uri)`	`uri`에서 수신 중인 서버를 중지해요.
`quack_identify(name, provider, hostname, region, meta)`	이 노드의 `whoami` 식별 필드를 설정해요. 임의 부분집합을 제공할 수 있어요.
`whoami()`	현재 노드의 식별 + 런타임 정보를 반환하는 테이블 매크로.

클라이언트 쿼리 (Client Queries)

함수	설명
`quack_query(uri, query, token := 'token_value', disable_ssl := false)`	원격 `uri`에서 `query`를 실행하고 결과를 스트리밍해요. `token`을 전달해 클라이언트 측의 일치하는 quack 시크릿을 덮어쓸 수 있어요.
`quack_query_by_name(catalog, query)`	이미 연결된 Quack 카탈로그에 대해 `query`를 실행해요 (`⟨catalog⟩.query()`에서 사용).

유틸리티 (Utility)

함수	설명
`quack_uri_parser(uri, ssl)`	Quack URI를 `STRUCT(host, port, ipv6, ssl, url)` 항목으로 파싱해요
`quack_check_token(sid, client_token, server_token)`	기본 인증 콜백으로, 클라이언트가 제공한 토큰을 서버의 저장된 토큰과 비교해요.
`quack_nop_authorization(sid, query)`	기본 인가 콜백으로, 항상 허용해요.
`quack_clear_cache()`	캐시를 지워요. 이는 DuckDB 클라이언트가 카탈로그를 강제로 새로고침하게도 해요.

`ATTACH` 옵션

옵션	타입	기본값	설명
`TOKEN`	`VARCHAR`	(설정 안 됨)	인증 토큰. 클라이언트 측의 일치하는 quack 시크릿을 덮어써요.
`DISABLE_SSL`	`BOOLEAN`	로컬이면 `true`, 그 외 `false`	클라이언트 전송을 강제해요. 로컬 URI는 기본적으로 평문 HTTP를 사용해요.
`TYPE`	`VARCHAR`	추론됨	토큰 해석에 사용되는 시크릿 타입(예: `quack`)을 고정해요.

설정 (Settings)

모든 설정은 일반 DuckDB 세션/글로벌 옵션이에요. SET ⟨name⟩ = ⟨value⟩ 또는 SET GLOBAL로 설정해요.

인증 / 인가 (Authentication / Authorization)

인증 콜백은 매번 새 서버 측 연결에서 평가되므로 아래 두 설정은 글로벌 스코프(SET GLOBAL)예요. 이들에 대한 일반 SET은 자동으로 글로벌 슬롯에 전달돼요. 기본값을 복원하려면 RESET GLOBAL을 사용하고, 일반 RESET은 세션 뷰만 지우므로 인증 경로는 오래된 글로벌 값을 계속 읽게 돼요.

설정	타입	기본값	설명
`quack_authentication_function`	`VARCHAR`	`quack_check_token`	서버가 클라이언트를 인증하는 데 사용하는 3-인자 스칼라 함수 `(sid, client_token, server_token) -> BOOLEAN`의 이름.
`quack_authorization_function`	`VARCHAR`	`quack_nop_authorization`	서버가 각 쿼리를 인가하는 데 사용하는 2-인자 스칼라 함수 `(sid, query) -> BOOLEAN`의 이름.

기대되는 시그니처를 가진 스칼라 함수를 만든 다음 설정을 그것으로 가리켜 자체 auth를 연결할 수 있어요. 예시는 [Security]({% link docs/current/quack/security.md %})를 참고해요.

`FETCH` 배칭 (서버 측)

서버는 청크별 오버헤드를 줄이기 위해 여러 DataChunk를 각 FETCH 응답에 배칭해요.

설정	타입	기본값	설명
`quack_fetch_batch_chunks`	`UBIGINT`	`12`	`FETCH` 응답당 전송되는 최대 `DataChunk` 수.

노드 식별 (Node Identity)

이 설정들은 whoami() 매크로를 뒷받침해요. quack_identify(...)는 이들을 갱신하는 설탕이에요.

설정	타입	기본값	설명
`whoami_name`	`VARCHAR`	(empty)	사람이 읽을 수 있는 노드 이름.
`whoami_provider`	`VARCHAR`	(empty)	배포 제공자 (`ec2`, `docker`, `local`, ...).
`whoami_hostname`	`VARCHAR`	(empty)	네트워크 호스트명 / 공개 주소.
`whoami_region`	`VARCHAR`	(empty)	배포 리전.
`whoami_started_at`	`VARCHAR`	(empty)	노드 시작 시간 (ISO 8601 타임스탬프). `uptime`을 고정해요.
`whoami_meta`	`VARCHAR`	`{}`	제공자별 메타데이터를 JSON으로.
`quack_loaded_at_us`	`BIGINT`	확장 로드 시 에폭 마이크로초	`whoami_started_at`이 비었을 때의 폴백 uptime 앵커.

로깅 (Logging)

확장이 두 로그 타입을 등록해요. 연결 문제를 디버깅하거나 요청 타이밍을 측정하려면 활성화해요.

Quack 로그

모든 Quack 메시지의 구조화 로그 (클라이언트 및 서버 측 모두):

CALL enable_logging('Quack');

FROM quack_query('quack:localhost', 'SELECT 42');

SELECT * FROM duckdb_logs_parsed('Quack');

context_id	scope	connection_id	transaction_id	query_id	thread_id	timestamp	type	log_level	message_type	quack_connection_id	client_query_id	query	server	duration_ms	response_type	error
60	CONNECTION	2	18	18	NULL	2026-05-10 09:06:19.841623+02	Quack	DEBUG	CONNECTION_REQUEST		18	NULL	http://localhost:9494	41	CONNECTION_RESPONSE	NULL
60	CONNECTION	2	18	18	NULL	2026-05-10 09:06:19.842407+02	Quack	DEBUG	PREPARE_REQUEST	091A003553E7E67B615B73D6BE81FD2E	18	SELECT 42	http://localhost:9494	0	PREPARE_RESPONSE	NULL

각 항목의 필드:

필드	설명
`message_type`	요청 타입: `PREPARE_REQUEST`, `FETCH_REQUEST` 등.
`quack_connection_id`	서버가 발급한 연결 id (하나의 `ATTACH`에서 요청 간에 안정적).
`client_query_id`	클라이언트가 할당한 단조 id로, 클라이언트/서버 로그를 상호 연관지어요.
`query`	`PREPARE_REQUEST`의 SQL 페이로드.
`server`	클라이언트 측 로그의 HTTP URL, 서버 측 로그의 `NULL`.
`duration_ms`	왕복 시간 (클라이언트) 또는 처리 시간 (서버).
`response_type`	응답 타입 또는 `ERROR`.
`error`	요청이 실패한 경우 오류 메시지.

클라이언트 요청을 서버 측 처리와 연관지으려면 (quack_connection_id, client_query_id)로 조인해요.

HTTP 로그

기본 HTTP 전송은 별도로 로깅할 수 있어요:

CALL enable_logging('HTTP');
FROM quack_query('quack:localhost', 'SELECT 1');
SELECT request.type, request.url, response.status
FROM duckdb_logs_parsed('HTTP');

type	url	status
POST	http://localhost:9494/quack	OK_200
POST	http://localhost:9494/quack	OK_200

요청은 /quack 엔드포인트로의 POST예요.

쿼리를 위한 로그 영구화

duckdb_logs_parsed는 DuckDB의 인메모리 로그 버퍼에서 읽어요. 의미 있는 세션에서는 로그를 영구화하고 싶을 거예요:

CALL enable_logging(
    'Quack',
    storage => 'file',
    storage_config => {'path': '/tmp/duckdb-rpc-logs'}
);

실행 사이에 로그를 지우려면 다음을 사용해요:

CALL truncate_duckdb_logs();

로깅을 끄려면 다음을 실행해요:

CALL disable_logging();

더 알아보기 (Learn more)

Quack 확장 개요와 프로토콜 둘러보기는 [Overview]({% link docs/current/quack/overview.md %})를 참고해요.