MongoDB 유선 프로토콜
참고
이 MongoDB 유선 프로토콜 사양은 Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License에 따라 사용이 허가되었습니다. 이 자료는 상업용 데이터베이스 또는 DBaaS(Database-as-a-Service) 제품군을 만드는 것과 같은 상업적 목적으로 사용하거나 변경할 수 없습니다.
서론
MongoDB 유선 프로토콜은 간단한 소켓 기반, 요청-응답 스타일의 프로토콜입니다. 클라이언트는 일반 TCP/IP 소켓을 통해 데이터베이스 서버와 통신합니다.
TCP/IP 소켓
클라이언트는 일반 TCP/IP 소켓으로 데이터베이스에 연결해야 합니다.
포트
mongod
및 mongos
인스턴스의 기본 포트 번호는 27017 입니다. mongod
및 mongos
의 포트 번호는 구성 가능하며 다를 수 있습니다.
바이트 순서 지정
MongoDB 유선 프로토콜의 모든 정수는 리틀 엔디안 바이트 순서, 즉 제일 낮은 바이트를 먼저 사용합니다.
메시지 유형과 형식
MongoDB는 클라이언트 요청과 데이터베이스 응답 모두에 OP_MSG 옵코드를 사용합니다. 오래된 MongoDB 버전에서는 사용되었지만 현재는 사용이 중단되고 OP_MSG
로 대체된 메시지 형식이 몇 가지 있습니다.
참고
이 페이지에서는 C형
struct
를 사용해 메시지 구조를 설명합니다.이 문서에 사용된 유형(
cstring
, 등)은int32
BSON 사양 에 정의된 유형과 동일합니다. .반복을 나타내기 위해 이 문서에서는 BSON 사양 의 별표 표기법을 사용합니다. . 예를 들어
int64*
는 지정된 유형 중 하나 이상을 소켓에 차례로 쓸 수 있음을 나타냅니다.표준 메시지 헤더의 유형은
MsgHeader
입니다. 정수 상수는 대문자로 표시됩니다(예:ZERO
의 정수 값의 경우 0).
표준 메시지 헤더
일반적으로 각 메시지에는 표준 메시지 헤더가 있고 그 뒤에 요청별 데이터가 뒤따릅니다. 표준 메시지 헤더의 구조는 다음과 같습니다.
struct MsgHeader { int32 messageLength; // total message size, including this int32 requestID; // identifier for this message int32 responseTo; // requestID from the original request // (used in responses from db) int32 opCode; // request type - see table below for details }
필드 | 설명 |
---|---|
messageLength | 메시지의 총 크기(바이트)입니다. 이 총계에는 메시지 길이를 보관하는 4바이트가 포함됩니다. |
requestID | 이 메시지를 고유하게 식별하는 클라이언트 또는 데이터베이스 생성 식별자입니다. 클라이언트 생성 메시지의 경우(예: OP_QUERY 및 OP_GET_MORE), OP_REPLY 메시지의 responseTo 필드에 반환됩니다. 클라이언트는 requestID 및 responseTo 필드를 사용하여 쿼리 응답을 원래 쿼리와 연결할 수 있습니다. |
responseTo | 데이터베이스에서 보낸 메시지의 경우 이는 클라이언트의 OP_QUERY 또는 OP_GET_MORE 메시지에서 가져온 requestID 입니다. 클라이언트는 requestID 및 responseTo 필드를 사용하여 쿼리 응답을 원래 쿼리와 연결할 수 있습니다. |
opCode | 메시지 유형입니다. 자세한 내용은 요청 옵코드 를 참조하세요. |
옵코드 요청
참고
MongoDB 2 부터 시작합니다.6 및
maxWireVersion
3
, MongoDB 드라이버는 승인된 쓰기에 대해OP_INSERT
,OP_UPDATE
및 대신 데이터베이스 명령insert
,update
및delete
OP_DELETE
을 사용합니다. 대부분의 드라이버는 승인되지 않은 쓰기에 옵코드를 계속 사용합니다.버전 4.2에서 MongoDB는 더 이상 사용되지 않는 내부
OP_COMMAND
및OP_COMMANDREPLY
프로토콜을 제거합니다.버전 5.0 에서는 MongoDB는 다음 옵코드를 더 이상 사용하지 않습니다.
OP_REPLY
OP_UPDATE
OP_INSERT
OP_QUERY
[1]OP_GET_MORE
OP_DELETE
OP_KILL_CURSORS
이러한 옵코드 대신 OP_MSG를 사용하세요.
[1] MongoDB 5.0 는 OP_QUERY
찾기 작업과OP_QUERY
명령을 모두 더 이상 사용하지 않습니다. 예외적으로OP_QUERY
는 연결 핸드셰이크의 일부로hello
및isMaster
명령을 실행하는 데 계속 지원됩니다.
MongoDB는 다음과 같은 opCode
값을 지원합니다.
옵코드 이름 | 값 | 논평 |
---|---|---|
OP_MSG | 2013 | MongoDB 3.6 에 도입된 형식을 사용하여 메시지를 보냅니다. |
OP_REPLY Deprecated in MongoDB 5.0. | 1 | 클라이언트 요청에 응답합니다. responseTo 가 설정되었습니다. |
OP_UPDATE Deprecated in MongoDB 5.0. | 2001 | 문서를 업데이트합니다. |
OP_INSERT Deprecated in MongoDB 5.0. | 2002 | 새 문서를 삽입합니다. |
RESERVED | 2003 | 이전에는 OP_GET_BY_OID에 사용되었습니다. |
OP_QUERY Deprecated in MongoDB 5.0. | 2004 | 컬렉션을 쿼리합니다. |
OP_GET_MORE Deprecated in MongoDB 5.0. | 2005 | 쿼리에서 더 많은 데이터를 가져옵니다. 커서를 참조하세요. |
OP_DELETE Deprecated in MongoDB 5.0. | 2006 | 문서를 삭제합니다. |
OP_KILL_CURSORS Deprecated in MongoDB 5.0. | 2007 | 클라이언트가 커서 작업을 완료했음을 데이터베이스에 알립니다. |
OP_COMPRESSED | 2012 | 압축을 사용하여 다른 명령 코드를 래핑합니다. |
클라이언트 요청 메시지
OP_MSG
OP_MSG
다른 옵코드의 기능을 포함하도록 설계된 확장 가능한 메시지 형식입니다. 이 옵코드의 형식은 다음과 같습니다.
OP_MSG { MsgHeader header; // standard message header uint32 flagBits; // message flags Sections[] sections; // data sections optional<uint32> checksum; // optional CRC-32C checksum }
필드 | 설명 |
---|---|
header | 표준 메시지 헤더에 설명된 표준 메시지 헤더입니다. |
flagBits | 플래그 비트에 설명된 대로 메시지 플래그를 포함하는 정수 비트마스크입니다. |
sections | 섹션에 설명된 메시지 본문 섹션입니다. |
checksum | 체크섬에 설명된 대로 선택 사항인 CRC-32C 체크섬입니다. |
플래그 비트
flagBits
정수는 OP_MSG
의 형식과 동작을 수정하는 비트마스크 인코딩 플래그입니다.
처음 16비트(0~15)는 필수이며, 알 수 없는 비트가 설정된 경우 파서에서 반드시 오류가 발생해야 합니다.
마지막 16비트(16-31)는 선택 사항이며 구문 분석기는 알 수 없는 설정 비트를 모두 무시해야 합니다. 프록시 및 기타 메시지 전달자는 메시지를 전달하기 전에 알 수 없는 선택적 비트를 모두 지워야 합니다.
비트 | 이름 | 요청 | 응답 | 설명 |
---|---|---|---|---|
0 | checksumPresent | ✓ | ✓ | |
1 | moreToCome | ✓ | ✓ | 수신자의 추가 조치 없이 다른 메시지가 이 메시지에 이어서 전송됩니다. 수신자는 전송이 차단되어 교착 상태가 발생할 수 있으므로 moreToCome 이 0으로 설정된 메시지를 받을 때까지 다른 메시지를 보내지 않아야 합니다. moreToCome 비트가 설정된 요청은 회신을 받지 못합니다. 응답은 exhaustAllowed 비트가 설정된 요청에 대한 응답으로만 이 설정을 갖습니다. |
16 | exhaustAllowed | ✓ | 클라이언트는 이렇게 하면 요청자의 네트워크 계층이 준비된 경우에만 여러 응답이 전송됩니다. 중요MongoDB 3.6 는 이 플래그를 무시하고 단일 메시지로 응답합니다. |
섹션
OP_MSG
메시지에 하나 이상의 섹션이 포함되어 있습니다. 각 섹션은 해당 유형을 나타내는 kind
바이트로 시작합니다. kind
바이트 이후의 모든 항목이 섹션의 페이로드를 구성합니다.
사용 가능한 섹션의 종류는 다음과 같습니다.
Kind 0: Body
본문 섹션은 단일 BSON 객체로 인코딩됩니다. BSON 객체의 크기는 섹션의 크기로도 사용됩니다. 이 섹션 종류는 표준 명령 요청 및 회신 본문입니다.
모든 최상위 필드에는 고유한 이름이 있어야 합니다.
종류 1: 문서 시퀀스
유형 | 설명 |
---|---|
int32 | 섹션의 크기(바이트)입니다. |
C 문자열 | 문서 시퀀스 식별자입니다. 모든 현재 명령에서 이 필드는 본문 섹션에서 대체되는 필드(중첩될 수 있음)입니다. 이 필드는 본문 섹션에도 존재하면 안 됩니다. |
0개 이상의 BSON 객체 |
|
체크섬
각 메시지는 체크섬 자체를 제외한 메시지의 모든 바이트를 포함하는 CRC-32C[2] 체크섬으로 끝날 수 있습니다.
MongoDB 4.2부터:
mongod
인스턴스,mongos
인스턴스 및mongo
shell 인스턴스는 TLS/SSL 연결을 사용 하지 않는 경우 체크섬이 포함된 메시지를 교환합니다.mongod
instances,mongos
instances, 및mongo
shell instances는 TLS/SSL 연결을 사용하는 경우 체크섬을 건너뜁니다.
드라이버 및 이전 바이너리는 체크섬이 포함된 메시지가 표시되는 경우 체크섬을 무시합니다.
체크섬의 존재 여부는 checksumPresent
플래그 비트로 표시됩니다.
OP_UPDATE
MongoDB 5 에서 더 이상 사용되지 않습니다.0.
OP_UPDATE 메시지는 컬렉션의 문서를 업데이트하는 데 사용됩니다. OP_UPDATE 메시지의 형식은 다음과 같습니다.
struct OP_UPDATE { MsgHeader header; // standard message header int32 ZERO; // 0 - reserved for future use cstring fullCollectionName; // "dbname.collectionname" int32 flags; // bit vector. see below document selector; // the query to select the document document update; // specification of the update to perform }
필드 | 설명 |
---|---|
header | 표준 메시지헤더에 설명된 대로 메시지 헤더입니다. |
ZERO | 정수 값은 0입니다. 나중에 사용하기 위해 예약되어 있습니다. |
fullCollectionName | 전체 컬렉션 이름입니다. 즉, 네임스페이스입니다. 전체 컬렉션 이름은 데이터베이스 이름과 컬렉션 이름을 연결한 것이며, 연결에 . 를 사용합니다. 예를 들어 데이터베이스 foo 및 컬렉션 bar 의 경우 전체 컬렉션 이름은 foo.bar 입니다. |
flags | 작업에 대한 플래그를 지정하는 비트 벡터입니다. 비트 값은 다음에 해당합니다.
|
selector | 업데이트할 문서를 선택하기 위한 쿼리를 지정하는 BSON 문서입니다. |
update | 수행해야 할 업데이트를 지정하는 BSON 문서입니다. 업데이트 지정에 대한 자세한 내용은 업데이트 작업 문서를 참조하세요. |
OP_UPDATE 메시지에 대한 응답이 없습니다.
OP_INSERT
MongoDB 5 에서 더 이상 사용되지 않습니다.0.
OP_INSERT 메시지는 컬렉션에 하나 이상의 문서를 삽입하는 데 사용됩니다. OP_INSERT 메시지의 형식은 다음과 같습니다.
struct { MsgHeader header; // standard message header int32 flags; // bit vector - see below cstring fullCollectionName; // "dbname.collectionname" document* documents; // one or more documents to insert into the collection }
필드 | 설명 |
---|---|
header | 표준 메시지헤더에 설명된 대로 메시지 헤더입니다. |
flags | 작업에 대한 플래그를 지정하는 비트 벡터입니다. 비트 값은 다음에 해당합니다.
|
fullCollectionName | 전체 컬렉션 이름입니다. 즉, 네임스페이스입니다. 전체 컬렉션 이름은 데이터베이스 이름과 컬렉션 이름을 연결한 것이며, 연결에 . 를 사용합니다. 예를 들어 데이터베이스 foo 및 컬렉션 bar 의 경우 전체 컬렉션 이름은 foo.bar 입니다. |
documents | 컬렉션에 삽입할 하나 이상의 문서입니다. 둘 이상이 있는 경우 순서대로 소켓에 차례로 기록됩니다. |
OP_INSERT 메시지에 대한 응답이 없습니다.
OP_QUERY
MongoDB 5 에서 더 이상 사용되지 않습니다.0.
OP_QUERY 메시지는 컬렉션의 문서를 데이터베이스에 쿼리하는 데 사용됩니다. OP_QUERY 메시지의 형식은 다음과 같습니다.
struct OP_QUERY { MsgHeader header; // standard message header int32 flags; // bit vector of query options. See below for details. cstring fullCollectionName ; // "dbname.collectionname" int32 numberToSkip; // number of documents to skip int32 numberToReturn; // number of documents to return // in the first OP_REPLY batch document query; // query object. See below for details. [ document returnFieldsSelector; ] // Optional. Selector indicating the fields // to return. See below for details. }
필드 | 설명 | |
---|---|---|
header | 표준 메시지헤더에 설명된 대로 메시지 헤더입니다. | |
flags | 작업에 대한 플래그를 지정하는 비트 벡터입니다. 비트 값은 다음에 해당합니다.
| |
fullCollectionName | 전체 컬렉션 이름입니다. 즉, 네임스페이스입니다. 전체 컬렉션 이름은 데이터베이스 이름과 컬렉션 이름을 연결한 것이며, 연결에 . 를 사용합니다. 예를 들어 데이터베이스 foo 및 컬렉션 bar 의 경우 전체 컬렉션 이름은 foo.bar 입니다. | |
numberToSkip | 쿼리 결과를 반환할 때 결과 데이터세트의 첫 번째 문서부터 생략할 문서 수를 설정합니다. | |
numberToReturn | 쿼리에 대한 첫 번째 OP_REPLY 메시지의 문서 수를 제한합니다. 그러나 결과가 numberToReturn 보다 많은 경우 데이터베이스는 여전히 커서를 설정하고 cursorID 을 클라이언트에 반환합니다. 클라이언트 드라이버가 SQL LIMIT 키워드와 같은 '제한' 기능을 제공하는 경우 호출 애플리케이션에 지정된 수보다 많은 문서가 반환되지 않도록 하는 것은 클라이언트 드라이버의 몫입니다. numberToReturn 가 0 이면 db는 기본 반환 크기를 사용합니다. 숫자가 음수이면 데이터베이스는 해당 숫자를 반환하고 커서를 닫습니다. 해당 쿼리에 대한 더 이상의 결과를 가져올 수 없습니다. numberToReturn 가 1 인 경우 서버는 이를 -1 로 처리합니다(커서가 자동으로 닫힘). | |
query | 쿼리를 나타내는 BSON 문서입니다. 쿼리에는 하나 이상의 요소가 포함되며, 결과 세트에 문서가 포함되려면 모든 요소가 일치해야 합니다. 가능한 요소에는 $query , $orderby , $hint 및 $explain 가 있습니다. | |
returnFieldsSelector | 선택 사항입니다. 반환된 문서의 필드를 제한하는 BSON 문서입니다.
|
데이터베이스는 OP_QUERY 메시지에 OP_REPLY 메시지로 응답합니다.
OP_GET_MORE
MongoDB 5 에서 더 이상 사용되지 않습니다.0.
OP_GET_MORE 메시지는 컬렉션의 문서를 데이터베이스에 쿼리하는 데 사용됩니다. OP_GET_MORE 메시지의 형식은 다음과 같습니다.
struct { MsgHeader header; // standard message header int32 ZERO; // 0 - reserved for future use cstring fullCollectionName; // "dbname.collectionname" int32 numberToReturn; // number of documents to return int64 cursorID; // cursorID from the OP_REPLY }
필드 | 설명 |
---|---|
header | 표준 메시지헤더에 설명된 대로 메시지 헤더입니다. |
ZERO | 정수 값은 0입니다. 나중에 사용하기 위해 예약되어 있습니다. |
fullCollectionName | 전체 컬렉션 이름입니다. 즉, 네임스페이스입니다. 전체 컬렉션 이름은 데이터베이스 이름과 컬렉션 이름을 연결한 것이며, 연결에 . 를 사용합니다. 예를 들어 데이터베이스 foo 및 컬렉션 bar 의 경우 전체 컬렉션 이름은 foo.bar 입니다. |
numberToReturn | 쿼리에 대한 첫 번째 OP_REPLY 메시지의 문서 수를 제한합니다. 그러나 결과가 numberToReturn 보다 많은 경우 데이터베이스는 여전히 커서를 설정하고 cursorID 을 클라이언트에 반환합니다. 클라이언트 드라이버가 SQL LIMIT 키워드와 같은 '제한' 기능을 제공하는 경우 호출 애플리케이션에 지정된 수보다 많은 문서가 반환되지 않도록 하는 것은 클라이언트 드라이버의 몫입니다. numberToReturn 가 0 이면 db는 기본 반환 크기를 사용합니다. |
cursorID | OP_REPLY 에 포함된 커서 식별자입니다. 이 값은 데이터베이스에서 가져온 값이어야 합니다. |
데이터베이스는 OP_GET_MORE 메시지에 OP_REPLY 메시지로 응답합니다.
OP_DELETE
MongoDB 5 에서 더 이상 사용되지 않습니다.0.
OP_DELETE 메시지는 컬렉션에서 하나 이상의 문서를 제거하는 데 사용됩니다. OP_DELETE 메시지의 형식은 다음과 같습니다.
struct { MsgHeader header; // standard message header int32 ZERO; // 0 - reserved for future use cstring fullCollectionName; // "dbname.collectionname" int32 flags; // bit vector - see below for details. document selector; // query object. See below for details. }
필드 | 설명 |
---|---|
header | 표준 메시지헤더에 설명된 대로 메시지 헤더입니다. |
ZERO | 정수 값은 0입니다. 나중에 사용하기 위해 예약되어 있습니다. |
fullCollectionName | 전체 컬렉션 이름입니다. 즉, 네임스페이스입니다. 전체 컬렉션 이름은 데이터베이스 이름과 컬렉션 이름을 연결한 것이며, 연결에 . 를 사용합니다. 예를 들어 데이터베이스 foo 및 컬렉션 bar 의 경우 전체 컬렉션 이름은 foo.bar 입니다. |
flags | 작업에 대한 플래그를 지정하는 비트 벡터입니다. 비트 값은 다음에 해당합니다.
|
selector | 제거할 문서를 선택하는 데 사용된 쿼리를 나타내는 BSON 문서입니다. 선택기에는 하나 이상의 요소가 포함되며 collection에서 문서를 제거하려면 모든 요소가 일치해야 합니다. |
OP_DELETE 메시지에 대한 응답이 없습니다.
OP_KILL_CURSORS
MongoDB 5 에서 더 이상 사용되지 않습니다.0.
OP_KILL_CURSORS 메시지는 데이터베이스에서 활성 커서를 닫는 데 사용됩니다. 이는 쿼리가 끝날 때 데이터베이스 리소스가 회수되도록 하는 데 필요합니다. OP_KILL_CURSORS 메시지의 형식은 다음과 같습니다.
struct { MsgHeader header; // standard message header int32 ZERO; // 0 - reserved for future use int32 numberOfCursorIDs; // number of cursorIDs in message int64* cursorIDs; // sequence of cursorIDs to close }
필드 | 설명 |
---|---|
header | 표준 메시지헤더에 설명된 대로 메시지 헤더입니다. |
ZERO | 정수 값은 0입니다. 나중에 사용하기 위해 예약되어 있습니다. |
numberOfCursorIDs | 메시지에 있는 커서 ID의 수입니다. |
cursorIDs | 닫을 커서 ID의 "배열"입니다. 둘 이상이 있는 경우 순서대로 소켓에 차례로 기록됩니다. |
소진될 때까지 커서를 읽으면( OP_QUERY 또는 OP_GET_MORE가 커서 ID에 대해 0을 반환할 때까지 읽음) 커서를 종료할 필요가 없습니다.
OP_COMPRESSED
모든 옵코드는 OP_COMPRESSED 헤더로 압축하고 래핑할 수 있습니다. OP_COMPRESSED 메시지에는 압축된 원본 옵코드 메시지와 함께 이를 처리하고 압축을 푸는 데 필요한 메타데이터가 포함되어 있습니다.
OP_COMPRESSED 메시지의 형식은 다음과 같습니다.
struct { MsgHeader header; // standard message header int32 originalOpcode; // value of wrapped opcode int32 uncompressedSize; // size of deflated compressedMessage, excluding MsgHeader uint8 compressorId; // ID of compressor that compressed message char *compressedMessage; // opcode itself, excluding MsgHeader }
필드 | 설명 |
---|---|
MsgHeader | 표준 메시지헤더에 설명된 대로 메시지 헤더입니다. |
originalOpcode | 래핑된 옵코드의 값을 포함합니다. |
uncompressedSize | compressedMessage 를 제외한 수축된 MsgHeader 의 크기입니다. |
compressorId | 메시지를 압축한 압축기의 ID입니다. compressorId 값 목록이 아래에 제공됩니다. |
compressedMessage | MsgHeader 를 제외한 옵코드입니다. |
각 압축기에는 다음과 같이 사전 정의된 압축기 ID가 할당됩니다.
compressorId | 핸드셰이크 값 | 설명 |
---|---|---|
0 | 눕 | 메시지 내용은 압축되지 않습니다. 테스트에 사용됩니다. |
1 | 스내피 | 메시지 내용은 스내피를 사용해 압축됩니다. |
2 | zlib | 메시지의 내용은 zlib를 사용하여 압축됩니다. |
3 | zstd | 메시지 내용은 zstd를 사용하여 압축됩니다. |
4-255 | 예약됨 | 향후 사용을 위해 예약되었습니다. |
데이터베이스 응답 메시지
OP_REPLY
MongoDB 5 에서 더 이상 사용되지 않습니다.0.
OP_REPLY
메시지는 OP_QUERY 또는 OP_GET_MORE 메시지에 대한 응답으로 데이터베이스에서 전송됩니다. OP_REPLY 메시지의 형식은 다음과 같습니다.
struct { MsgHeader header; // standard message header int32 responseFlags; // bit vector - see details below int64 cursorID; // cursor id if client needs to do get more's int32 startingFrom; // where in the cursor this reply is starting int32 numberReturned; // number of documents in the reply document* documents; // documents }
필드 | 설명 |
---|---|
header | 표준 메시지헤더에 설명된 대로 메시지 헤더입니다. |
responseFlags | 플래그를 지정하는 비트 벡터입니다. 비트 값은 다음에 해당합니다.
|
cursorID | 이 OP_REPLY가 속한 cursorID 입니다. 쿼리 결과 세트가 하나의 OP_REPLY 메시지에 맞는 경우 cursorID 은 0 가 됩니다. 이 cursorID 는 추가 데이터를 가져오는 데 사용되는 모든 OP_GET_MORE 메시지에 사용해야 하며, 더 이상 필요하지 않은 경우 클라이언트가 OP_KILL_CURSORS 메시지를 통해 닫아야 합니다. |
startingFrom | 커서의 시작 위치입니다. |
numberReturned | 회신에 포함된 문서 수입니다. |
documents | 반환된 문서입니다. |
각주
[2] | (1, 2) 32-비트 CRC는 https://tools.ietf.org/html/rfc4960#page-140에 설명된 대로 Castagnoli 다항식으로 계산됩니다. |