MongoDB Wire Protocol (original) (raw)

Note

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 mongosinstances is 27017. The port number for mongod andmongos 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 ofOP_MSG.

Note

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

The types used in this document, such as int32 and cstring, 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

}

MongoDB uses these opCode values:

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

}

Each compressor is assigned a predefined compressor ID as follows:

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

}

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 MUSTerror if an unknown bit is set.

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

An OP_MSG message contains one or more sections. Each section starts with a kind byte indicating its type. Everything after the kindbyte 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.

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.

If you do not use TLS/SSL connections, mongod instances andmongos instances exchange messages with checksums.

If you use TLS/SSL connections, mongod instances andmongos instances skip the checksum.

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 ofOP_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.

Footnotes