NOVIDADES
Nesta página
Descubra as novidades de cada versão:
Para visualizar uma lista de versões e notas de versão detalhadas, consulte Mongoid Releases no Github.
Novidades no 9.0
A versão 9.0 inclui os seguintes novos recursos, melhorias e correções:
Railsmdb
Junto com o lançamento do Mongoid v9.0, O railsmdb
, um utilitário de linha de comando para criar, atualizar, gerenciar e manter aplicativos Rails, está geralmente disponível.
railsmdb
facilita o trabalho com o MongoDB a partir da linha de comando através de geradores comuns com os quais os desenvolvedores Ruby on Rails já estão familiarizados.
Por exemplo, você pode utilizar o railsmdb
para gerar stubs para novos modelos Mongoid:
bin/railsmdb generate model person
Isso criará um novo modelo em app/models/person.rb
:
class Person include Mongoid::Document include Mongoid::Timestamp end
Você pode especificar os campos do modelo:
bin/railsmdb generate model person name:string birth:date
class Person include Mongoid::Document include Mongoid::Timestamp field :name, type: String field :birth, type: Date end
Você pode instruir o gerador a tornar o novo modelo uma subclasse de outro, passando a opção --parent
:
bin/railsmdb generate model student --parent=person
class Student < Person include Mongoid::Timestamp end
Se precisar armazenar seus modelos em uma coleção diferente da que pode ser inferida a partir do nome do modelo, você pode especificar --collection
:
bin/railsmdb generate model course --collection=classes
class Course include Mongoid::Document include Mongoid::Timestamp store_in collection: 'classes' end
Para mais informações, consulte o repositório mongoid-railsmdb no Github.
Remoção de suporte para Ruby 2.6 e JRuby 9.3
Mongoid v9.0 requer Ruby 2.7 ou mais recente ou JRuby 9.4. Versões anteriores do Ruby e JRuby não são suportadas.
Remoção do suporte para Rails 5
Mongoid v9.0 requer Rails 6.0 ou mais recente. Versões anteriores do Rails não são suportadas.
Remoção da classe obsoleta Mongoid::Errors::InvalidStorageParent
A classe obsoleta Mongoid::Errors::InvalidStorageParent
foi removida.
around_*
As chamadas de resposta para documentos incorporados são ignoradas
O Mongoid v8.x e versões mais antigas permitem que o usuário defina around_*
callbacks para documentos incorporados. A partir de v9.0, esses retornos de chamada são ignorados e não serão executados. Um aviso será impresso no console se esses retornos de chamada forem definidos.
Se desejar restaurar o comportamento antigo, você pode definir Mongoid.around_embedded_document_callbacks
como true em seu aplicação.
Observação
Habilitar chamadas de resposta around_*
para documentos incorporados não é recomendado, pois pode causar exceções SystemStackError
quando um documento tiver muitos documentos incorporados. Consulte MONGOID- para obter5658 mais detalhes.
for_js
O método está obsoleto
O método for_js
está obsoleto e será removido no Mongoid v10.0.
Remoção de opções obsoletas
Alteração significativa: as seguintes opções de configuração são removidas no Mongoid9.0 v. Certifique-se de remover todas as referências a eles do seu aplicativo. Se você estava usando config.load_defaults 8.1
antes de atualizar, não sofrerá nenhuma mudança de comportamento. Consulte as notas de versão anteriores para saber o significado de cada opção.
:use_activesupport_time_zone
:broken_aggregables
:broken_alias_handling
:broken_and
:broken_scoping
:broken_updates
:compare_time_by_ms
:legacy_attributes
:legacy_pluck_distinct
:legacy_triple_equals
:object_id_as_json_oid
:overwrite_chained_operators
Além disso, o suporte para versões v7.5 do config.load_defaults
e anteriores foi descartado (você deve usar um mínimo da versão v8.0.)
Remoção de funcionalidade obsoleta
Alteração significativa: a seguinte funcionalidade obsoleta foi removida:
O módulo
Mongoid::QueryCache
foi removido. Substitua qualquer uso 1-for-1 porMongo::QueryCache
. O métodoMongoid::QueryCache#clear_cache
deve ser substituído porMongo::QueryCache#clear
. Todos os outros métodos e submódulos recebem nomes idênticos.Object#blank_criteria?
o método é removido (anteriormente obsoleto).Document#as_json :compact
opção é removida. Ligue para`#compact
no objetoHash
retornado.A classe obsoleta
Mongoid::Errors::InvalidStorageParent
foi removida.
touch
Método limpa estado alterado
No Mongoid v8.x e versões anteriores, o método touch
deixa os modelos no estado alterado:
# v8.x behaviour band = Band.create! band.touch band.changed? # => true band.changes # => {"updated_at"=>[2023-01-30 13:12:57.477191135 UTC, 2023-01-30 13:13:11.482975646 UTC]}
A partir de v9.0, O Mongoid agora limpa corretamente o estado alterado após usar o método touch
.
# v9.0 behavior band = Band.create! band.touch band.changed? # => false band.changes # => {}
Modo Sandbox para Console Rails
O Mongoid agora suporta o modo sandbox do console Rails. Se o console Rails foi iniciado com o sinalizador --sandbox
, o Mongoid iniciará uma transação no cliente :default
antes de abrir o console. Esta transação não será confirmada. Portanto, todos os comandos executados no console usando o cliente :default
não serão mantidos no banco de dados.
Observação
Se você executar comandos no modo sandbox usando qualquer outro cliente que não seja o padrão, essas alterações persistirão como de costume.
API de novas transações
O Mongoid 9.0 introduz uma nova API de transações inspirada no Active Record:
Band.transaction do Band.create(title: 'Led Zeppelin') end band = Band.create(title: 'Deep Purple') band.transaction do band.active = false band.save! end
Para saber mais, consulte o guiaTransações e sessões.
Documentos incorporados sempre usam o contexto de persistência pai
O Mongoid v8.x e versões mais antigas permitem que o usuário especifique o contexto de persistência para um documento incorporado (usando a macro store_in
). No Mongoid v9.0 essas configurações são ignoradas para documentos incorporados. Um documento incorporado agora sempre usa o contexto de persistência de seu documento principal.
Suporte para passar valores brutos para queries
Ao executar queries, agora é possível ignorar a lógica de coerção do tipo Mongoid usando a classe wrapper Mongoid::RawValue
. Isso pode ser útil quando os dados legado no banco de dados forem de um tipo diferente da definição de campo .
class Person include Mongoid::Document field :age, type: Integer end # Query for the string "42", not the integer 42 Person.where(age: Mongoid::RawValue("42"))
Aumentar AttributeNotLoaded
erro ao acessar campos omitidos da projeção de query
Ao tentar acessar um campo em uma instância de modelo que foi excluído com os métodos de projeções de query only
ou without
quando a instância foi carregada, o Mongoid agora criará um erro Mongoid::Errors::AttributeNotLoaded
.
Band.only(:name).first.label #=> raises Mongoid::Errors::AttributeNotLoaded Band.without(:label).first.label = 'Sub Pop Records' #=> raises Mongoid::Errors::AttributeNotLoaded
Nas versões anteriores do Mongoid, as mesmas condições gerariam um ActiveModel::MissingAttributeError
. Verifique seu código para quaisquer usos específicos do Mongoid desta classe e altere-os para Mongoid::Errors::AttributeNotLoaded
. Observe também que AttributeNotLoaded
herda de Mongoid::Errors::MongoidError
, enquanto ActiveModel::MissingAttributeError
não.
Usar o fuso horário configurado para Typecast Date
para Time
em Queries
Ao fazer query de um campo de hora usando um valor de data, o Mongoid agora considera corretamente Time.zone
para executar a conversão de tipo.
class Magazine include Mongoid::Document field :published_at, type: Time end Time.zone = 'Asia/Tokyo' Magazine.gte(published_at: Date.parse('2022-09-26')) #=> will return all results on or after Sept 26th, 2022 # at 0:00 in Asia/Tokyo time zone.
Nas versões Mongoid anteriores, o código acima ignorava a Time.zone
(independentemente da configuração :use_activesupport_time_zone
agora removida) e sempre usava o zona horário do sistema para executar a conversão de tipo.
Observe que, em versões anteriores do Mongoid, o typecasting Date
para Time
durante operações de persistência já estava correto usando o zona horário.
touch
O método em documentos incorporados lida corretamente com touch: false
a opção
Quando a opção touch: false
é definida em uma relação embedded_in
, chamar o método touch
em um documento filho incorporado não invocará touch
em seu documento pai.
class Address include Mongoid::Document include Mongoid::Timestamps embedded_in :mall, touch: false end class Mall include Mongoid::Document include Mongoid::Timestamps embeds_many :addresses end mall = Mall.create! address = mall.addresses.create! address.touch #=> updates address.updated_at but not mall.updated_at
Além disso, o método touch
foi otimizado para executar uma operação de persistência por documento pai, mesmo ao usar vários níveis de documentos incorporados aninhados.
embedded_in
Associações padrão para touch: true
A atualização de um subdocumento incorporado agora tocará automaticamente no pai, a menos que você defina explicitamente touch: false
na relação:
class Address include Mongoid::Document include Mongoid::Timestamps embedded_in :mall, touch: false end
Para todas as outras associações, o padrão permanece touch: false
.
Padrão invertido para a :replace
opção em upsert
Mongoid v8.1 adicionou a opção :replace
ao método upsert
. Esta opção foi usada para especificar se o documento existente deve ou não ser atualizado ou substituído.
Mongoid v9.0 inverte o padrão deste sinalizador de true
para false
. Isso significa que, por padrão, o Mongoid v9.0 atualiza o documento existente e não o substitui.
Imutabilidade do _id
Campo Aplicado
Antes do Mongoid v9.0, A mutação do campo _id
se comportou de forma inconsistente dependendo se o documento era de nível superior ou incorporado e dependendo de como a atualização foi executada. Em v9.0, alterar o campo _id
agora criará uma exceção quando o documento for salvo, se o documento tiver sido persistido anteriormente.
O Mongoid 9.0 também introduz um novo sinalizador de recurso, immutable_ids
, que padroniza para true
.
Mongoid::Config.immutable_ids = true
Quando definido como false
, o comportamento mais antigo e inconsistente é restaurado.
Suporte para aliases de campo nas opções de índice
Foi adicionado suporte para usar nomes de campo com nomes alternativos nas seguintes opções da macro index
: partial_filter_expression
, weights
, wildcard_projection
.
class Person include Mongoid::Document field :a, as: :age index({ age: 1 }, { partial_filter_expression: { age: { '$gte' => 20 } }) end
Observação
A expansão de aliases de nome de campo em opções de índice como partial_filter_expression
é executada de acordo com o comportamento do servidor MongoDB 6.0. Versões futuras do servidor podem mudar a forma como interpretam essas opções, e a funcionalidade do Mongoid pode não suportar essas alterações.
Campos BSON 5 BSON::Decimal128
e
Quando BSON 4 ou anterior estiver presente, qualquer campo declarado como BSON::Decimal128
retornará um valor BSON::Decimal128
. No entanto, quando BSON 5 está presente, qualquer campo declarado como BSON::Decimal128
retornará um valor BigDecimal
por padrão.
class Model include Mongoid::Document field :decimal_field, type: BSON::Decimal128 end # under BSON <= 4 Model.first.decimal_field.class #=> BSON::Decimal128 # under BSON >= 5 Model.first.decimal_field.class #=> BigDecimal
Se você precisar de valores BSON::Decimal128
literais com 5 BSON, você pode instruir o Mongoid a permitir campos BSON::Decimal128
literais:
Model.first.decimal_field.class #=> BigDecimal Mongoid.allow_bson5_decimal128 = true Model.first.decimal_field.class #=> BSON::Decimal128
Observação
A opção allow_bson5_decimal128
só tem efeito sob BSON 5 e posterior. O BSON 4 e as versões anteriores ignoram totalmente a configuração.
Gerenciamento de índice de pesquisa para MongoDB Atlas
Quando conectado ao MongoDB Atlas, o Mongoid agora suporta a criação e a remoção de índices de pesquisa. Você pode fazer isso programaticamente, por meio da API Mongoid::SearchIndexable
:
class SearchablePerson include Mongoid::Document search_index { ... } # define the search index here end # create the declared search indexes; this returns immediately, but the # search indexes may take several minutes before they are available. SearchablePerson.create_search_indexes # query the available search indexes SearchablePerson.search_indexes.each do |index| # ... end # remove all search indexes from the model's collection SearchablePerson.remove_search_indexes
Se você não estiver conectado ao MongoDB Atlas, as definições do índice de pesquisa serão ignoradas. Tentar criar, enumerar ou remover índices de pesquisa resultará em um erro.
Também há tarefas de coleta disponíveis, para conveniência:
# create search indexes for all models; waits for indexes to be created # and shows progress on the terminal. $ rake mongoid:db:create_search_indexes # as above, but returns immediately and lets the indexes be created in the # background $ rake WAIT_FOR_SEARCH_INDEXES=0 mongoid:db:create_search_indexes # removes search indexes from all models $ rake mongoid:db:remove_search_indexes
Remoção de Time.configured
Time.configured
retornou o objeto de tempo agrupando o fuso horário configurado ou a classe Ruby Time
padrão. Isso permitia que você executasse uma query de um valor de hora mesmo que nenhum fuso horário tivesse sido configurado.
O Mongoid agora exige que você defina um fuso horário se pretende fazer qualquer coisa com valores de tempo (incluindo o uso de carimbos de data/hora em seus documentos). Qualquer uso de Time.configured
deve ser substituído por Time.zone
.
# before: puts Time.configured.now # after: puts Time.zone.now # or, better for finding the current Time specifically: puts Time.current
Se você não definir um fuso zona, verá erros em seu código relacionados a valores de nil
. Se você estiver usando o Rails, o fuso zona padrão já está definido como UTC. Se você não estiver usando o Rails, você pode definir um fuso zona no início do seu programa como este:
Time.zone = 'UTC'
Isso definirá o fuso zona como UTC. Você pode ver todos os nomes de zona disponíveis executando o seguinte comando:
$ ruby -ractive_support/values/time_zone \ -e 'puts ActiveSupport::TimeZone::MAPPING.keys'
Registros lembram contexto de persistência da criação
Considere o seguinte código:
record = Model.with(collection: 'other_collection') { Model.first } record.update(field: 'value')
Antes do Mongoid v9.0, o código anterior falha silenciosamente ao executar a atualização, porque as opções de armazenamento (aqui, a especificação de uma coleção alternativa para o modelo) não seriam lembradas pelo registro. Assim, o registro seria carregado de other_collection
, mas, quando atualizado, tentaria procurar e atualizar o documento na coleção padrão do Modelo. Para fazer isso funcionar, você teria que especificar a coleção explicitamente para cada atualização.
A partir do Mongoid v9.0, registros criados ou carregados sob opções de armazenamento explícitas, lembrarão essas opções (incluindo um cliente nomeado , um banco de dados diferente ou uma collection diferente).
Se você precisar do legado (pré-v9.0) você pode habilitá-lo com a seguinte bandeira:
Mongoid.legacy_persistence_context_behavior = true
Este sinalizador é padronizado como falso no Mongoid v9.0.