Atualize sem receios com a stable API do MongoDB
Avalie esse Tutorial
Você hesita em atualizar o MongoDB, por temer que o novo banco de dados seja incompatível com seu código existente?
Depois de escrever e implantar seu aplicativo MongoDB, você quer poder atualizar seu MongoDB database à vontade, sem se preocupar com a possibilidade de uma mudança de comportamento interromper seu aplicativo. No passado, fizemos o possível para garantir que cada versão do banco de dados fosse compatível com as versões anteriores e, ao mesmo tempo, adicionássemos novos recursos. Mas às vezes tivemos que quebrar a compatibilidade, porque não havia outra maneira de corrigir um problema ou melhorar o comportamento. Além disso, não tinhamos uma única definição de compatibilidade com versões anteriores.
Resolver esse problema é mais importante agora: estamos lançando novas versões quatro vezes por ano em vez de umae planejamos ser mais rápidos no futuro. Queremos ajudá-lo a fazer upgrades com frequência e aproveitar os novos recursos, mas primeiro você deve se sentir confiante de que pode fazer upgrade com segurança. O ideal é que você atualize imediatamente todos os seus aplicativos para o MongoDB mais recente sempre que formos lançados.
A MongoDB stable API é como tornaremos isso possível. A stable API engloba o subconjunto de comandos MongoDB que os aplicativos comumente usam para ler e escrever dados, criar collection e índices e assim por diante. Comprometemo-nos a manter esses comandos compatíveis com versões anteriores nas novas versões do MongoDB. Podemos adicionar novos recursos (como novos parâmetros de comando, novos operadores de agregação, novos comandos etc.) à stable API, mas apenas de maneiras compatíveis com versões anteriores.
Sigamos este princípio:
Para qualquer versão V da API, se um aplicativo declarar a versão V da API e usar apenas comportamentos em V, e for implantado junto com uma versão específica de um driver oficial, ele não sofrerá alterações de comportamento semanticamente significativas resultantes de atualizações do banco de dados, desde que o novo banco de dados suporta V.
(O que é uma mudança de comportamento semanticamente insignificante? Exemplos incluem o texto de alguma mensagem de erro, a ordem de um resultado de query se você não classificá-lo explicitamente ou o desempenho de uma query específica. Comportamentos como esses, que não são documentados e não não afeta a correção, pode mudar de versão para versão.)
Para usar a Stable API, atualize para o driver mais recente e crie o MongoClient da sua aplicação assim:
1 client = MongoClient( 2 "mongodb://host/", 3 api={"version": "1", "strict": True})
Por enquanto, "1" é a única versão da API. Passando "strict": True significa que o banco de dados rejeitará todos os comandos que não estejam na stable API. Por exemplo, se você chamar replSetGetStatus, que não está na stable API, receberá um erro:
1 { 2 "ok" : 0, 3 "errmsg" : "Provided apiStrict:true, but replSetGetStatus is not in API Version 1", 4 "code" : 323, 5 "codeName" : "APIStrictError" 6 }
Execute o conjunto de testes do seu aplicativo com as novas opções do MongoClient, veja quais comandos e recursos você está usando que estão fora da stable API e migre para alternativas com controle de versão. Por exemplo, "mapreduce" não está na stable API, mas "aggregate" está. Depois que seu aplicativo usar apenas a Stable API, você poderá implementá-lo novamente com as novas opções MongoClient e ter certeza de que futuras atualizações de banco de dados não afetarão seu aplicativo.
O mongosh shell agora também suporta a stable API:
1 mongosh --apiVersion 1 --apiStrict
Talvez você precise usar recursos sem versão em alguma parte do seu aplicativo, talvez temporariamente enquanto estiver migrando para a stable API, talvez permanentemente. A saída é criar um MongoClient não restrito e usá-lo apenas para usar recursos não versionados:
1 # Non-strict client. 2 client = MongoClient( 3 "mongodb://host/", 4 api={"version": "1", "strict": False}) 5 6 client.admin.command({"replSetGetStatus": 1})
A opção "strict" é falsa por padrão, só estou sendo explícita aqui. Use esse cliente não rigoroso para os poucos comandos não versionados que seu aplicativo precisa. Esteja ciente de que ocasionalmente podemos fazer alterações incompatíveis com versões anteriores nesses comandos.
A única versão da API que existe hoje é "1", mas no futuro lançaremos novas versões da API. Isso é empolgante para nós: o MongoDB tem algumas falhas que precisávamos manter por questões de compatibilidade, mas a stable API nos oferece uma maneira segura de removê-las. Considere o seguinte:
1 client = MongoClient("mongodb://host") 2 client.test.collection.insertOne({"a": [1]}) 3 4 # Strangely, this matches the document above. 5 result = client.test.collection.findOne( 6 {"a.b": {"$ne": null}})
É obviamente errado que
{"a": [1]} corresponda à query {"a.b": {"$ne": null}}, mas não podemos corrigir esse comportamento, temendo que os aplicativos dos usuários confiem nele. A stable API nos oferece uma maneira de corrigir isso com segurança. Podemos fornecer semântica de query mais limpa na versão 2:1 # Explicitly opt in to new behavior. 2 client = MongoClient( 3 "mongodb://host/", 4 api={"version": "2", "strict": True}) 5 6 client.test.collection.insertOne({"a": [1]}) 7 8 # New behavior: doesn't match document above. 9 result = client.test.collection.findOne( 10 {"a.b": {"$ne": null}})
Versões futuras do MongoDB suportarão a versão 1 e 2, e manteremos a versão 1 por muitos anos. Os aplicativos que solicitam as versões antigas ou novas podem ser executados simultaneamente no mesmo banco de dados. O comportamento padrão será a versão 1 (para compatibilidade com aplicativos antigos que não solicitam uma versão específica), mas novos aplicativos podem ser escritos para a versão 2 e obter o novo comportamento, obviamente, mais sensato.
Com o tempo, descontinuaremos alguns recursos da versão 1 . Isso é um sinal de que, quando introduzirmos a versão 2, essas funcionalidades não serão incluídas. (As versões futuras do MongoDB suportarão a versão 1 com recursos obsoletos e a versão 2 sem eles.) Quando chegar a hora de você migrar um aplicativo existente da versão 1 para o 2, sua primeira etapa será encontrar todos os recursos obsoletos que ele usa:
1 # Catch uses of features deprecated in Version 1. 2 client = MongoClient( 3 "mongodb://host/", 4 api={"version": "1", 5 "strict": True, 6 "deprecationErrors": True})
O banco de dados retornará um APIDeprecationError sempre que seu código tentar usar um recurso obsoleto. Depois de executar seus testes e corrigir todos os erros, você estará pronto para testar seu aplicativo com a Versão 2.
No entanto, a versão 2 pode estar muito distante. Até lá, continuaremos adicionando recursos e fazendo melhorias na versão 1. Introduziremos novos comandos, novas opções, novos operadores de agregação e assim por diante. Cada alteração na versão 1 será uma extensão da API existente e nunca afetará o código do aplicativo existente. Com lançamentos trimestrais, podemos melhorar o MongoDB mais rápido do que nunca. Depois de atualizar para 5.0 e migrou seu aplicativo para a stable API, você sempre poderá usar a versão mais recente sem temor.
Você pode experimentar a stable API com o MongoDB 5.0 Release Candidate, que já está disponível em nossa Central de Download.
Aqui está uma lista de comandos incluídos na versão da API 1 no MongoDB 5.0. Você pode chamar esses comandos com a versão "1" e strict: true. (Mas, é claro, você também pode chamá-los sem configurar a versão da API do MongoClient, como antes.) Não faremos alterações incompatíveis com versões anteriores em nenhum desses comandos. Em versões futuras, podemos adicionar recursos a esses comandos e podemos adicionar novos comandos à versão 1.
- explicar (não fará alterações incompatíveis nos parâmetros de entrada deste comando, embora seu formato de saída possa mudar arbitrariamente)
- saslContinue
- saslStart
O desenvolvimento, o lançamento e o timing de quaisquer recursos ou funcionalidades descritos dos nossos produtos permanecem a nosso exclusivo critério. Esta informação destina-se apenas a delinear a direção geral do nosso produto e não deve ser invocada na tomada de uma decisão de compra nem é um compromisso, promessa ou obrigação legal de entregar qualquer material, código ou funcionalidade.
Avalie esse Tutorial