Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

MongoDB Wire Protocol

On this page

  • Introduction
  • TCP/IP Socket
  • Messages Types and Formats
  • Standard Message Header
  • Opcodes
  • Opcode Considerations

Note

This MongoDB Wire Protocol Specification is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License. You may not use or adapt this material for any commercial purpose, such as to create a commercial database or database-as-a-service offering.

The MongoDB Wire Protocol is a simple socket-based, request-response style protocol. Clients communicate with the database server through a regular TCP/IP socket.

Clients should connect to the database with a regular TCP/IP socket.

The default port number for mongod and mongos instances is 27017. The port number for mongod and mongos is configurable and may vary.

All integers in the MongoDB wire protocol use little-endian byte order: that is, least-significant byte first.

MongoDB uses the OP_MSG opcode for both client requests and database replies. There are several message formats used in older versions of MongoDB which have been deprecated in favor of OP_MSG.

Note

This page uses a C-like struct to describe the message structure.

The types used in this document (for example, int32) are the same as those defined in the BSON specification.

In general, each message consists of a standard message header followed by request-specific data. The standard message header is structured as follows:

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 the database)
int32 opCode; // message type
}
Field
Description
messageLength
The total size of the message in bytes. This total includes the 4 bytes that holds the message length.
requestID
A client or database-generated identifier that uniquely identifies the message.
responseTo
The requestID taken from the messages from the client.
opCode
Type of message. See Opcodes for details.

MongoDB uses these opCode values:

Opcode Name
Value
Comment
OP_COMPRESSED
2012
Wraps other opcodes using compression
OP_MSG
2013
Send a message using the standard format. Used for both client requests and database replies.
OP_REPLY
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.
1
Reply to a client request. responseTo is set.
OP_UPDATE
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.
2001
Update document.
OP_INSERT
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.
2002
Insert new document.
RESERVED
2003
Formerly used for OP_GET_BY_OID.
OP_QUERY
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.
2004
Query a collection.
OP_GET_MORE
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.
2005
Get more data from a query. See Cursors.
OP_DELETE
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.
2006
Delete documents.
OP_KILL_CURSORS
Deprecated in MongoDB 5.0. Removed in MongoDB 5.1.
2007
Notify database that the client has finished with the cursor.

New in version MongoDB: 3.4

Any opcode can be compressed and wrapped in an OP_COMPRESSED header. The OP_COMPRESSED message contains the original compressed opcode message alongside the metadata necessary to process and decompress it.

The format of the OP_COMPRESSED message is:

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
}
Field
Description
MsgHeader
Message header, as described in Standard Message Header.
originalOpcode
Contains the value of the wrapped opcode.
uncompressedSize
The size of the deflated compressedMessage, which excludes the MsgHeader.
compressorId
The ID of the compressor that compressed the message. A list of compressorId values is provided below.
compressedMessage
The opcode itself, excluding the MsgHeader.

Each compressor is assigned a predefined compressor ID as follows:

compressorId
Handshake Value
Description
0
noop
The content of the message is uncompressed. This is used for testing.
1
snappy
The content of the message is compressed using snappy.
2
zlib
The content of the message is compressed using zlib.
3
zstd
The content of the message is compressed using zstd.
4-255
reserved
Reserved for future use.

OP_MSG is an extensible message format used to encode both client requests and server replies on the wire.

OP_MSG has the following format:

OP_MSG {
MsgHeader header; // standard message header
uint32 flagBits; // message flags
Sections[] sections; // data sections
optional<uint32> checksum; // optional CRC-32C checksum
}
Field
Description
header
Standard message header, as described in Standard Message Header.
flagBits
An integer bitmask containing message flags, as described in Flag Bits.
sections
Message body sections, as described in Sections.
checksum
An optional CRC-32C checksum, as described in Checksum.

The flagBits integer is a bitmask encoding flags that modify the format and behavior of OP_MSG.

The first 16 bits (0-15) are required and parsers MUST error if an unknown bit is set.

The last 16 bits (16-31) are optional, and parsers MUST ignore any unknown set bits. Proxies and other message forwarders MUST clear any unknown optional bits before forwarding messages.

Bit
Name
Request
Response
Description
0
checksumPresent

The message ends with 4 bytes containing a CRC-32C [2] checksum. See Checksum for details.
1
moreToCome

Another message will follow this one without further action from the receiver. The receiver MUST NOT send another message until receiving one with moreToCome set to 0 as sends may block, causing deadlock. Requests with the moreToCome bit set will not receive a reply. Replies will only have this set in response to requests with the exhaustAllowed bit set.
16
exhaustAllowed

The client is prepared for multiple replies to this request using the moreToCome bit. The server will never produce replies with the moreToCome bit set unless the request has this bit set.

This ensures that multiple replies are only sent when the network layer of the requester is prepared for them.

An OP_MSG message contains one or more sections. Each section starts with a kind byte indicating its type. Everything after the kind byte constitutes the section's payload.

The available kinds of sections follow.

A body section is encoded as a single BSON object. The size in the BSON object also serves as the size of the section. This section kind is the standard command request and reply body.

All top-level fields MUST have a unique name.

Type
Description
int32
Size of the section in bytes.
C String

Document sequence identifier. In all current commands this field is the (possibly nested) field that it is replacing from the body section.

This field MUST NOT also exist in the body section.

Zero or more BSON objects
  • Objects are sequenced back to back with no separators.

  • Each object is limited to the maxBSONObjectSize of the server. The combination of all objects is not limited to maxBSONObjSize.

  • The document sequence ends once size bytes have been consumed.

  • Parsers MAY choose to merge these objects into the body as an array at the path specified by the sequence identifier when converting to language-level objects.

This section is used for internal purposes.

Each message MAY end with a CRC-32C [2] checksum that covers all bytes in the message except for the checksum itself.

Starting in MongoDB 4.2:

  • mongod instances and mongos instances will exchange messages with checksums if not using TLS/SSL connection.

  • mongod instances and mongos instances will skip the checksum if using TLS/SSL connection.

Drivers and older binaries will ignore the checksum if presented with messages with checksum.

The presence of a checksum is indicated by the checksumPresent flag bit.

Starting in MongoDB 5.1, these opcodes are removed in favor of OP_MSG:

  • OP_DELETE

  • OP_GET_MORE

  • OP_INSERT

  • OP_KILL_CURSORS

  • OP_QUERY [1]

  • OP_REPLY

  • OP_UPDATE

If you are running an older version of MongoDB and need detailed information on the previous opcodes, see Legacy Opcodes.

In version 4.2, MongoDB removes the deprecated internal OP_COMMAND and OP_COMMANDREPLY protocol.

Footnotes

[1] MongoDB 5.1 removes support for both OP_QUERY find operations and OP_QUERY commands. As an exception, OP_QUERY is still supported for running the hello and isMaster commands as part of the connection handshake.
[2](1, 2) 32-bit CRC computed with the Castagnoli polynomial as described by https://tools.ietf.org/html/rfc4960#page-140.
←  MongoDB Server ParametersLegacy Opcodes →