Seu upgrade do MongoDB vai funcionar? Descubra antes com o UCFM

# upgrade # ucfm # ferramentas
Jean da Silva
Published date:
7 min read

Originally written for Percona Blog in November, 2026 – Will your MongoDB upgrade break? Check it with UCFM

Você foi escalado para uma das tarefas mais comuns, e mais temidas, na vida de um DBA:

Upgrades são necessários por vários motivos, seja para corrigir um bug existente ou para manter o ambiente dentro do suporte e elegível a receber correções de segurança. Seja qual for o motivo, a tarefa é sua.

A troca do binário é a parte fácil. A parte difícil é tudo o que vem antes:

Como era antes

Um upgrade major no MongoDB anda uma release por vez, não importa o salto que você planeja. Por exemplo: “Ir da 6.0 para a 8.0”

Então a lição de casa não se faz uma vez. Ela se faz a cada passo, e em cada passo o checklist é mais ou menos este:

Nada disso é difícil por si só. É só longo, chato, fácil de errar e diferente para cada passo de versão. E não existia um único comando que respondesse à pergunta de verdade:

Esse deployment está pronto para o upgrade? Se não, o que eu devo corrigir primeiro?

Conheça o UCFM, o upgrade checker para MongoDB

O UCFM (Upgrade Checker For MongoDB) diz se um deployment de MongoDB ou de Percona Server for MongoDB está pronto para o upgrade, e o que corrigir primeiro.

Se você já trabalhou com MySQL, a ideia pode soar familiar: isso porque o ucfm é bastante inspirado no upgrade checker do MySQL Shell, o util.checkForServerUpgrade().

Meme de uma prova: um homem olha de lado para a folha do colega ao lado e copia a resposta.DBAs de MySQL têm essa resposta há anos.

O valor não está em nenhum check isolado. Está em ter um lugar só que conhece cada mudança entre duas versões, aplica todas elas ao seu deployment e te entrega uma lista curta do que corrigir.

Foi essa a ideia por trás dele: uma ferramenta que diz o que está certo e o que está errado no seu ambiente, e responde essa mesma pergunta um passo de upgrade por vez.

Se você está um passo antes e ainda decide qual caminho tomar, deixa eu recomendar o MongoDB Upgrade Roadmap; ele pode te ajudar com os passos do upgrade.

O que ele faz e o que não faz

O ucfm é uma ferramenta somente leitura que funciona checando fatos de cada membro que consegue alcançar no seu deployment.

Você aponta para um nó, e ele descobre o resto do replica set, ou os config servers, shards e mongos. Depois roda três tipos de check:

No fim do check, ele gera uma lista com os achados e as ações recomendadas.

Vale destacar que o ucfm não faz upgrade de nada. Ele lê e reporta; o upgrade continua sendo seu.

O que ele te dá é a resposta para a pergunta do começo deste post. Antes da janela de manutenção, você sabe o que pode quebrar e onde.

Como usar

Instalação

Um comando baixa a última release, verifica o checksum e instala o ucfm em /usr/local/bin (ou em ~/.local/bin quando você não é root). Rodar de novo atualiza.

curl -fsSL https://raw.githubusercontent.com/jenunes/ucfm/main/install.sh | bash

Crie um usuário somente leitura

A ferramenta precisa de clusterMonitor, readAnyDatabase e uma role pequena que consiga ler usuários, roles e definições de views. Para isso criamos uma role customizada, a ucfmViewSecurity, que guarda as permissões necessárias, e você pode removê-la depois se preferir:

use admin
db.createRole({
  role: "ucfmViewSecurity",
  privileges: [
    { resource: { cluster: true }, actions: ["viewUser"] },
    { resource: { db: "", collection: "" }, actions: ["viewUser", "viewRole"] },
    { resource: { db: "", collection: "system.views" }, actions: ["find"] }
  ],
  roles: []
})

Depois crie o usuário com as permissões necessárias:

use admin
db.createUser({
  user: "ucfm",
  pwd: passwordPrompt(),
  roles: ["clusterMonitor", "readAnyDatabase", "ucfmViewSecurity"]
})

Nota: Em sharded cluster, crie o usuário no mongos e também no primary de cada shard. ucfm conecta direto nos membros dos shards, e eles só aceitam usuários locais do shard. Se você esquecer algum, ele avisa e nomeia o shard.

Cheque seu cluster

Aponte o --uri para qualquer membro do replica set, ou para um mongos (se for sharded cluster), e informe a versão de destino:

ucfm check --uri "mongodb://ucfm@db1:27017/?authSource=admin" --target 7.0

Se preferir, deixe a senha fora do --uri e o ucfm pergunta por ela. Para scripts, use a variável de ambiente UCFM_URI ou o --uri-file.

O relatório começa com os checks do deployment inteiro (caminho de upgrade, FCV, saúde, estado do sharding), depois traz um bloco por passo de upgrade. Um exemplo resumido:

The MongoDB deployment at db1:27017 (replica set rs0, 3 members), Percona
Server for MongoDB 6.0.29-23, will now be checked for compatibility issues for
upgrade to MongoDB 7.0 (path 6.0 → 7.0)...

================================================================================
Deployment-wide checks
================================================================================

1) Upgrade path (upgrade-path)
   No issues found: from 6.0 (current) to 7.0 (target) is a supported upgrade
      path.

2) Server versions across members (binary-versions-consistent)
   No issues found: all 3 members run 6.0.29-23.

3) featureCompatibilityVersion (fcv-matches-binary)
   No issues found: FCV is 6.0 on 3 members, the same as their binaries.

[...]

================================================================================
Upgrade 6.0 → 7.0
Checked against Percona Server for MongoDB 7.0, psmdb-7.0.45-24
================================================================================

[...]

20) PSMDB journal options (psmdb-journal-option-ignored)
   Notice: storage.journal.enabled / --journal / --nojournal are set. PSMDB 7.0
      and later always journal and ignore these settings, logging a startup
      warning.

   - db1:27017, db2:27017, db3:27017

   Solution:
   - Remove the journal settings from the configuration.

   More information:
     https://docs.percona.com/percona-server-for-mongodb/7.0/install/upgrade-from-60.html

[...]

24) Usage of removed commands (command-removed-in-use)
   Warning: Clients ran these commands since the servers started (longest uptime
      1d); 7.0 no longer implements them and will answer CommandNotFound.

   - availableQueryOptions (6 calls)

   Solution:
   - Find the applications or tools issuing these commands (profiler, logs,
     $currentOp) and update them before upgrading.

   More information:
     https://www.mongodb.com/docs/manual/release-notes/7.0-compatibility/

[...]

================================================================================
Errors:   0
Warnings: 3
Notices:  4

Checks with warnings:
   - 24) Usage of removed commands (command-removed-in-use)
   - 31) Floating-point rounding in $add (add-rounding)
   - 35) $natural hint and sort values (natural-hint-values)

No errors were found. Review the 3 warnings before upgrading.

Antes de passar pelos resultados, leia o topo do relatório: ele diz o que está sendo checado, e os primeiros checks dizem o que não pôde ser checado e como resolver isso.

A ferramenta checa um upgrade major por vez. Caso o destino esteja mais longe, por exemplo do 6.0 ao 8.0, o check mostra o caminho completo e o relatório só do primeiro passo, nesse caso 7.0; rode a ferramenta novamente depois de cada upgrade para ter o relatório correto da versão.

O exit code segue o resultado (0 limpo, 1 warnings, 2 errors, 3 falha da ferramenta), então o check cabe num pipeline. Adicione --format json para obter a saída em JSON, ou --deep-check para amostrar até 1000 documentos por collection e verificar as mudanças que dependem dos dados armazenados.

Auditar as configurações de produção

Upgrade é um bom momento para entender como anda o resto da casa. O ucfm audit compara o deployment com as Production Notes e o Operations Checklist do MongoDB:

ucfm audit --uri "mongodb://ucfm@db1:27017/?authSource=admin"

Você também pode anexar essa auditoria ao ucfm check padrão com --with-audit:

ucfm check --uri "mongodb://ucfm@db1:27017/?authSource=admin" --target 7.0 --with-audit

Uma execução, um relatório com as duas seções.

Com isso, acredito que você já tem o que precisa para a sua próxima janela de manutenção. Quando quiser ir além, como checar o sistema operacional de cada host ou coletar um snapshot para analisar em outro lugar, dê uma olhada na documentação do UCFM, que tem mais detalhes.

Conclusão

O UCFM nasceu do desejo de simplificar um processo e de responder à pergunta destacada no começo, uma pergunta que, até agora, não tinha um único comando para respondê-la.

Ainda assim, ele não substitui o seu julgamento, o seu backup nem o procedimento de upgrade. Ele substitui o checklist manual e longo por uma única passada de leitura no ambiente que você já tem: um passo por vez, com achados nos quais você pode agir antes da janela de manutenção.

Instale, aponte para um nó, escolha o destino e leia o relatório. Corrija os erros, rode de novo e me conte como foi.

Sugestões, correções e features são todas bem-vindas; o projeto é open source em: github.com/jenunes/ucfm.

Share
Próximo
Por que você deveria parar de usar ÁRBITROS no MongoDB