Configuration
On this page
- Generating Default Configuration
- Loading Mongoid Configuration
- Mongoid Configuration Options
- Version Based Defaults
- ERb Preprocessing
- Logging
- In Ruby on Rails Application
- Standalone
- Time Zones
- Setting time zone on data loaded from MongoDB
- Configuring
SSLContext
- Network Compression
- Client-Side Encryption
- Usage with Forking Servers
- Puma
- Unicorn
- Passenger
- Query Cache Middleware
- Enabling Query Cache for Rack Web Requests
- Enabling Query Cache for ActiveJob
- Development Configuration
Mongoid is customarily configured through a mongoid.yml
file that specifies
options and clients. The simplest configuration is as follows, which configures
Mongoid to talk to a MongoDB server at "localhost:27017" and use the database
named "mongoid".
development: clients: default: database: mongoid hosts: - localhost:27017
The top level key in the configuration file, development
in the above
example, refers to the environment name which the application is executing in,
i.e. development
, test
or production
. The third level key,
default
in the above example, refers to the Mongo client name.
Most applications will use a single client named default
.
Generating Default Configuration
If you are using Ruby on Rails, you can have Mongoid generate a default configuration file for you by running the following command:
rails g mongoid:config
The configuration file will be placed in config/mongoid.yml
. An
initializer will also be created and placed in
config/initializers/mongoid.rb
. It is recommended that all configuration
be specified in config/mongoid.yml
, but if you prefer, the mongoid.rb
initializer may also be used to set configuration options. Note, though, that
settings in mongoid.yml
always take precedence over settings in the
initializer.
If you are not using Ruby on Rails, you can copy the minimal configuration
given above and save it as config/mongoid.yml
.
Loading Mongoid Configuration
If you are using Ruby on Rails, Mongoid configuration is automatically loaded
for the current environment as stored in Rails.env
when the application
loads.
You may need to configure the ORM for your application to be Mongoid by
adding the following to application.rb
:
config.generators do |g| g.orm :mongoid end
If you are not using Ruby on Rails, Mongoid configuration must be loaded
manually. This can be done via the Mongoid.load!
method, which takes
the configuration file path as its argument, as follows:
# Use automatically detected environment name Mongoid.load!("path/to/your/mongoid.yml") # Specify environment name manually Mongoid.load!("path/to/your/mongoid.yml", :production)
When Mongoid is asked to automatically detect the environment name, it does so by examining the following sources, in order:
If
Rails
top level constant is defined,Rails.env
.If
Sinatra
top level constant is defined,Sinatra::Base.environment
.The
RACK_ENV
environment variable.The
MONGOID_ENV
environment variable.
It is also possible to configure Mongoid directly in Ruby, without using a configuration file. This configuration style does not support the concept of environments - whatever configuration is provided, it is applied to the current environment - but it does support defining multiple clients.
Mongoid.configure do |config| config.clients.default = { hosts: ['localhost:27017'], database: 'my_db', } config.log_level = :warn end
Note
Mongoid must be configured before any component of it is used or referenced. Once a component is used or referenced, changing configuration may not apply changes to already instantiated components.
Mongoid Configuration Options
The following annotated example mongoid.yml
demonstrates how Mongoid
can be configured.
Mongoid delegates to the Ruby driver for client configuration. Please review the driver documentation for details on driver options.
development: # Configure available database clients. (required) clients: # Defines the default client. (required) default: # Mongoid can connect to a URI accepted by the driver: # uri: mongodb://user:password@mongodb.domain.com:27017/my_db_development # Otherwise define the parameters separately. # This defines the name of the default database that Mongoid can connect to. # (required). database: my_db_development # Provides the hosts the default client can connect to. Must be an array # of host:port pairs. (required) hosts: - localhost:27017 options: # Note that all options listed below are Ruby driver client options (the mongo gem). # Please refer to the driver documentation of the version of the mongo gem you are using # for the most up-to-date list of options. # Change the default write concern. (default = { w: 1 }) # write: # w: 1 # Change the default read preference. Valid options for mode are: :secondary, # :secondary_preferred, :primary, :primary_preferred, :nearest # (default: primary) # read: # mode: :secondary_preferred # tag_sets: # - use: web # The name of the user for authentication. # user: 'user' # The password of the user for authentication. # password: 'password' # The user's database roles. # roles: # - 'dbOwner' # Change the default authentication mechanism. Valid options include: # :scram, :scram256, :mongodb_cr, :mongodb_x509, :gssapi, :aws, :plain. # MongoDB Server defaults to :scram, which will use "SCRAM-SHA-256" if available, # otherwise fallback to "SCRAM-SHA-1" (:scram256 will always use "SCRAM-SHA-256".) # This setting is handled by the MongoDB Ruby Driver. Please refer to: # https://mongodb.com/docs/ruby-driver/current/reference/authentication/ # auth_mech: :scram # The database or source to authenticate the user against. # (default: the database specified above or admin) # auth_source: admin # Force a the driver cluster to behave in a certain manner instead of auto- # discovering. Can be one of: :direct, :replica_set, :sharded. Set to :direct # when connecting to hidden members of a replica set. # connect: :direct # Changes the default time in seconds the server monitors refresh their status # via hello commands. (default: 10) # heartbeat_frequency: 10 # The time in seconds for selecting servers for a near read preference. (default: 0.015) # local_threshold: 0.015 # The timeout in seconds for selecting a server for an operation. (default: 30) # server_selection_timeout: 30 # The maximum number of connections in the connection pool. (default: 5) # max_pool_size: 5 # The minimum number of connections in the connection pool. (default: 1) # min_pool_size: 1 # The 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 # The time to wait to establish a connection before timing out, in seconds. # (default: 10) # connect_timeout: 10 # How long to wait for a response for each operation sent to the # server. This timeout should be set to a value larger than the # processing time for the longest operation that will be executed # by the application. Note that this is a client-side timeout; # the server may continue executing an operation after the client # aborts it with the SocketTimeout exception. # (default: nil, meaning no timeout) # socket_timeout: 5 # The name of the replica set to connect to. Servers provided as seeds that do # not belong to this replica set will be ignored. # replica_set: name # Compressors to use for wire protocol compression. (default is to not use compression) # "zstd" requires zstd-ruby gem. "snappy" requires snappy gem. # Refer to: https://www.mongodb.com/docs/ruby-driver/current/reference/create-client/#compression # compressors: ["zstd", "snappy", "zlib"] # Whether to connect to the servers via ssl. (default: false) # ssl: true # The certificate file used to identify the connection against MongoDB. # ssl_cert: /path/to/my.cert # The private keyfile used to identify the connection against MongoDB. # Note that 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 # A passphrase for the private key. # ssl_key_pass_phrase: password # Whether to do peer certification validation. (default: true) # ssl_verify: true # The 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 # Whether to truncate long log lines. (default: true) # truncate_logs: true # Configure Mongoid-specific options. (optional) options: # Allow BSON::Decimal128 to be parsed and returned directly in # field values. When BSON 5 is present and the this option is set to false # (the default), BSON::Decimal128 values in the database will be returned # as BigDecimal. # # @note this option only has effect when BSON 5+ is present. Otherwise, # the setting is ignored. # allow_bson5_decimal128: false # Application name that is printed to the MongoDB logs upon establishing # a connection. Note that the name cannot exceed 128 bytes in length. # It is also used as the database name if the database name is not # explicitly defined. (default: nil) # app_name: nil # When this flag is 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. This may lead to stack overflow errors # if there are more than cicrca 1000 embedded documents in the root # document's dependencies graph. # See https://jira.mongodb.org/browse/MONGOID-5658 for more details. # 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 # Mark belongs_to associations as required by default, so that saving a # model with a missing belongs_to association will trigger a validation # error. # belongs_to_required_by_default: true # Set the global discriminator key. # discriminator_key: "_type" # Raise 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, or it might work, depending on the situation. # immutable_ids: true # Include the root model name in json serialization. # include_root_in_json: false # # Include the _type field in serialization. # include_type_for_serialization: false # Whether to join nested persistence contexts for atomic operations # to parent contexts by default. # join_contexts: false # When this flag is false (the default as of Mongoid 9.0), a document that # is created or loaded will remember 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 you'll get pre-9.0 behavior, where a document will # not remember the storage options from when it was loaded/created, and # subsequent updates will need to explicitly set up those options each time. # # For example: # # record = Model.with(collection: 'other_collection') { Model.first } # # This will try to load the first document from 'other_collection' and # instantiate it as a Model instance. Pre-9.0, the record object would # not remember that it came from 'other_collection', and attempts to # update it or reload it would fail unless you first remembered to # explicitly specify the collection every time. # # As of Mongoid 9.0, the record will remember that it came from # 'other_collection', and updates and reloads will automatically default # to that collection, for that record object. # legacy_persistence_context_behavior: false # When this flag is false, a document will become read-only only once the # #readonly! method is called, and an error will be raised on attempting # to save or update such documents, instead of just on delete. When this # flag is true, a document is only read-only if it has been projected # using #only or #without, and read-only documents will not be # deletable/destroyable, but they will be savable/updatable. # When this feature flag is turned on, the read-only state will be reset on # reload, but when it is turned off, it won't be. # legacy_readonly: false # The log level. # # It must be set prior to referencing clients or Mongo.logger, # changes to this option are not be propagated to any clients and # loggers that already exist. # # Additionally, only when the clients are configured via the # configuration file is the log level given by this option honored. # log_level: :info # Store BigDecimals as Decimal128s instead of strings in the db. # map_big_decimal_to_decimal128: true # Preload 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. The pre-9.0 behavior leads to a problem that for multi # level nested documents callbacks are called multiple times. # See https://jira.mongodb.org/browse/MONGOID-5542 # prevent_multiple_calls_of_embedded_callbacks: true # Raise an error when performing a #find and the document is not found. # raise_not_found_error: true # Raise an error when defining a scope with the same name as an # existing method. # scope_overwrite_exception: false # Return stored times as UTC. # use_utc: false # Configure Driver-specific options. (optional) driver_options: # When this flag is off, an aggregation done on a view will be executed over # 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 will be correctly # propagated to readable methods. # broken_view_options: true # When this flag is set to true, the update and replace methods will # validate the parameters and raise an error if they are invalid. # validate_update_replace: false
Version Based Defaults
Mongoid supports setting the configuration options to the defaults for specific
versions. This is useful for upgrading to a new Mongoid version. When upgrading
your Mongoid version, the following should be set on Mongoid::Config
:
Mongoid.configure do |config| config.load_defaults <OLD VERSION> end
This way, when upgrading to a new version of Mongoid, your code will run with
the configuration options from the previous version of Mongoid. Then,
one-by-one, you can change the feature flags for the new version, and test that
your code still acts as expected. Once all of the new feature flags have been
accounted for, the call to load_defaults
may be changed to take in the new
version, and all of the changed feature flags may be removed.
For example, suppose we're upgrading from 7.5 to 8.0. Between these two versions,
two feature flags were added: legacy_attributes
and map_big_decimal_to_decimal128
.
Before upgrading to Mongoid 8, add the following to your Mongoid::Config
:
Mongoid.configure do |config| config.load_defaults 7.5 end
After upgrading to Mongoid 8.0 in your Gemfile
, any feature flags will
remain set to their 7.5 default behavior: legacy_attributes: true,
map_big_decimal_to_decimal128: false
. You may then flip these feature flags
one-by-one to their 8.0 behavior:
Mongoid.configure do |config| config.load_defaults 7.5 config.legacy_attributes = false # config.map_big_decimal_to_decimal128 = true end
We recommend do these one at a time, so in the example above we leave the
second flag commented out. After verifying your code works as expected with the
legacy_attributes
flag turned off, the map_big_decimal_to_decimal128
setting can be uncommented. Once that functionality is verified as well, both
of those lines can be removed and the load_defaults
replaced with:
Mongoid.configure do |config| config.load_defaults 8.0 end
ERb Preprocessing
When loading a configuration file, Mongoid processes it with ERb before parsing it as YAML. This allows, for example, constructing the contents of the configuration file at runtime based on environment variables:
development: clients: default: uri: "<%= ENV['MONGODB_URI'] %>"
Note
When outputting values from ERb, ensure the values are valid YAML and escape them as needed.
Note
Since ERb rendering is performed prior to YAML parsing, all ERb directives in the configuration file are evaluated, including those occurring in YAML comments.
Logging
When configuring logging, it is important to keep in mind that Mongoid provides a model layer on top of the MongoDB Ruby driver, and the driver dispatches the CRUD operations to the MongoDB deployment. Therefore, some of the logging output in an application using Mongoid comes from Mongoid itself, and some comes from the driver.
The Mongo client is a Ruby driver client instance, therefore the logger of a Mongo client is the Ruby driver logger, not the Mongoid logger. In other words:
# Ruby driver logger, not Mongoid logger Mongoid.client(:default).logger
Depending on whether Mongoid is used in a Ruby on Rails application, and how both Mongoid and Ruby driver are configured, they may use the same logger instance or different instances, potentially with different configurations.
In Ruby on Rails Application
When used in a Ruby on Rails application, Mongoid by default inherits the logger and the log level from Rails, and sets the driver's logger to the same logger instance:
Rails.logger === Mongoid.logger # => true Mongoid.logger === Mongo::Logger.logger # => true
To change the log level, use standard Rails configuration.
Place the following in one of environment configuration files, such as
config/environments/production.rb
:
Rails.application.configure do config.log_level = :debug end
Note
The log_level
Mongoid configuration option is not used when Mongoid operates
in a Rails application, because Mongoid inherits Rails' log level in this case.
To configure either Mongoid or driver logger differently from the Rails logger, use an initializer as follows:
Rails.application.configure do config.after_initialize do # Change Mongoid log destination and/or level Mongoid.logger = Logger.new(STDERR).tap do |logger| logger.level = Logger::DEBUG end # Change driver log destination and/or level Mongo::Logger.logger = Logger.new(STDERR).tap do |logger| logger.level = Logger::DEBUG end end end
Note
There is currently no provision in the Ruby standard library Logger
to return the log device (i.e. the IO
object) that a logger is using.
To have, for example, Mongoid and/or the Ruby driver log to the
standard Rails log file (e.g. log/development.log
) but with a
different level from standard Rails logger (Rails.logger
), the
file must be opened separately and the resulting IO
object passed to
the Logger
constructor.
Note
Since by default Mongoid sets its own logger and the driver's logger to the
same instance as the Rails logger, modifying any of the instances affects
all of them. For example the following changes log level for all three
loggers, unless the application assigned a separate Logger
instance
to Mongo::Logger.logger
as described above:
Mongoid::Logger.logger.level = Logger::DEBUG
Standalone
When not loaded in a Ruby on Rails application, Mongoid respects the
log_level
top level configuration option. It can be given in the
configuration file as follows:
development: clients: default: # ... options: log_level: :debug
... or when configuring Mongoid inline:
Mongoid.configure do |config| config.log_level = :debug end
The default log destination in Mongoid 7.1 and higher is standard error. The default log destination in Mongoid 7.0 and lower is standard output. To change the log destination, create a new logger instance as follows:
Mongoid.logger = Logger.new(STDERR).tap do |logger| logger.level = Logger::DEBUG end
To change the Ruby driver log level or destination:
Mongo::Logger.logger = Logger.new(STDERR).tap do |logger| logger.level = Logger::DEBUG end
To set the driver logger to be the same as the Mongoid logger:
Mongo::Logger.logger = Mongoid.logger
Note
Mongoid does not alter the driver's logger when running in standalone mode.
Time Zones
Mongoid uses ActiveSupport's time zone functionality, which is far
more robust than Ruby's standard library. Importantly, ActiveSupport
allows configuration of Time.zone
, a thread-global variable which
provides context for working with date and time values.
While a thorough treatment of time zones in Ruby is outside the scope of this tutorial, the easiest and most reliable way of achieving correct time zone handling is as follows:
Set the operating system's time zone to UTC. For example, on Linux:
cp /usr/share/zoneinfo/UTC /etc/localtime
Set your application default time zone to UTC:
# If using Rails, in application.rb: class Application < Rails::Application config.time_zone = 'UTC' end # If not using Rails: Time.zone = 'UTC'
In each controller and job class, set the appropriate time zone in a
before_filter
at the earliest possible stage. As an example, if each user of your application can set their own time zone, you may wish to do:
class ApplicationController < ActionController::Base before_filter :fetch_user, :set_time_zone def set_time_zone Time.zone = @user.time_zone end end
From here, you may work with times naturally in the local time zone. For example, in a view:
Turned into a pumpkin after <%= cinderella.updated_at.seconds_after_midnight %> seconds!
Use ActiveSupport methods instead of the Ruby standard library.
Time.zone.now
orTime.current` instead of ``Time.now
Date.current
instead ofDate.today
Critically, note that the latter Ruby standard library methods reference your system time zone (e.g. UTC) and not the value of
Time.zone
. As it is very easy to mistake these similarly named methods, we recommend to use Rubocop's Rails/TimeZone cop in your CI.
Setting time zone on data loaded from MongoDB
MongoDB stores all times in UTC without time zone information.
Mongoid models load and returns time values as instances of
ActiveSupport::TimeWithZone
. You may set the use_utc
option
to control how Mongoid sets the time zone when loading from the database:
If false (default), Mongoid will use
Time.zone
to set the time zone of time values are loaded from database.If true, Mongoid will always set the time zone as UTC on loaded time values.
use_utc
only affects how data is loaded, and does not affect
how data is persisted. For example, if you assign a Time
or
ActiveSupport::TimeWithZone
instance to a time field, the time
zone information of the assigned instance always will be used
irrespective of the use_utc
setting. Alternatively, if you
assign a string value to a time field, any time zone information
in the string will be used if present. If the string does not include
time zone information it will be parsed according to Time.zone
.
To illustrate:
Time.use_zone("Asia/Kolkata") do # String does not include time zone, so "Asia/Kolkata" will be used ghandi.born_at = "1869-10-02 7:10 PM" # Time zone in string (-0600) will be used amelia.born_at = "1897-07-24 11:30 -0600" end
Configuring SSLContext
It may be desirable to further configure TLS options in your application, for example by enabling or disabling certain ciphers.
This can be done by setting TLS context hooks on the Ruby driver -- TLS context
hooks are user-provided Proc
(s) that will be invoked before any TLS socket
connection in the driver and can be used to modify the underlying
OpenSSL::SSL::SSLContext
object used by the socket.
To set TLS context hooks, add Proc
(s) to the Mongo.tls_context_hooks
array. This can be done in an initializer. The example below adds a hook
that only enables the "AES256-SHA" cipher.
Mongo.tls_context_hooks.push( Proc.new { |context| context.ciphers = ["AES256-SHA"] } ) # Only the AES256-SHA cipher will be enabled from this point forward
Every Proc
in Mongo.tls_context_hooks
will be passed an
OpenSSL::SSL::SSLContext
object as its sole argument. These procs will
be executed sequentially during socket creation.
Warning
TLS context hooks are global and will affect all Mongo::Client
instances
in an application.
For more information about TLS context hooks, including best practices for assigning and removing them, see the Ruby driver documentation.
Network Compression
Mongoid supports compression of messages to and from MongoDB servers. This functionality is provided by the Ruby driver, which implements the three algorithms that are supported by MongoDB servers:
Snappy:
snappy
compression can be used when connecting to MongoDB servers starting with the 3.4 release, and requires the snappy library to be installed.Zlib:
zlib
compression can be used when connecting to MongoDB servers starting with the 3.6 release.Zstandard:
zstd
compression can be used when connecting to MongoDB servers starting with the 4.2 release, and requires the zstd-ruby library to be installed.
To use wire protocol compression, configure the Ruby driver options within mongoid.yml
:
development: # Configure available database clients. (required) clients: # Define the default client. (required) default: # ... options: # These options are Ruby driver options, documented in # https://mongodb.com/docs/ruby-driver/current/reference/create-client/ # ... # Compressors to use. (default is to not use compression) # Valid values are zstd, zlib or snappy - or any combination of the three compressors: ["zstd", "snappy"]
If no compressors are explicitly requested, the driver will not use compression, even if the required dependencies for one or more compressors are present on the system.
The driver chooses the first compressor of the ones requested that is also supported
by the server. The zstd
compressor is recommended as it produces the highest
compression at the same CPU consumption compared to the other compressors.
For maximum server compatibility all three compressors can be specified, e.g.
as compressors: ["zstd", "snappy", "zlib"]
.
Client-Side Encryption
When loading the configuration file, Mongoid permits the file to contain
BSON::Binary
instances which are used for specifying keyId
in
the schema map for client-side encryption,
as the following example shows:
development: clients: default: database: blog_development hosts: [localhost:27017] options: auto_encryption_options: key_vault_namespace: 'keyvault.datakeys' kms_providers: local: key: "z7iYiYKLuYymEWtk4kfny1ESBwwFdA58qMqff96A8ghiOcIK75lJGPUIocku8LOFjQuEgeIP4xlln3s7r93FV9J5sAE7zg8U" schema_map: blog_development.comments: properties: message: encrypt: keyId: - !ruby/object:BSON::Binary data: !binary |- R/AgNcxASFiiJWKXqWGo5w== type: :uuid bsonType: "string" algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" bsonType: "object"
Usage with Forking Servers
When using Mongoid with a forking web server such as Puma, or any application that otherwise forks to spawn child processes, special considerations apply.
If possible, we recommend to not perform any MongoDB operations in the parent process prior to forking, which will avoid any forking-related pitfalls.
A detailed technical explanation of how the Mongo Ruby Driver handles forking
is given in the driver's "Usage with Forking Servers" documentation
<https://www.mongodb.com/docs/ruby-driver/current/reference/create-client/#usage-with-forking-servers>
.
In a nutshell, to avoid various connection errors such as Mongo::Error::SocketError
and Mongo::Error::NoServerAvailable
, you must do the following:
Disconnect MongoDB clients in the parent Ruby process immediately before forking using
Mongoid.disconnect_clients
. This ensures the parent and child process do not accidentally reuse the same sockets and have I/O conflicts. Note thatMongoid.disconnect_clients
does not disrupt any in-flight MongoDB operations, and will automatically reconnect when you perform new operations.Reconnect your MongoDB clients in the child Ruby process immediately after forking using
Mongoid.reconnect_clients
. This is required to respawn the driver's monitoring threads in the child process.
Most web servers provide hooks that can be used by applications to perform actions when the worker processes are forked. The following are configuration examples for several common Ruby web servers.
Puma
Use the on_worker_boot
hook to reconnect clients in the workers and
the before_fork
and on_refork
hooks to close clients in the
parent process (Puma documentation).
# config/puma.rb # Runs in the Puma master process before it forks a child worker. before_fork do Mongoid.disconnect_clients end # Required when using Puma's fork_worker option. Runs in the # child worker 0 process before it forks grandchild workers. on_refork do Mongoid.disconnect_clients end # Runs in each Puma child process after it forks from its parent. on_worker_boot do Mongoid.reconnect_clients end
Unicorn
Use the after_fork
hook to reconnect clients in the workers and
the before_fork
hook to close clients in the parent process
(Unicorn documentation):
# config/unicorn.rb before_fork do |_server, _worker| Mongoid.disconnect_clients end after_fork do |_server, _worker| Mongoid.reconnect_clients end
Passenger
Use the starting_worker_process
hook to reconnect clients in the workers
(Passenger documentation).
Passenger does not appear to have a hook that is invoked in the parent process
before the workers are forked.
if defined?(PhusionPassenger) PhusionPassenger.on_event(:starting_worker_process) do |forked| Mongoid.reconnect_clients if forked end end
Query Cache Middleware
Enabling Query Cache for Rack Web Requests
The MongoDB Ruby Driver provides a Rack middleware which enables the Query Cache for the duration of each web request. Below is an example of how to enable the Query Cache Middleware in a Ruby on Rails application:
# config/application.rb # Add Mongo::QueryCache::Middleware at the bottom of the middleware stack # or before other middleware that queries MongoDB. config.middleware.use Mongo::QueryCache::Middleware
Please refer to the Rails on Rack guide for more information about using Rack middleware in Rails applications.
Enabling Query Cache for ActiveJob
The MongoDB Ruby Driver also provides Query Cache middleware for ActiveJob. You may enable it for all jobs in an initializer:
# config/initializers/active_job.rb # Enable Mongo driver query cache for ActiveJob ActiveSupport.on_load(:active_job) do include Mongo::QueryCache::Middleware::ActiveJob end
Or for a specific job class:
class MyJob < ActiveJob::Base include Mongo::QueryCache::Middleware::ActiveJob end
Development Configuration
Driver's default configuration is suitable for production deployment. In development, some settings can be adjusted to provide a better developer experience.
:server_selection_timeout
: set this to a low value (e.g.,1
) if your MongoDB server is running locally and you start it manually. A low server selection timeout will cause the driver to fail quickly when there is no server running.
Sample recommended development configuration:
development: clients: default: database: mongoid hosts: - localhost:27017 options: server_selection_timeout: 1