Menu Docs

Configuração do aplicativo

Neste guia, você pode aprender a configurar como seu aplicação se conecta ao MongoDB e como ele processa seus dados. Ao configurar seu aplicação, você é obrigado a fornecer uma string de conexão ou URI de conexão , que contém um conjunto de instruções que o Mongoid usa para se conectar a um MongoDB. Para saber mais sobre connection strings, consulte Connection strings no manual do servidor.

Você configura principalmente o Mongoid usando um arquivo mongoid.yml que especifica suas opções e clientes de conexão. Para saber mais sobre como criar um arquivo mongoid.yml ao configurar um aplicação, consulte um dos seguintes guias:

A configuração mais simples de um aplicação configura o Mongoid para se conectar a um servidor MongoDB em localhost:27017 e acessar o banco de dados denominado myDB. O arquivo mongoid.yml para esta configuração se assemelha ao seguinte arquivo:

mongoid.yml
development:
clients:
default:
database: myDB
hosts:
- localhost:27017

A chave de nível superior no arquivo anterior, development, refere-se ao nome do ambiente em que o aplicação está sendo executado. Os valores possíveis incluem development, test ou production. A chave de terceiro nível, default, refere-se ao nome do cliente MongoDB . A maioria dos aplicativos utiliza um único cliente denominado default.

Se você estiver usando Ruby on Rails como estrutura do aplicação , aplicação gerar um arquivo de configuração padrão executando o seguinte comando shell:

rails g mongoid:config

Este comando cria o arquivo de configuração em config/mongoid.yml. Um inicializador também é criado em config/initializers/mongoid.rb. Recomendamos que você especifique todas as configurações no mongoid.yml, mas você também pode usar o inicializador mongoid.rb para definir as opções de configuração. As configurações em mongoid.yml sempre substituem as configurações no inicializador.

Se você não estiver usando Ruby on Rails, crie o arquivo config/mongoid.yml e, em seguida, copie e cole o arquivo de configuração mostrado na seção anterior.

Importante

Você deve configurar o Mongoid antes de usar qualquer componente Mongoid. Depois de usar ou fazer referência a um componente, a alteração da configuração pode não aplicar alterações aos componentes já instanciados.

Se você estiver utilizando Ruby on Rails, o Rails carregará automaticamente sua configuração Mongoid para o ambiente atual como armazenado no Rails.env.

Você também pode especificar Mongoid como o ORM para seu aplicação adicionando as seguintes linhas ao seu arquivo application.rb:

config.generators do |g|
g.orm :mongoid
end

Se você não estiver usando Ruby on Rails, deverá carregar sua configuração Mongoid manualmente. Chame o método Mongoid.load!, que usa o caminho do arquivo de configuração como argumento:

# Uses automatically detected environment name
Mongoid.load!("config/mongoid.yml")
# Specifies environment name manually
Mongoid.load!("config/mongoid.yml", :development)

O Mongoid detecta o nome do ambiente examinando as seguintes fontes, em ordem:

  1. Se Rails constante de nível superior estiver definida: Rails.env

  2. Se Sinatra constante de nível superior estiver definida: Sinatra::Base.environment

  3. RACK_ENV variável de ambiente

  4. Variável de ambiente do MONGOID_ENV.

Observação

Você também pode configurar o Mongoid diretamente no Ruby sem usar um arquivo de configuração. Esse estilo de configuração não suporta o conceito de ambientes. Qualquer configuração fornecida é aplicada ao ambiente atual.

O arquivo de exemplo mongoid.yml anotado descreve onde definir cada tipo de opção de configuração e fornece informações sobre cada opção e seus parâmetros.

development:
# Configures available database clients. (required)
clients:
# Defines the default client. (required)
default:
# Supplies your connection URI, including the database name.
uri: mongodb+srv://user:pass@mongo0.example.com/myDB
# OR, you can define the parameters separately.
# Defines the name of the default database. (required)
database: my_db_development
# Provides the hosts the client can connect to.
# Must be an array of host:port pairs. (required)
hosts:
- localhost:27017
options:
# All options in this section are Ruby driver client options.
# To learn more, visit
# https://www.mongodb.com/docs/ruby-driver/current/reference/create-client/
# Sets the write concern. (default = { w: 1 })
write:
w: 1
# Sets the read preference. Valid options for mode are: :secondary,
# :secondary_preferred, :primary, :primary_preferred, :nearest
# (default: primary)
read:
mode: :secondary_preferred
tag_sets: # If using tag sets
- use: web
# Sets name of the user for authentication.
user: "user"
# Sets password of the user for authentication.
password: "password"
# Sets user's database roles.
roles:
- "dbOwner"
# Sets the authentication mechanism. Valid options include:
# :scram, :scram256, :mongodb_cr, :mongodb_x509, :gssapi, :aws, :plain
# MongoDB Server defaults to :scram
auth_mech: :scram
# Sets the database or source to authenticate the user against.
# (default: the database specified above or admin)
auth_source: admin
# Specifies type of connection. Can be one of: :direct,
# :replica_set, :sharded
# Set to :direct when connecting to hidden members of a replica set.
connect: :direct
# Changes the time taken for the server monitors to refresh
# their status via hello commands. (default: 10)
heartbeat_frequency: 10
# Sets time in seconds for selecting servers for a :nearest read
# preference. (default: 0.015)
local_threshold: 0.015
# Sets timeout in seconds for selecting a server for an
# operation. (default: 30)
server_selection_timeout: 30
# Sets maximum number of connections in the connection pool.
# (default: 5)
max_pool_size: 5
# Sets minimum number of connections in the connection pool.
# (default: 1)
min_pool_size: 1
# Sets time to wait, in seconds, in the connection pool for a
# connection to be checked in before timing out. (default: 5)
wait_queue_timeout: 5
# Sets time to wait to establish a connection before timing out,
# in seconds. (default: 10)
connect_timeout: 10
# Sets name of the replica set to connect to. Servers provided as
# seeds that do not belong to this replica set are ignored.
replica_set: myRS
# Sets compressors to use for wire protocol compression.
# (default is to not use compression)
compressors: ["zstd", "snappy", "zlib"]
# Specified whether to connect to the servers by using ssl.
# (default: false)
ssl: true
# Sets certificate file used to identify the connection for SSL.
ssl_cert: /path/to/my.cert
# Sets private keyfile used to identify the connection against MongoDB.
# Even if the key is stored in the same file as the certificate,
# both need to be explicitly specified.
ssl_key: /path/to/my.key
# Sets passphrase for the private key.
ssl_key_pass_phrase: password123
# Specifies whether to do peer certification validation.
# (default: true)
ssl_verify: true
# Sets file containing concatenated certificate authority
# certificates used to validate certs passed from the other end
# of the connection.
ssl_ca_cert: /path/to/ca.cert
# Specifies whether to truncate long log lines. (default: true)
truncate_logs: true
# Optional Mongoid-specific configuration.
options:
# Allows BSON::Decimal128 to be parsed and returned directly in
# field values. Only has effect when BSON 5+ is present.
allow_bson5_decimal128: false
# Allows duplicate indexes to be declared and sent
# to the server. The server then validates the indexes and raises an
# exception if duplicate indexes are detected. When false, indexes
# are validated on the client, which can lead to some indexes
# getting silently ignored even if they are not duplicates.
# (default: false)
allow_duplicate_index_declarations: false
# Sets app name that is printed to the MongoDB logs upon establishing
# a connection. Value is used as the database name if the database
# name is not provided. (default: nil)
app_name: nil
# When false, callbacks for embedded documents will not be
# called. This is the default in 9.0.
# Setting this flag to true restores the pre-9.0 behavior, where callbacks
# for embedded documents are called, which might lead to stack overflow errors.
around_callbacks_for_embeds: false
# Sets the async_query_executor for the application. By default the
# thread pool executor is set to :immediate. Options are:
# - :immediate - Initializes a single +Concurrent::ImmediateExecutor+
# - :global_thread_pool - Initializes a single +Concurrent::ThreadPoolExecutor+
# that uses the +async_query_concurrency+ for the +max_threads+ value.
async_query_executor: :immediate
# Marks belongs_to associations as required by default, so saving a
# model with a missing association triggers a validation error.
belongs_to_required_by_default: true
# Sets the global discriminator key.
discriminator_key: "_type"
# Raises an exception when a field is redefined.
duplicate_fields_exception: false
# Defines how many asynchronous queries can be executed concurrently.
# This option should be set only if `async_query_executor` is set
# to `:global_thread_pool`.
global_executor_concurrency: nil
# When this flag is true, any attempt to change the _id of a persisted
# document will raise an exception (Errors::ImmutableAttribute).
# This is the default in 9.0. Setting this flag to false restores the
# pre-9.0 behavior, where changing the _id of a persisted
# document might be ignored.
immutable_ids: true
# Includes the root model name in json serialization.
include_root_in_json: false
# # Include the _type field in serialization.
include_type_for_serialization: false
# Specifies whether to join nested persistence contexts for atomic
# operations to parent contexts.
join_contexts: false
# When this flag is false (the default for 9.0), a document that
# is created or loaded remembers the storage options that were active
# when it was loaded, and will use those same options by default when
# saving or reloading itself.
#
# When this flag is true, a document does not remember the storage
# options from when it was loaded/created, and
# subsequent updates will need to explicitly set up those options
# each time.
legacy_persistence_context_behavior: false
# Specifies whether to use legacy read-only behavior. To learn more,
# visit https://www.mongodb.com/docs/mongoid/current/interact-data/crud
legacy_readonly: false
# Sets the log level. This must be set before referencing clients
# or Mongo.logger, because changes to this option are not be
# propagated to any clients and loggers that already exist.
log_level: :info
# Stores BigDecimals as Decimal128s instead of strings in the db.
map_big_decimal_to_decimal128: true
# Preloads all models in development, needed when models use
# inheritance.
preload_models: false
# When this flag is true, callbacks for every embedded document will be
# called only once, even if the embedded document is embedded in multiple
# documents in the root document's dependencies graph.
# This is the default in 9.0. Setting this flag to false restores the
# pre-9.0 behavior, where callbacks are called for every occurrence of an
# embedded document.
prevent_multiple_calls_of_embedded_callbacks: true
# Raises an error when performing a find operation and no document
# matches.
raise_not_found_error: true
# Raises an error when defining a scope with the same name as an
# existing method.
scope_overwrite_exception: false
# Returns stored times as UTC.
use_utc: false
# Optional driver-specific configuration.
driver_options:
# When this flag is off, an aggregation done on a view is performed on
# the documents included in that view, instead of all documents in the
# collection. When this flag is on, the view filter is ignored.
broken_view_aggregate: true
# When this flag is set to false, the view options is correctly
# propagated to readable methods.
broken_view_options: true
# When this flag is set to true, the update and replace methods
# validate the parameters and raise an error if they are invalid.
validate_update_replace: false

O Mongoid suporta a definição das opções de configuração para seus valores padrão para versões específicas. Isso pode ser útil para quando você atualizar para uma nova versão Mongoid. Ao atualizar sua versão Mongoid, defina as seguintes opções em Mongoid::Config:

Mongoid.configure do |config|
config.load_defaults <older version>
end

Isso permite que você atualize para uma nova versão do Mongoid enquanto usa as opções de configuração da versão instalada anterior. Esse recurso dá a você mais tempo para implementar testes para cada comportamento alterado, para garantir que seu código não quebre ou se comporte de maneiras inesperadas. Depois de verificar se o aplicação funciona conforme o esperado, você pode remover esse código para usar a configuração padrão da versão atual.

Ao carregar um arquivo de configuração, o Mongoid processa usando ERb antes de analisá-lo como YAML. Isso permite que o Mongoid construa o conteúdo do arquivo de configuração no tempo de execução com base em variáveis de ambiente.

Como o Mongoid executa a renderização de ERb antes da análise de YAML, todas as diretivas ERb no arquivo de configuração são avaliadas, incluindo aquelas que ocorrem nos comentários de YAML.

O seguinte arquivo de amostra de mongoid.yml demonstra como você pode referenciar uma variável de ambiente que armazena sua string de conexão:

development:
clients:
default:
uri: "<%= ENV['MONGODB_URI'] %>"

Dica

Ao emitir valores de ERb, verifique se os valores são YAML válidos e escape-os conforme necessário.

O Mongoid usa a funcionalidade de zona horário do Active Support, que oferece mais funcionalidades do que a biblioteca padrão do Ruby. O Suporte Active permite a configuração da variável Time.zone, uma variável global de thread que fornece contexto para trabalhar com valores de data e hora.

Você pode implementar o tratamento correto de zona horário em seu aplicação executando as seguintes etapas:

  1. Configure o fuso horário do sistema operacional para UTC.

  2. Defina o zona horário padrão do seu aplicação para UTC, como mostrado no seguinte código:

    # If using Rails, in `application.rb`:
    class Application < Rails::Application
    config.time_zone = 'UTC'
    end
    # If not using Rails:
    Time.zone = 'UTC'
  3. Em cada controlador e classe de tarefa , defina o zona horário apropriado em um chamada de resposta before_filter :

    class ApplicationController < ActionController::Base
    before_filter :fetch_user, :set_time_zone
    def set_time_zone
    Time.zone = @user.time_zone
    end
    end
  4. Em seguida, você pode trabalhar com horários no zona horário local.

  5. Use métodos do Active Support em vez da biblioteca padrão Ruby.

    • Use os métodos Time.zone.now ou Time.current em vez de Time.now

    • Usar o método Date.current em vez de Date.today

    Os métodos da biblioteca padrão Ruby, como Time.now e Date.today, fazem referência ao zona horário do sistema e não ao valor da variável Time.zone.

    Você pode confundir esses métodos com nomes semelhantes, por isso recomendamos usar o recurso Rails/TimeZone do RuboCop em seus testes.

O MongoDB armazena todos os horários em UTC sem informações de zona horário. Os modelos Mongoid carregam e retornam valores de tempo como instâncias de ActiveSupport::TimeWithZone. Você pode definir a opção use_utc para controlar como o Mongoid define o zona horário ao carregar valores do banco de dados:

  • false (padrão): o Mongoid usa o valorde Time.zone para definir o zona horário dos valores do banco de dados.

  • true: o Mongoid sempre define o zona horário como UTC em valores de hora carregados.

A opção use_utc afeta somente como os dados são carregados e não afeta como os dados são persistidos. Por exemplo, se você atribuir uma instância Time ou ActiveSupport::TimeWithZone a um campo de tempo, as informações de zona horário da instância atribuída serão utilizadas independentemente do valor use_utc.

Como alternativa, se você atribuir um valor de string a um campo de tempo , qualquer informação de zona horário na string será analisada. Se a string não incluir informações de zona horário, ela será analisada de acordo com o valor Time.zone.

O seguinte código define um valor Time.zone e demonstra como o Mongoid processa diferentes strings de tempo:

Time.use_zone("Asia/Kolkata") do
# String does not include time zone, so "Asia/Kolkata" is used
ghandi.born_at = "1869-10-02 7:10 PM"
# Time zone in string (-0600) is used
amelia.born_at = "1897-07-24 11:30 -0600"
end

Você pode configurar opções avançadas de TLS em seu aplicação, como ativar ou desativar determinadas cifras. Para saber mais sobre as principais opções de SSL/TLS, consulte a seção Opções de configuração deste guia.

Você pode definir ganchos de contexto TLS no driver Ruby. Os hooks de contexto TLS são objetos Proc fornecidos pelo usuário que são invocados antes que qualquer conexão de soquete TLS seja criada no driver. Estes ganchos podem ser utilizados para modificar o objeto OpenSSL::SSL::SSLContext subjacente utilizado pelo soquete.

Para definir hooks de contexto TLS, adicione um Proc à array Mongo.tls_context_hooks. Esta tarefa pode ser feita em um inicializador. O exemplo a seguir adiciona um gancho que habilita apenas a cifra "AES256-SHA":

Mongo.tls_context_hooks.push(
Proc.new { |context|
context.ciphers = ["AES256-SHA"]
}
)

Cada Proc em Mongo.tls_context_hooks recebe um objeto OpenSSL::SSL::SSLContext como seu único argumento. Estes objetos Proc são executados sequencialmente durante a criação do soquete.

Aviso

Os hooks de contexto TLS são globais e afetam todas as instâncias Mongo::Client em um aplicação.

Para saber mais sobre os hooks de contexto TLS, consulte Modificando o SSLContext na documentação do driver Ruby.

O Mongoid suporta compressão de mensagens de e para MongoDB. Essa funcionalidade é fornecida pelo driver Ruby, que implementa os seguintes algoritmos compatíveis:

  • Padrão Z (recomendado): para usar zstandard a compactação, você deve instalar a biblioteca zstd-ruby . Este compressor produz a maior compressão com o mesmo consumo de CPU em comparação com os outros compressores.

  • Snappy: Para usar snappy a compactação, você deve instalar a biblioteca snappy.

  • zlib: para usar zlib a compactação, você deve instalar a biblioteca zlib.

Para usar a compactação do protocolo de conexão , configure as opções do driver no arquivo mongoid.yml:

development:
clients:
default:
...
options:
# Specify compresses to use. (default is no compression)
# Accepted values are zstd, zlib, snappy, or a combination
compressors: ["zstd", "snappy"]

Se você não solicitar explicitamente nenhum compressor, o driver não usará a compactação, mesmo que as dependências necessárias para um ou mais compressores estejam instaladas.

O driver escolhe o primeiro compressor, se você especificar vários, que é suportado pelo seu sistema do MongoDB .