Menu Docs

Definir versão de compatibilidade do recurso

setFeatureCompatibilityVersion

Habilita ou desabilita os recursos que persistem aos dados incompatíveis com versões anteriores do MongoDB. Você só pode emitir o setFeatureCompatibilityVersion em relação ao banco de dados admin.

Aviso

Habilitar funcionalidades incompatíveis com versões anteriores pode complicar o processo de downgrade, pois você deve remover todos as funcionalidades persistentes incompatíveis com versões anteriores antes de fazer o downgrade.

É recomendável que, após a atualização, você permita que seu sistema seja executado sem habilitar funcionalidades incompatíveis com versões anteriores por um período de burn-in para garantir que a probabilidade de downgrade seja mínima. Quando você estiver confiante de que a probabilidade de downgrade é mínima, habilite esses recursos.

Esse comando está disponível em implantações hospedadas nos seguintes ambientes:

  • MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB

  • MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

O comando tem a seguinte sintaxe:

db.adminCommand(
{
setFeatureCompatibilityVersion: <version>,
writeConcern: { wtimeout: <timeout> }
}
)

Os valores possíveis para version são:

Versão
Descrição

"6.0"

Disponível nos Sistemas do MongoDB 6.0

Habilita os recursos 6.0 que persistem dados incompatíveis com o MongoDB 5.0.

"5.0"

Disponível nos Sistemas MongoDB 5.0 e 6.0

Habilita os recursos 5.0 que persistem dados incompatíveis com o MongoDB 4.4.

O writeConcern opcional especifica o valor da write concern wtimeout em milissegundos:

  • O período que o primary aguarda a confirmação da maioria dos nós do conjunto de réplicas. Se o reconhecimento não for recebido no período, a operação falhará.

  • O padrão é 60000 milissegundos. Utilize um período mais longo se os membros secundários do conjunto de réplicas tiverem um atraso que exceda o padrão wtimeout.

Observação

  • Para um standalone, execute o comando na instância do standalone mongod.

  • Para um conjunto de réplicas, execute o comando no primary. A maioria dos nós portadores de dados deve estar disponível.

  • Para um cluster fragmentado, execute o comando em uma instância do mongos.

Certas operações em segundo plano podem impedir a execução de setFeatureCompatibilityVersion. Utilize o currentOp para identificar quaisquer operações em andamento.

Se você acionar uma alteração de setFeatureCompatibilityVersion durante uma sincronização inicial, a sincronização poderá falhar com uma mensagem de erro OplogOperationUnsupported ao reproduzir entradas na fase de aplicação oplog. A sincronização após essa tentativa é bem-sucedida porque a fase de operação não repete mais a operação.

Implantações
featureCompatibilityVersion

Para novas implantações do 6.0

"6.0"

Para sistemas 6.0 atualizados do 5.0

"5.0" até você setFeatureCompatibilityVersion "6.0"a.

Para novas implantações do 5.0

"5.0"

Para sistemas 5.0 atualizados do 4.4

"4.4" até você setFeatureCompatibilityVersion "5.0"a.

Este comando deve executar gravações em uma collection interna do sistema. Se, por algum motivo, o comando não for concluído com êxito, você poderá tentar novamente com segurança, pois a operação é idempotente.

A partir do MongoDB 6.0, se você precisar fazer downgrade da versão de compatibilidade de funcionalidades, certifique-se de desabilitar a replicação de cluster para cluster e o bloqueio de escrita do usuário.

  1. Se você ativou a replicação de cluster para cluster, desative-a.

  2. Se você habilitou o bloqueio de escrita do usuário, desative-o:

    db.runCommand( { setUserWriteBlockMode: 1, global: false } )
  3. Aguarde a conclusão do comando anterior.

  4. Faça downgrade da versão de compatibilidade de recursos usando setFeatureCompatibilityVersion.

Para obter mais informações sobre o MongoDB Cluster-to-Cluster Sync, consulte a documentação.

Os arbiters não replicam a collection. Por esse motivo, os arbiters sempre têm uma versão de compatibilidade do recurso igual à versão de downgrade do binário, independentemente do valor FCV do conjunto de admin.system.version réplicas.

Por exemplo, um árbitro em um cluster do MongoDB 5.0 tem um valor FCV de 4.4.

Para visualizar o featureCompatibilityVersion para uma instância do mongod, execute o comando getParameter em uma instância do mongod:

db.adminCommand( {
getParameter: 1,
featureCompatibilityVersion: 1
}
)

A saída se assemelha a:

{
featureCompatibilityVersion: { version: '5.0' },
ok: 1,
'$clusterTime': {
clusterTime: Timestamp({ t: 1660318752, i: 5 }),
signature: {
hash: Binary(Buffer.from("ce0cff3621e9b089fa6d8e9a1e1efc1a1ff15dab", "hex"), 0),
keyId: Long("7129893797260951557")
}
},
operationTime: Timestamp({ t: 1660318752, i: 5 })
}

Observação

A operação é indefinida nas instâncias do mongos.

Em um cluster fragmentado com controle de acesso habilitado, você deve se conectar ao shard como um usuário local do shard para executar o comando.

Para habilitar as funcionalidades do 6.0 que persistem dados incompatíveis com MongoDB 5.0, configure a compatibilidade da funcionalidade para "6.0" no sistema do MongoDB 6.0:

Observação

Execute o comando setFeatureCompatibilityVersion no banco de dados do admin.

  • Para um standalone, execute o comando na instância do standalone mongod.

  • Para um conjunto de réplicas, execute o comando no primary. A maioria dos nós portadores de dados deve estar disponível.

  • Para um cluster fragmentado, execute o comando em uma instância do mongos.

db.adminCommand( { setFeatureCompatibilityVersion: "6.0" } )

Para desabilitar as funcionalidades do 6.0 que persistem dados incompatíveis com MongoDB 5.0, configure a compatibilidade da funcionalidade para "5.0" no sistema do MongoDB 6.0:

Observação

Execute o comando setFeatureCompatibilityVersion no banco de dados do admin.

  • Para um standalone, execute o comando na instância do standalone mongod.

  • Para um conjunto de réplicas, execute o comando no primary. A maioria dos nós portadores de dados deve estar disponível.

  • Para um cluster fragmentado, execute o comando em uma instância do mongos.

  • "5.0" featureCompatibilityVersion é suportado somente nos sistemas MongoDB 5.0 e MongoDB 6.0.

db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )

Se executar como parte do processo de downgrade do MongoDB 6.0 para MongoDB 5.0, você também deverá remover todas as funcionalidades persistentes que são incompatíveis com 5.0. Consulte os procedimentos de downgrade apropriados.

Para habilitar as funcionalidades do 5.0 que persistem dados incompatíveis com MongoDB 4.4, configure a compatibilidade da funcionalidade para "5.0" no sistema do MongoDB 5.0:

Observação

Execute o comando setFeatureCompatibilityVersion no banco de dados do admin.

  • Para um standalone, execute o comando na instância do standalone mongod.

  • Para um conjunto de réplicas, execute o comando no primary. A maioria dos nós portadores de dados deve estar disponível.

  • Para um cluster fragmentado, execute o comando em uma instância do mongos.

db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )

Para desabilitar as funcionalidades do 5.0 que persistem dados incompatíveis com MongoDB 4.4, configure a compatibilidade da funcionalidade para "4.4" no sistema do MongoDB 5.0:

Observação

Execute o comando setFeatureCompatibilityVersion no banco de dados do admin.

  • Para um standalone, execute o comando na instância do standalone mongod.

  • Para um conjunto de réplicas, execute o comando no primary. A maioria dos nós portadores de dados deve estar disponível.

  • Para um cluster fragmentado, execute o comando em uma instância do mongos.

  • "4.4" featureCompatibilityVersion é suportado somente nos sistemas MongoDB 4.4 e MongoDB 5.0.

db.adminCommand( { setFeatureCompatibilityVersion: "4.4" } )

Se executar como parte do processo de downgrade do MongoDB 5.0 para MongoDB 4.4, você também deverá remover todas as funcionalidades persistentes que são incompatíveis com o 4.4. Consulte os procedimentos de downgrade apropriados.

Para habilitar as funcionalidades do 4.2 que persistem dados incompatíveis com o MongoDB 4.0, configure a compatibilidade da funcionalidade para "4.2" no sistema do MongoDB 4.2 :

Observação

Execute o comando setFeatureCompatibilityVersion no banco de dados do admin.

  • Para um standalone, execute o comando na instância do standalone mongod.

  • Para um conjunto de réplicas, execute o comando no primary. A maioria dos nós portadores de dados deve estar disponível.

  • Para um cluster fragmentado, execute o comando em uma instância do mongos.

db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } )

O exemplo a seguir define o campo de wtimeout de write concern opcional como 5000 (5 segundos).

Observação

Execute o comando setFeatureCompatibilityVersion no banco de dados do admin.

  • Para um standalone, execute o comando na instância do standalone mongod.

  • Para um conjunto de réplicas, execute o comando no primary. A maioria dos nós portadores de dados deve estar disponível.

  • Para um cluster fragmentado, execute o comando em uma instância do mongos.

db.adminCommand( {
setFeatureCompatibilityVersion: "5.0",
writeConcern: { wtimeout: 5000 }
} )