Native Protocol

​

개요

​

보안

​

전송 보안(TLS)

​

인증

​

서버 간 시크릿

​

버전 관리 및 기능 게이트

​

버전 협상(Version negotiation)

negotiated_version = min(client_version, server_version)

​

기능 게이트(Feature gates)

​

기능 표

​

패킷 엔벌로프

[VarUInt: packet_type_code]    always encoded as VarUInt
[message body]                 format depends on packet_type_code

​

청크 프레이밍 (v54470+)

<chunk>...   one or more chunks; their payloads concatenated form the whole packet
[u32 LE = 0] zero-size terminator marking end of packet

[u32 LE: chunk_size]   chunk_size in [1, UINT32_MAX]
[chunk_size bytes]     packet bytes (see note below)

• chunked / notchunked는 엄격한 값으로, 해당 측이 반드시 그 모드를 사용해야 함을 의미합니다.
• _optional 변형은 유연한 값으로, 상대 측이 선택한 모드를 그대로 따릅니다.

​

연결 수명 주기

​

상태

​

핸드셰이크 단계

1. 클라이언트는 자신이 지원하는 최대 프로토콜 버전을 담아 ClientHello를 전송합니다.
2. 클라이언트는 응답을 읽은 후 패킷 유형에 따라 다음과 같이 처리합니다.

   패킷 유형	동작
   Hello (0)	ServerHello를 디코딩하고 negotiated_version = min(client_ver, server_ver)를 계산한 후 3단계로 진행합니다.
   Exception (2)	Exception을 디코딩하여 오류로 반환하고 연결을 종료합니다.
   그 외의 패킷	프로토콜 위반이므로 연결을 종료합니다.

3. negotiated_version ≥ 54458(ADDENDUM 기능)이면 클라이언트는 Addendum을 전송합니다. 이 판단은 클라이언트가 선언한 버전이 아니라 협상된 버전을 기준으로 합니다.

​

Ping 단계

1. 클라이언트가 Ping을 전송합니다.
2. 클라이언트가 응답을 읽습니다.

   패킷 유형	동작
   Pong (4)	연결이 활성 상태임을 확인합니다. READY로 돌아갑니다.
   Exception (2)	Exception을 디코딩하여 오류로 반환합니다.
   그 외 모든 패킷	프로토콜 위반(Protocol violation)입니다.

​

쿼리 단계

1. 클라이언트는 고유한 query_id(일반적으로 UUID)를 포함하여 Query를 전송합니다.
2. 클라이언트는 외부 테이블(external table)을 모두 전송한 다음, 빈 Data 마커를 전송합니다. 빈 Data 패킷의 값은 table_name = "", num_columns = 0, num_rows = 0입니다. 서버는 이 마커를 수신해야 쿼리 실행을 시작합니다. 외부 테이블은 동일한 table_name을 가진 여러 Data 패킷으로 나뉘어 전송될 수 있습니다. 이때 첫 번째 패킷이 테이블의 스키마를 확정하며, 이후 같은 이름으로 전송되는 모든 패킷은 동일한 컬럼명과 유형을 동일한 순서로 포함해야 합니다. 그렇지 않으면 서버는 INCORRECT_DATA 오류와 함께 쿼리를 거부합니다(Data 참조).
3. 클라이언트는 READING_RESPONSE 상태로 전환하고 쓰기 버퍼를 플러시합니다.
4. 클라이언트는 루프를 돌며 응답 패킷을 읽고, 패킷 유형에 따라 처리합니다:

   패킷 유형	동작
   Data (1)	블록을 디코딩합니다. 첫 번째 Data는 스키마 헤더이고, 이후의 Data는 결과 블록(누적)이며, 빈 블록은 경계 마커입니다. num_rows == 0은 쿼리 종료를 의미하지 않습니다.
   Progress (3)	실행 메트릭입니다. 각 패킷은 직전 패킷 대비 증분이므로 로컬에서 누적하십시오.
   EndOfStream (5)	쿼리가 완료되었음을 나타냅니다. 루프를 종료하고 READY 상태로 돌아갑니다.
   ProfileInfo (6)	실행 후 프로파일링 데이터입니다.
   Totals (7)	집계 합계 블록입니다(Data와 동일한 wire 형식).
   Extremes (8)	최솟값/최댓값 블록입니다(Data와 동일한 wire 형식).
   Log (10)	서버 로그 라인입니다.
   TableColumns (11)	컬럼 기본값 메타데이터입니다.
   ProfileEvents (14)	성능 카운터입니다.
   Exception (2)	디코딩하여 오류로 반환합니다. 루프를 종료하고 READY 상태로 돌아갑니다.
   그 외 모든 유형	쿼리 단계에서 예상치 못한 패킷입니다. 연결을 종료합니다.

​

INSERT 단계

1. 클라이언트는 body를 INSERT SQL로 설정한 Query를 전송합니다.
2. 클라이언트는 외부 테이블(external table)이 있으면 이를 전송합니다(INSERT에서는 드문 경우입니다). Query 단계와 달리 여기서는 빈 Data 마커를 전송하지 않습니다. INSERT Query 패킷은 보류 중인 데이터가 있는 상태로 전송되므로, 빈 데이터 종료 블록은 5단계로 미뤄집니다. 스키마 블록보다 먼저 이를 전송하면 서버는 이를 행 스트림의 끝으로 해석하여 행 없이 INSERT를 완료한 뒤, 첫 번째 실제 행 패킷을 예상치 못한 최상위 패킷으로 파싱하게 됩니다.
3. 클라이언트는 스키마 Data 패킷을 읽을 때까지 메타데이터 패킷(TableColumns, Progress, ProfileInfo, Log, ProfileEvents)을 소비합니다. 스키마 Data 패킷은 행은 0개이지만 전체 컬럼 구조(이름과 타입)를 갖춘 Block입니다. 스키마 블록은 일종의 계약으로, 클라이언트가 이후 전송하는 행은 이 컬럼 형태와 일치해야 합니다.
4. 클라이언트는 데이터 블록을 전송합니다. 각 블록마다 VarUInt(ClientPacket::Data = 2)를 쓰고, 이어서 빈 외부 테이블 이름에 해당하는 String("")을 쓴 다음 Block을 씁니다. 컬럼 타입은 위치 순서대로 스키마 블록의 컬럼과 일치해야 합니다.
5. 클라이언트는 입력 종료 표시를 전송합니다. 이는 빈 Block(컬럼 0개, 행 0개)을 담은 Data 패킷입니다.
6. 클라이언트는 EndOfStream(성공) 또는 Exception(실패)을 받을 때까지 응답 스트림을 소비합니다.

​

메시지 참고

• VarUInt — 가변 길이 부호 없는 정수입니다(VarUInt 참조).
• String — VarUInt 길이 접두사가 붙은 바이트열입니다(String 참조).
• UInt8, Int32 등 — 고정 폭 리틀 엔디언 정수입니다.
• Bool — 0x00 또는 0x01 값을 갖는 1바이트입니다.

• 클라이언트 — 외부 클라이언트가 설정합니다.
• 서버 간 — 서버 간 통신에서만 의미가 있으며, 외부 클라이언트는 기본값을 기록합니다.
• 공통 — 양쪽 모두 사용합니다.

​

ClientHello (패킷 유형 0)

​

ServerHello (패킷 유형 0)

​

Addendum (패킷 유형 없음)

​

Ping (패킷 유형 4)

​

Pong (패킷 유형 4)

​

Exception (패킷 유형 2)

​

Query (패킷 유형 1)

​

ClientInfo (Query에 포함)

[UInt8: has_trace]              0 = no trace data follows, 1 = trace data follows
If has_trace == 1:
  [16 bytes: trace_id]          byte-swapped per-8-bytes
  [8 bytes:  span_id]           byte-swapped
  [String:   trace_state]       W3C trace state
  [UInt8:    trace_flags]       W3C trace flags

​

서버 간 인증

1. 서버 간 모드 진입. 연결하는 서버는 ClientHello 안에서 이를 알립니다. 이때 user 필드에는 서버 간 마커가 들어가고 password는 비어 있습니다. 이어서 같은 ClientHello 패킷 안에서 user/password 필드 바로 뒤에 두 개의 문자열, 즉 클러스터 이름과 새로 생성한 32바이트 salt(임의 값의 encodeSHA256)를 추가합니다. 서버는 ServerHello를 보내기 전에 이 두 문자열을 읽으므로 클라이언트는 이를 미리 기록해야 합니다. ServerHello를 먼저 기다리면 서버가 이 문자열을 읽느라 대기 상태에 있으므로 교착 상태(deadlock)가 발생합니다.
2. 논스 획득. INTERSERVER_SECRET_V2(v54462)가 협상되면 ServerHello에 8바이트 UInt64 논스가 포함됩니다.
3. 해시 계산. InitialQuery가 아닌 모든 Query 패킷에 대해 클라이언트는 필드 4에 encodeSHA256(salt + nonce + cluster_secret + query + query_id + initial_user + external_roles + current_roles), 즉 32바이트 다이제스트를 기록합니다. (nonce는 10진수 문자열 형식이며 v54462 이상으로 협상된 경우에만 포함됩니다. external_roles는 INTERSERVER_EXTERNALLY_GRANTED_ROLES(v54472)가 협상된 경우에만 추가됩니다. current_roles는 직렬화된 역할 이름 목록(존재 여부 바이트를 제외한 [VarUInt count][String]*count)이며, INTERSERVER_CURRENT_ROLES(v54488)가 협상되고 목록이 있는 경우에만 추가됩니다.) InitialQuery이거나 클러스터 시크릿이 구성되지 않은 경우에는 클라이언트가 빈 문자열을 대신 기록합니다.
4. 검증. 서버는 최대 32바이트까지 필드 4를 읽고, 자신이 보유한 클러스터 시크릿으로 동일한 값을 이어 붙여 해시를 다시 계산합니다. 다이제스트가 일치하지 않으면 연결을 거부합니다.

​

Setting

• 0x01 — Important: 쿼리 결과에 영향을 주는 설정이므로 이전 버전의 피어가 이를 임의로 무시해서는 안 됩니다.
• 0x02 — Custom: 사용자 지정 설정입니다.
• 0x0c — 독립적인 플래그가 아니라 2비트 등급(tier) 필드입니다: 0x00 = Production, 0x04 = Obsolete, 0x08 = Experimental, 0x0c = Beta. 반드시 2비트 전체(flags & 0x0c)를 읽어야 합니다. 단순히 flags & 0x04로 검사하면 Beta(0x0c)를 Obsolete로 잘못 분류하게 됩니다.
• 0x80 — HotReload(재시작 없이 구성을 다시 로드함. flags enum에 정의되어 있으며, 주로 조정(coordination) 설정에서 사용됩니다).

​

Parameter

​

데이터(Data) (패킷 유형 1 서버→클라이언트, 패킷 유형 2 클라이언트→서버)

[VarUInt: packet_type]     1 (server→client) or 2 (client→server)
[String:  table_name]      External table name; empty in most cases
[Block]                    See the Native Format spec for the Block layout

​

Progress (패킷 유형 3)

​

ProfileInfo (패킷 유형 6)

​

Totals (패킷 유형 7)

[VarUInt: 7]                packet type
[String:  table_name]       always empty
[Block]                     see the Native Format spec

​

Extremes (패킷 유형 8)

[VarUInt: 8]                packet type
[String:  table_name]       always empty
[Block]                     num_rows = 2

​

Log (패킷 유형 10)

[VarUInt: 10]               packet type
[String:  table_name]       always empty
[Block]                     num_columns = 8, num_rows = number of log lines

​

ProfileEvents (패킷 유형 14)

[VarUInt: 14]               packet type
[String:  table_name]       always empty
[Block]                     num_columns = 6, num_rows = number of events

​

TableColumns (패킷 유형 11)

​

TimezoneUpdate (패킷 유형 17)

​

SSH 챌린지-응답 인증 (패킷 유형 11, 12, 18)

1. 클라이언트는 SSH 마커 접두사와 빈 비밀번호를 포함한 ClientHello를 전송합니다.
2. 클라이언트는 SSHChallengeRequest(패킷 11)를 전송합니다. 이 시점에 서버는 아직 ServerHello를 전송하지 않은 상태이며, 인증을 먼저 처리하기 위해 이 패킷이 도착할 때까지 대기합니다.
3. 서버는 무작위 바이트를 담은 SSHChallenge(패킷 18)로 응답합니다.
4. 클라이언트는 서명할 문자열을 구성한 뒤 원시 챌린지가 아닌 이 문자열에 서명하고, 서명을 담은 SSHChallengeResponse(패킷 12)를 전송합니다. 서명 대상 메시지는 다음 4개 파트를 정확히 이 순서대로, 구분자 없이 바이트 단위로 연결한 것입니다.
   to_sign = decimal(protocol_version) + default_database + user + challenge
   

   파트	출처
   decimal(protocol_version)	클라이언트의 프로토콜 버전을 10진수 ASCII 문자열로 표현한 값입니다(예: "54466"). VarUInt나 고정 폭 정수가 아니라 버전 번호를 문자열로 나타낸 것입니다. 서버는 ClientHello에서 수신한 것과 동일한 프로토콜 버전을 사용하여 검사합니다.
   default_database	ClientHello의 database 필드입니다(없으면 빈 문자열).
   user	" SSH KEY AUTHENTICATION " 마커 접두사를 제거한 실제 사용자 이름으로, 서버가 접두사를 제거하여 복원하는 이름과 동일합니다.
   challenge	SSHChallenge 패킷의 원시 challenge 바이트입니다.

5. 서버는 동일한 decimal(protocol_version) + default_database + user + challenge 문자열을 재구성한 뒤, 사용자에게 등록된 공개 키로 서명을 검증합니다. 검증에 성공하면 비밀번호 흐름과 동일한 응답인 ServerHello를 전송하고, 이후 핸드셰이크가 정상적으로 진행됩니다(Addendum 등). 실패하면 Exception을 반환하고 연결을 종료합니다. 원시 챌린지 바이트에만 서명하는 클라이언트는 인증에 실패합니다.

​

MergeTreeAllRangesAnnouncementResponse (패킷 유형 14)

1. 팔로워가 읽기 파이프라인을 열고 initiator에 MergeTreeAllRangesAnnouncement를 전송합니다.
2. announcement의 mode가 Default가 아닐 때만(WithOrder = 1 또는 ReverseOrder = 2이며, 둘 다 순서 보장 병렬 읽기에 사용됨) initiator가 MergeTreeAllRangesAnnouncementResponse로 응답합니다. mode = Default = 0이면 initiator는 응답하지 않으며 팔로워도 대기하지 않습니다. Default 모드에서는 MergeTreeReadTaskRequest마다 범위를 할당하므로 파트 목록을 미리 받을 필요가 없습니다.
3. 팔로워는 첫 번째 MergeTreeReadTaskRequest(서버 패킷 16 — 팔로워→initiator로 전송되며, initiator는 클라이언트 패킷 10인 MergeTreeReadTaskResponse로 응답함)를 보내기 전에 응답을 기다리며(응답이 예정된 경우), 반환된 파트 목록을 바탕으로 자신의 #split_i 스트림이 소유한 파트만 대상으로 소스를 생성합니다.

​

Body

​

RangesInDataPartsDescription body

​

RangesInDataPartDescription body

​

MergeTreePartInfo body

​

MarkRanges body

​

패킷 유형 참고

​

Client → Server

​

Server → Client

​

QueryPlan

​

구성

• 전송 계층 설정 — TCP 연결 자체의 동작에 영향을 주는 TCP 소켓 옵션과 타임아웃입니다.
• 애플리케이션 계층 설정 — Query 패킷의 설정 목록에 담겨 전달되는 쿼리별 매개변수로, 서버가 wire 상에서 전송하는 내용이나 프레이밍 방식에 영향을 줍니다.
• 범위 외 설정 — 프로토콜 설정과 혼동하기 쉽지만 실제로는 SQL 실행이나 저장소를 제어하는 설정입니다.

​

전송 계층 설정

​

소켓 옵션

​

타임아웃

tcp_keep_alive_timeout (290s)
      < receive_timeout (300s)
      < idle_connection_timeout (3600s)
      < tcp_close_connection_after_queries_seconds (0 = unlimited by default)

​

연결 제한

​

애플리케이션 계층 설정

​

압축

​

로그 스트리밍

​

진행 상황 보고

​

결과 엔벌로프

​

비동기 INSERT

​

분산 추적(Distributed tracing)

​

범위 외 설정

• max_threads — 쿼리 실행 시의 병렬 처리 수준입니다.
• max_memory_usage — 쿼리별 메모리 사용 상한입니다.
• max_block_size, preferred_block_size_bytes — 쿼리 처리 중 내부 블록 크기를 조정하며, wire 블록은 이 설정과 무관합니다.
• compile_expressions — JIT 컴파일 설정으로, CPU에만 영향을 줍니다.
• async_insert_max_data_size — 서버 측 큐 버퍼 설정입니다.
• input_format_native_* / output_format_native_* 계열을 제외한 모든 input_format_* 및 output_format_* 설정 — native가 아닌 설정은 다른 포맷(예: HTTP에서 사용하는 포맷)을 선택하거나 조정할 뿐, native protocol의 Data 블록에는 영향을 주지 않습니다.

​

용어집

• 일반 쿼리(SELECT 등): Query 패킷과 외부 테이블 Data 패킷 뒤에 전송되어 “더 이상 외부 데이터가 없음”을 알립니다. 이후 서버가 쿼리 실행을 시작합니다.
• INSERT: 클라이언트는 스키마 블록 이전에 마커를 보내지 않습니다. 서버가 먼저 스키마 블록을 보내면 클라이언트가 행 Data 블록을 스트리밍하고, 그런 다음에야 빈 Data 패킷을 보내 행 스트림을 종료합니다. 스키마 블록보다 먼저 빈 마커를 보내면 곧바로 행이 끝난 것으로 해석되어 데이터가 손실됩니다.