Protocolo de conexão do MongoDB
Nesta página
Observação
Esta especificação do protocolo de conexão do MongoDB está licenciada nos termos da licença Creative Commons Attribution-NonCommercial-ShareAlike 3.0 dos Estados Unidos. Você não pode usar ou adaptar este material para qualquer finalidade comercial, como criar um banco de dados comercial ou uma oferta de banco de dados como serviço.
Introdução
O MongoDB Wire Protocol é um protocolo simples de estilo solicitação-resposta baseado em soquete. Os clientes se comunicam com o servidor do banco de dados por meio de um soquete TCP/IP regular.
Soquete TCP/IP
Os clientes devem se conectar ao banco de dados com um soquete TCP/IP regular.
Porta
O número de porta padrão para instâncias mongod
e mongos
é 27017. O número da porta para mongod
e mongos
é configurável e pode variar.
Ordenação de bytes
Todos os números inteiros no protocolo de conexão do MongoDB usam a ordem de bytes little-endian: ou seja, primeiro o byte menos significativo.
Tipos e formatos de mensagens
O MongoDB usa o opcode OP_MSG para solicitações de clientes e respostas do banco de dados. Existem vários formatos de mensagem usados em versões mais antigas do MongoDB que foram preteridos em favor de OP_MSG
.
Observação
Esta página usa um
struct
tipo C para descrever a estrutura da mensagem.Os tipos utilizados neste documento, como
int32
ecstring
, são os mesmos definidos na especificação BSON.Para indicar repetição, o documento usa a notação de asterisco da especificação BSON. Por exemplo,
int64*
indica que um ou mais do tipo especificado podem ser gravados no soquete, um após o outro.O cabeçalho da mensagem padrão é digitado como
MsgHeader
. As constantes inteiras estão em maiúsculas (por exemploZERO
para o valor inteiro de 0).
Cabeçalho de Mensagem Padrão
Em geral, cada mensagem consiste em um cabeçalho de mensagem padrão seguido de dados específicos do solicitante. O cabeçalho da mensagem padrão é estruturado da seguinte forma:
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 }
Campo | Descrição |
---|---|
messageLength | O tamanho total da mensagem em bytes. Este total inclui os
bytes que contêm o comprimento da mensagem. |
requestID | Um identificador gerado pelo cliente ou pelo banco de dados que identifica exclusivamente esta mensagem. Para o caso de mensagens geradas pelo cliente (por exemplo, OP_QUERY e OP_GET_MORE), ele será retornado no campo responseTo da mensagem OP_REPLY . Os clientes podem usar os campos requestID e responseTo para associar respostas de query à query de origem. |
responseTo | No caso de uma mensagem do banco de dados, será o requestID retirado das mensagens OP_QUERY ou OP_GET_MORE do cliente. Os clientes podem utilizar os campos requestID e responseTo para associar respostas de consulta com a consulta de origem. |
opCode | Tipo de mensagem. Consulte Solicitar códigos de opção para obter detalhes. |
Solicitar códigos de operação
Observação
A partir do MongoDB 2.6 e
maxWireVersion
3
, os drivers do MongoDB usam os comandos de banco de dados de dadosinsert
,update
edelete
em vez deOP_INSERT
,OP_UPDATE
eOP_DELETE
para gravações confirmadas. A maioria dos drivers continua a usar opcodes para escritas não reconhecidas.Na versão 4.2, MongoDB remove o protocolo
OP_COMMAND
eOP_COMMANDREPLY
interno obsoleto.Na versão 5.0, O MongoDB descontinua os seguintes opcodes:
OP_REPLY
OP_UPDATE
OP_INSERT
OP_QUERY
[1]OP_GET_MORE
OP_DELETE
OP_KILL_CURSORS
Em vez desses códigos de operação, use OP_MSG.
[1] O MongoDB 5.0 descontinua as operações de localização OP_QUERY
e os comandosOP_QUERY
. Como exceção, o siteOP_QUERY
ainda é compatível com a execução dos comandoshello
eisMaster
como parte do handshake da conexão.
O MongoDB aceita estes valores opCode
:
Nome do Código de Operação | Valor | Comment |
---|---|---|
OP_MSG | 2013 | Envie uma mensagem usando o formato introduzido no MongoDB 3.6. |
OP_REPLY Deprecated in MongoDB 5.0. | 1 | Responda a uma solicitação do cliente. responseTo está definido. |
OP_UPDATE Deprecated in MongoDB 5.0. | 2001 | Update document. |
OP_INSERT Deprecated in MongoDB 5.0. | 2002 | Inserir novo documento. |
RESERVED | 2003 | Anteriormente usado para OP_GET_BY_OID. |
OP_QUERY Deprecated in MongoDB 5.0. | 2004 | Consultar uma coleção. |
OP_GET_MORE Deprecated in MongoDB 5.0. | 2005 | Obtenha mais dados de uma consulta. Consulte Cursores. |
OP_DELETE Deprecated in MongoDB 5.0. | 2006 | Excluir documentos. |
OP_KILL_CURSORS Deprecated in MongoDB 5.0. | 2007 | Notifique o banco de dados que o cliente terminou com o cursor. |
OP_COMPRESSED | 2012 | Envolve outros códigos de operação usando compressão |
Mensagens de solicitação do cliente
OP_MSG
OP_MSG
é um formato de mensagem extensível projetado para incluir a funcionalidade de outros códigos de operação. Este código de operação tem o seguinte formato:
OP_MSG { MsgHeader header; // standard message header uint32 flagBits; // message flags Sections[] sections; // data sections optional<uint32> checksum; // optional CRC-32C checksum }
Campo | Descrição |
---|---|
header | Cabeçalho de mensagem padrão, conforme descrito em Cabeçalho de mensagem padrão. |
flagBits | Uma máscara de bits de números inteiros contendo sinalizadores de mensagem, conforme descrito em Flag Bits. |
sections | Seções do corpo da mensagem, conforme descrito em Seções. |
checksum | Um checksum CRC-32C opcional, conforme descrito em Checksum. |
Sinalizar Bits
O número inteiro flagBits
é um sinalizador de codificação bitmask que modifica o formato e comportamento de OP_MSG
.
Os primeiros 16 bits (0-15) são obrigatórios e os analisadores DEVEM apresentar erro se um bit desconhecido for definido.
Os últimos 16 bits (16-31) são opcionais, e os analisadores DEVEM ignorar qualquer conjunto de bits desconhecido. Os proxies e outros encaminhadores de mensagens DEVEM limpar todos os bits opcionais desconhecidos antes de encaminhar as mensagens.
Bit | Nome | Solicitar | Resposta | Descrição |
---|---|---|---|---|
0 | checksumPresent | ✓ | ✓ | |
1 | moreToCome | ✓ | ✓ | Outra mensagem seguirá esta sem qualquer ação adicional do receptor. O receptor NÃO DEVE enviar outra mensagem até receber uma com moreToCome definido como 0, pois os envios podem bloquear, causando impasse. As solicitações com o conjunto de moreToCome bits não receberão uma resposta. As respostas só terão esta definição em resposta a pedidos com o conjunto de exhaustAllowed bits. |
16 | exhaustAllowed | ✓ | O cliente está preparado para múltiplas respostas a esta solicitação usando o bit Isso garante que várias respostas só sejam enviadas quando a camada de rede do solicitante estiver preparada para eles. ImportanteO MongoDB 3.6 ignora esta sinalização e responderá com uma única mensagem. |
Seções
Uma mensagem OP_MSG
contém uma ou mais seções. Cada seção começa com um byte kind
indicando seu tipo. Tudo após o byte de kind
constitui a carga útil da seção.
Seguem os tipos de seções disponíveis.
Tipo 0: Corpo
Uma seção do corpo é codificada como um único objeto BSON. O tamanho no objeto BSON também serve como tamanho da seção. Este tipo de seção é a solicitação de comando padrão e o corpo de resposta.
Todos os campos de nível superior DEVEM ter um nome exclusivo.
Tipo 1: Sequência de Documentos
Tipo | Descrição |
---|---|
int32 | Tamanho da seção em bytes. |
Cadeia C | Identificador de sequência do documento. Em todos os comandos atuais este campo é o campo (possivelmente aninhado) que ele está substituindo da seção do corpo. Este campo NÃO PODE existir na seção do corpo. |
Zero ou mais objetos BSON |
|
Checksum
Cada mensagem PODE terminar com uma soma de verificação CRC-32C [2] que abrange todos os bytes da mensagem, exceto a própria soma de verificação.
Começando no MongoDB 4.2:
As instâncias
mongod
,mongos
emongo
instâncias de shell trocarão mensagens com somas de verificação se não estiverem usando conexão TLS/SSL.As instâncias
mongod
,mongos
emongo
instâncias de shell ignorarão a checksum de verificação se estiverem usando a conexão TLS/SSL.
Drivers e binários mais antigos ignorarão a soma de verificação se houver mensagens com soma de verificação.
A presença de uma checksum é indicada pelo bit de sinalização checksumPresent
.
OP_UPDATE
Obsoleto no MongoDB 5.0.
A mensagem OP_UPDATE é usada para atualizar um documento em uma coleção. O formato de uma mensagem OP_UPDATE é o seguinte:
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 }
Campo | Descrição |
---|---|
header | Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão. |
ZERO | Valor total de 0. Reservado para uso futuro. |
fullCollectionName | O nome completo da collection; ou seja, namespace. O nome completo da coleção é a concatenação do nome do banco de dados com o nome da coleção, utilizando um . para a concatenação. Por exemplo, para o banco de dados foo e a coleção bar , o nome completo da coleção é foo.bar . |
flags | Vetor de bits para especificar sinalizadores para a operação. Os valores de bits correspondem ao seguinte:
|
selector | Documento JSON que especifica a query para seleção do documento a ser atualizado. |
update | Documento JSON que especifica a atualização a ser executada. Para obter informações sobre como especificar atualizações, consulte a documentação das Operações de Atualização. |
Não há resposta a uma mensagem OP_UPDATE.
OP_INSERT
Obsoleto no MongoDB 5.0.
A mensagem OP_INSERT é usada para inserir um ou mais documentos em uma coleção. O formato da mensagem 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 }
Campo | Descrição |
---|---|
header | Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão. |
flags | Vetor de bits para especificar sinalizadores para a operação. Os valores de bits correspondem ao seguinte:
|
fullCollectionName | O nome completo da collection; ou seja, namespace. O nome completo da coleção é a concatenação do nome do banco de dados com o nome da coleção, utilizando um . para a concatenação. Por exemplo, para o banco de dados foo e a coleção bar , o nome completo da coleção é foo.bar . |
documents | Um ou mais documentos para inserir na coleção. Se houver mais de um, eles serão gravados no soquete em sequência, um após o outro. |
Não há resposta a uma mensagem OP_INSERT.
OP_QUERY
Obsoleto no MongoDB 5.0.
A mensagem OP_QUERY é usada para executar query do banco de dados para documentos em uma coleção. O formato da mensagem 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. }
Campo | Descrição | |
---|---|---|
header | Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão. | |
flags | Vetor de bits para especificar sinalizadores para a operação. Os valores de bits correspondem ao seguinte:
| |
fullCollectionName | O nome completo da collection; ou seja, namespace. O nome completo da coleção é a concatenação do nome do banco de dados com o nome da coleção, utilizando um . para a concatenação. Por exemplo, para o banco de dados foo e a coleção bar , o nome completo da coleção é foo.bar . | |
numberToSkip | Define o número de documentos a serem omitidos, começando pelo primeiro documento no conjunto de dados resultante, ao retornar o resultado da query. | |
numberToReturn | Limita o número de documentos na primeira mensagem OP_REPLY à query. No entanto, o banco de dados de dados ainda estabelecerá um cursor e retornará o cursorID ao cliente se houver mais resultados do que numberToReturn . Se o driver cliente oferecer funcionalidade 'limit' (como a palavra-chave SQL LIMIT), caberá ao driver cliente garantir que não mais do que o número especificado de documento seja retornado ao aplicação de chamada. Se numberToReturn for 0 , o banco de dados usará o tamanho de retorno padrão. Se o número for negativo, o banco de dados de dados retornará esse número e fechará o cursor. Nenhum resultado adicional para essa query pode ser obtido. Se numberToReturn for 1 o servidor tratará como -1 (fechando o cursor automaticamente). | |
query | Documento BSON que representa a query. A query conterá um ou mais elementos, todos os quais devem corresponder para que um documento seja incluído no conjunto de resultados. Os possíveis elementos incluem $query , $orderby , $hint e $explain . | |
returnFieldsSelector | Opcional. Documento JSON que limita os campos nos documentos devolvidos. O
|
O banco de dados responderá a uma mensagem OP_QUERY com uma mensagem OP_REPLY.
OP_GET_MORE
Obsoleto no MongoDB 5.0.
A mensagem OP_GET_MORE é usada para executar query no banco de dados para documentos em uma coleção. O formato da mensagem 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 }
Campo | Descrição |
---|---|
header | Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão. |
ZERO | Valor total de 0. Reservado para uso futuro. |
fullCollectionName | O nome completo da collection; ou seja, namespace. O nome completo da coleção é a concatenação do nome do banco de dados com o nome da coleção, utilizando um . para a concatenação. Por exemplo, para o banco de dados foo e a coleção bar , o nome completo da coleção é foo.bar . |
numberToReturn | Limita o número de documentos na primeira mensagem OP_REPLY à query. No entanto, o banco de dados ainda estabelecerá um cursor e retornará o cursorID ao cliente se houver mais resultados do que numberToReturn . Se o driver cliente oferecer funcionalidade 'limit' (como a palavra-chave SQL LIMIT), caberá ao driver cliente garantir que não mais do que o número especificado de documento seja retornado ao aplicativo de chamada. Se numberToReturn for 0 , o db usará o tamanho de retorno padrão. |
cursorID | Identificador do cursor que veio em OP_REPLY. Este deve ser o valor que veio do banco de dados. |
O banco de dados responderá a uma mensagem OP_GET_MORE com uma mensagem OP_REPLY.
OP_DELETE
Obsoleto no MongoDB 5.0.
A mensagem OP_DELETE é usada para remover um ou mais documentos de uma coleção. O formato da mensagem 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. }
Campo | Descrição |
---|---|
header | Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão. |
ZERO | Valor total de 0. Reservado para uso futuro. |
fullCollectionName | O nome completo da collection; ou seja, namespace. O nome completo da coleção é a concatenação do nome do banco de dados com o nome da coleção, utilizando um . para a concatenação. Por exemplo, para o banco de dados foo e a coleção bar , o nome completo da coleção é foo.bar . |
flags | Vetor de bits para especificar sinalizadores para a operação. Os valores de bits correspondem ao seguinte:
|
selector | documento BSON que representa a query usada para selecionar os documentos a serem removidos. O seletor conterá um ou mais elementos, todos os quais devem corresponder para que um documento seja removido da coleção. |
Não há resposta a uma mensagem OP_DELETE.
OP_KILL_CURSORS
Obsoleto no MongoDB 5.0.
A mensagem OP_KILL_CURSORS é usada para fechar um cursor ativo no banco de dados. Isso é necessário para garantir que os recursos do banco de dados sejam recuperados no final da query. O formato da mensagem 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 }
Campo | Descrição |
---|---|
header | Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão. |
ZERO | Valor total de 0. Reservado para uso futuro. |
numberOfCursorIDs | O número de ID de cursor que estão na mensagem. |
cursorIDs | "Array" de IDs de cursor a serem fechadas. Se houver mais de um, eles serão gravados no soquete em sequência, um após o outro. |
Se um cursor for lido até esgotar (leia até OP_QUERY ou OP_GET_MORE retornar zero para o ID do cursor), não será necessário matar o cursor.
OP_COMPRESSED
Qualquer opcode pode ser comprimido e encapsulado em um cabeçalho OP_COMPRESSED. A mensagem OP_COMPRESSED contém a mensagem de opcode comprimida original juntamente com os metadados necessários para processá-la e descompactá-la.
O formato da mensagem 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 }
Campo | Descrição |
---|---|
MsgHeader | Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão. |
originalOpcode | Contém o valor do código de operação envolto. |
uncompressedSize | O tamanho do compressedMessage deflacionado, que exclui o MsgHeader . |
compressorId | O ID do compressor que comprimiu a mensagem. Uma lista de compressorId valores é fornecida abaixo. |
compressedMessage | O código de operação em si, excluindo o MsgHeader . |
Cada compressor recebe um ID de compressor pré-definido da seguinte forma:
compressorId | Valor do Handshake | Descrição |
---|---|---|
0 | noop | O conteúdo da mensagem é descompactado. Isso é usado para
testar. |
1 | snappy | O conteúdo da mensagem é comprimido usando snappy. |
2 | zlib | O conteúdo da mensagem é comprimido usando zlib. |
3 | zstd | O conteúdo da mensagem é comprimido usando zstd. |
4-255 | reservado | Reservado para uso futuro. |
Mensagens de resposta do banco de dados
OP_REPLY
Obsoleto no MongoDB 5.0.
A mensagem OP_REPLY
é enviada pelo banco de dados em resposta a uma mensagem OP_QUERY ou OP_GET_MORE. O formato de uma mensagem 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 }
Campo | Descrição |
---|---|
header | Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão. |
responseFlags | Vetor de bits para especificar sinalizadores. Os valores de bits correspondem ao seguinte:
|
cursorID | O cursorID do qual este OP_REPLY faz parte. Caso o conjunto de resultados da query se encaixe em uma mensagem OP_REPLY, cursorID será 0. Este cursorID deve ser usado em qualquer mensagem OP_GET_MORE usada para obter mais dados e também deve ser fechado pelo cliente quando não for mais necessário por meio de uma mensagem OP_KILL_CURSORS . |
startingFrom | Posição inicial no cursor. |
numberReturned | Número de documentos na resposta. |
documents | Documentos devolvidos. |
Notas de rodapé
[2] | (1, 2) 32-bit CRC calculado com o polinômio Castagnoli conforme descrito por https://tools.ietf.org/html/rfc4960#page-140. |