/ /

ODM para Mongoid en Ruby

Configuración

Docs Home

Librerías de clientes

Ruby

ODM para Mongoid en Ruby

Configuración

Configuración de la aplicación

Overview

En esta guía, aprenderá a configurar la conexión de su aplicación a MongoDB y cómo procesa sus datos. Al configurar su aplicación, deberá proporcionar una cadena de conexión, o URI de conexión, que contiene un conjunto de instrucciones que Mongoid utiliza para conectarse a MongoDB. Para obtener más información sobre las cadenas de conexión, consulte Cadenas de conexión en el manual del servidor.

Mongoid se configura principalmente mediante un mongoid.yml Archivo que especifica las opciones de conexión y los clientes. Para obtener más información sobre cómo crear un archivo mongoid.yml al configurar una aplicación, consulte una de las siguientes guías:

Estructura de mongoid.yml

La configuración más sencilla para una aplicación configura Mongoid para conectarse a un servidor MongoDB en localhost:27017 y acceder a la base de datos myDB. El archivo mongoid.yml para esta configuración es similar al siguiente:

mongoid.yml

development:
  clients:
    default:
      database: myDB
      hosts:
        - localhost:27017

La clave de nivel superior del archivo anterior, development, se refiere al nombre del entorno donde se ejecuta la aplicación. Los valores posibles son development, test o production. La clave de tercer nivel, default, se refiere al nombre del cliente de MongoDB. La mayoría de las aplicaciones utilizan un solo cliente llamado default.

Generar configuración predeterminada

Si utiliza Ruby on Rails como marco de su aplicación, puede generar un archivo de configuración predeterminado en su aplicación ejecutando el siguiente comando de shell:

rails g mongoid:config

Este comando crea el archivo de configuración en config/mongoid.yml. También se crea un inicializador en config/initializers/mongoid.rb. Se recomienda especificar todos los ajustes en mongoid.yml, pero también puede usar el inicializador mongoid.rb para configurar las opciones. Los ajustes en mongoid.yml siempre anulan los ajustes del inicializador.

Si no está utilizando Ruby on Rails, puede crear el archivo config/mongoid.yml y luego copiar y pegar el archivo de configuración que se muestra en la sección anterior.

Cargar configuración de Mongoid

Importante

Debe configurar Mongoid antes de usar cualquier componente. Después de usar o referenciar un componente, es posible que los cambios en la configuración no se apliquen a los componentes ya instanciados.

Si está utilizando Ruby on Rails, Rails carga automáticamente su configuración de Mongoid para el entorno actual tal como está almacenado en Rails.env.

También puede especificar Mongoid como ORM para su aplicación agregando las siguientes líneas a su archivo application.rb:

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

Si no usa Ruby on Rails, debe cargar manualmente la configuración de Mongoid. Llame al método Mongoid.load!, que toma como argumento la ruta del archivo de configuración:

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

Mongoid detecta el nombre del entorno examinando las siguientes fuentes, en orden:

Si se define la constante de nivel superior Rails: Rails.env
Si se define la constante de nivel superior Sinatra: Sinatra::Base.environment
RACK_ENV variable de entorno
MONGOID_ENV variable de entorno.

Nota

También puede configurar Mongoid directamente en Ruby sin usar un archivo de configuración. Este estilo de configuración no admite el concepto de entornos. Cualquier configuración que proporcione se aplica al entorno actual.

Opciones de configuración

El siguiente archivo de ejemplo anotado mongoid.yml describe dónde establecer cada tipo de opción de configuración y proporciona información sobre cada opción y sus 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/es/docs/ruby-driver/current/connect/connection-options/
        # 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/es/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

Valores predeterminados basados en la versión

Mongoid permite configurar las opciones de configuración con sus valores predeterminados para versiones específicas. Esto puede ser útil al actualizar a una nueva versión de Mongoid. Al actualizar su versión de Mongoid, configure las siguientes opciones en Mongoid::Config:

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

Esto le permite actualizar a una nueva versión de Mongoid mientras usa las opciones de configuración de la versión anterior. Esta función le da más tiempo para implementar pruebas para cada cambio de comportamiento y garantizar que su código no falle ni se comporte de forma inesperada. Después de verificar que su aplicación funciona correctamente, puede eliminar este código para usar la configuración predeterminada de la versión actual.

Preprocesamiento de ERb

Al cargar un archivo de configuración, Mongoid lo procesa utilizando ERb antes de analizarlo como YAML. Esto permite a Mongoid construir el contenido del archivo de configuración en tiempo de ejecución basándose en variables de entorno.

Debido a que Mongoid realiza la representación de ERb antes del análisis de YAML, se evalúan todas las directivas ERb en el archivo de configuración, incluidas aquellas que aparecen en los comentarios de YAML.

El siguiente archivo de muestra mongoid.yml demuestra cómo puede hacer referencia a una variable de entorno que almacena su cadena de conexión:

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

Tip

Al generar valores desde ERb, asegúrese de que los valores sean YAML válidos y escápelos según sea necesario.

Configuración de zona horaria

Mongoid utiliza la función de zona horaria de Active Support, que ofrece más funciones que la biblioteca estándar de Ruby. Active Support permite configurar la variable Time.zone, una variable global del hilo que proporciona contexto para trabajar con valores de fecha y hora.

Puede implementar el manejo correcto de la zona horaria en su aplicación realizando los siguientes pasos:

Establezca la zona horaria del sistema operativo en UTC.
Establezca la zona horaria predeterminada de su aplicación en UTC, como se muestra en el siguiente código:
```
# If using Rails, in `application.rb`:
class Application < Rails::Application
  config.time_zone = 'UTC'
end
# If not using Rails:
Time.zone = 'UTC'
```
En cada controlador y clase de trabajo, configure la zona horaria apropiada en una devolución de llamada before_filter:
```
class ApplicationController < ActionController::Base
  before_filter :fetch_user, :set_time_zone
  def set_time_zone
    Time.zone = @user.time_zone
  end
end
```
Luego podrás trabajar con horas en la zona horaria local.
Utilice métodos de soporte activo en lugar de la biblioteca estándar de Ruby.
- Utilice los métodos Time.zone.now o Time.current en lugar de Time.now
- Utiliza el método Date.current en lugar de Date.today
Los métodos de la biblioteca estándar de Ruby, como Time.now y Date.today, hacen referencia a la zona horaria de su sistema y no al valor de la variable Time.zone.
Es posible que confundas estos métodos con nombres similares, por lo que te recomendamos usar la función Rails/TimeZone de RuboCop en tus pruebas.

Establecer zona horaria en los datos de MongoDB

MongoDB almacena todas las horas en UTC sin información de zona horaria. Los modelos de Mongoid cargan y devuelven valores de hora como instancias de ActiveSupport::TimeWithZone. Puede configurar la opción use_utc para controlar cómo Mongoid configura la zona horaria al cargar valores desde la base de datos:

false (predeterminado): Mongoid utiliza el valor de Time.zone para establecer la zona horaria de los valores de la base de datos.
true:Mongoid siempre establece la zona horaria como UTC en los valores de tiempo cargados.

La opción use_utc solo afecta la forma en que se cargan los datos y no su persistencia. Por ejemplo, si asigna una instancia Time o ActiveSupport::TimeWithZone a un campo de hora, se utiliza la información de zona horaria de la instancia asignada independientemente del valor use_utc.

Como alternativa, si asigna un valor de cadena a un campo de hora, se analiza cualquier información de zona horaria contenida en la cadena. Si la cadena no incluye información de zona horaria, se analiza según el valor Time.zone.

El siguiente código establece un valor Time.zone y muestra cómo Mongoid procesa diferentes cadenas de tiempo:

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

Configuración SSL/TLS

Puede configurar opciones avanzadas de TLS en su aplicación, como habilitar o deshabilitar ciertos cifrados. Para obtener más información sobre las principales opciones de SSL/TLS, consulte la sección "Opciones de configuración" de esta guía.

Puede configurar ganchos de contexto TLS en el controlador Ruby. Estos ganchos son objetos Proc proporcionados por el usuario que se invocan antes de crear cualquier conexión de socket TLS en el controlador. Estos ganchos pueden usarse para modificar el objeto OpenSSL::SSL::SSLContext subyacente que utiliza el socket.

Para establecer hooks de contexto TLS, agrega un Proc al arreglo Mongo.tls_context_hooks. Esta tarea puede realizarse en un inicializador. El siguiente ejemplo agrega un hook que solo habilita el cifrado "AES256-SHA":

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

Cada Proc en Mongo.tls_context_hooks recibe un objeto OpenSSL::SSL::SSLContext como su único argumento. Estos objetos Proc se ejecutan secuencialmente durante la creación del socket.

Advertencia

Los ganchos de contexto TLS son globales y afectan a todas las instancias Mongo::Client de una aplicación.

Para obtener más información sobre los ganchos de contexto TLS, consulte Modificar el contexto TLS en la documentación del controlador Ruby.

Compresión de la red

Mongoid admite la compresión de mensajes hacia y desde MongoDB. Esta funcionalidad la proporciona el controlador Ruby, que implementa los siguientes algoritmos compatibles:

Zstandard (Recomendado): Para usar la compresión zstandard, debe instalar la librería zstd-ruby. Este compresor consigue la máxima compresión con el mismo consumo de CPU comparado con los demás compresores.
Snappy: para utilizar snappy la compresión, debe instalar la biblioteca snappy.
Zlib: para utilizar zlib la compresión, debe instalar la biblioteca zlib.

Para utilizar la compresión del protocolo de cable, configure las opciones del controlador en su archivo 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"]

Si no solicita explícitamente ningún compresor, el controlador no utiliza la compresión, incluso si están instaladas las dependencias necesarias para uno o más compresores.

El controlador elige el primer compresor, si especifica varios, que sea compatible con su implementación de MongoDB.

Volver

Configuración

Objetivos de persistencia

Overview

Estructura de mongoid.yml

Generar configuración predeterminada

Cargar configuración de Mongoid

Importante

Nota

Opciones de configuración

Valores predeterminados basados ​​en la versión

Preprocesamiento de ERb

Tip

Configuración de zona horaria

Establecer zona horaria en los datos de MongoDB

Configuración SSL/TLS

Advertencia

Compresión de la red

Valores predeterminados basados en la versión