/ /

Conéctese a MongoDB

Overview

En este guía, puedes aprender a configurar cómo tu aplicación se conecta a MongoDB y cómo procesa tus datos. Cuando configures tu aplicación, debes proporcionar una cadena de conexión, o URI de conexión, que contiene un conjunto de instrucciones que Mongoid utiliza para conectarse a una base de datos MongoDB. Para aprender más sobre cadenas de conexión, consulta Cadenas de conexión en el Manual del servidor.

Mongoid se configura principalmente mediante un mongoid.yml archivo que especifica tus opciones de conexión y clientes. Para obtener más información sobre cómo crear un archivo mongoid.yml al configurar una aplicación, vea 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 en el archivo anterior, development, hace referencia al nombre del entorno en el que se ejecuta la aplicación. Los valores posibles incluyen 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 único cliente llamado default.

Generar configuración por defecto

Si estás utilizando Ruby on Rails como tu marco de trabajo de aplicación, puedes generar un archivo de configuración predeterminado en tu 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. Recomendamos que especifiques todos los ajustes en mongoid.yml, pero también puedes usar el inicializador mongoid.rb para establecer las opciones de configuración. La configuración en mongoid.yml siempre anula la configuración en el 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 se está utilizando Ruby on Rails, Rails carga automáticamente su configuración de Mongoid para el entorno actual tal como se almacena en Rails.env.

También puedes especificar Mongoid como el ORM para tu aplicación agregando las siguientes líneas a tu 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 utilizar un archivo de configuración. Este estilo de configuración no admite el concepto de entornos. Cualquier configuración que proporciones se aplicará 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 por defecto basados en versiones

Mongoid admite establecer opciones de configuración a sus valores por defecto para versiones específicas. Esto podría ser útil cuando actualices a una nueva versión de Mongoid. Al actualizar tu versión de Mongoid, configura las siguientes opciones en Mongoid::Config:

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

Esto permite actualizar a una nueva versión de Mongoid utilizando las opciones de configuración de la versión previamente instalada. Esta funcionalidad le brinda más tiempo para implementar pruebas para cada comportamiento modificado y así asegurarse de que su código no se interrumpa ni tenga comportamientos inesperados. Una vez que verifiques que tu aplicación funciona como se esperaba, puedes remover este código para usar la configuración por defecto de la versión actual.

Pre-procesamiento ERb

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

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

El siguiente archivo de mongoid.yml muestra demuestra cómo puedes hacer referencia a una variable de entorno que almacene tu 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 por defecto de su aplicación a 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 clase de controlador y tarea, configura la zona horaria adecuada en una before_filter función de retorno:
```
class ApplicationController < ActionController::Base
  before_filter :fetch_user, :set_time_zone
  def set_time_zone
    Time.zone = @user.time_zone
  end
end
```
Después, puedes trabajar con horarios en la zona horaria local.
Usa los métodos de Active Support en lugar de la librería 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.

Configurar la 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 tiempo como instancias de ActiveSupport::TimeWithZone. Puede configurar la opción use_utc para controlar cómo Mongoid establece 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 afecta cómo se guardan los datos. Por ejemplo, si asignas una instancia Time o ActiveSupport::TimeWithZone a un campo de hora, la información de zona horaria de la instancia asignada se utiliza independientemente del valor de use_utc.

Alternativamente, si asignas un valor de string a un campo de tiempo, cualquier información de zona horaria en la string será analizada. Si la string no incluye información sobre la zona horaria, se analiza según el valor de 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 hooks de contexto TLS son globales y afectan a todas las instancias de Mongo::Client en 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 driver 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 conexión, configurá las opciones del driver en tu 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 driver no utiliza compresión, incluso si las dependencias necesarias para uno o más compresores están instaladas.

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

Volver

Para empezar: Sinatra

Servidores de bifurcación