Installation and Settings


The MongoDB module and sub-modules need some configuration to be useful. This guide assumes that :

  • A MongoDB 3.0 to 4.0 server instance is already installed, configured and available for connection from the Drupal instance.
  • The site will be running Drupal 8.6.x or 8.7.x, with Drush 9.x.
  • The mongodb (not mongo) PHP extension version 1.1.7 or later is installed and configured.
  • PHP is version 7.1.x to 7.2.x. PHP 7.3.x might work but is not tested: be sure to report any issue you could have with it.
  • We recommend using Composer for installing this module.

Check out the MongoDB extension and library for PHP

Installing MongoDB itself is best explained in these official resources maintained by MongoDB Inc.:

If MongoDB 3.0 to 3.51 is installed on localhost:27017 and the mongod server was started with the –httpinterface option, you may view the web admin interface:


Settings Configuration

  • Download the module package, as per Installing contributed modules (Drupal 8)
  • Copy the relevant section from mongodb/example.settings.local.php to your settings.local.php file if you use one, or settings.php otherwise, and adapt it to match your MongoDB settings. These settings are used by the mongodb module to connect to your MongoDB servers, with the default server being the one started in previous steps.
  • The clients key contains an associative array of connection by connection alias, with the default connection parameters being under the default key, and additional keys allowing the use of other servers/clusters.
  • The databases key contains an associative array of server/database pairs by database alias, with the default Drupal database being under the default key, and additional keys allowing modules to use their own database to avoid stepping on each other's toes. This is especially useful for bespoke modules created for the needs of a specific site, which can thus use their own databases, possibly located on other MongoDB clusters. For example, with the following settings:
// In sites/default/settings.local.php.
$settings['mongodb'] = [
  'clients' => [
    // Client alias => connection constructor parameters.
    'default' => [
      'uri' => 'mongodb://localhost:27017',
      'uriOptions' => [],
      'driverOptions' => [],
  'databases' => [
    // Database alias => [ client_alias, database_name ]
    'default' => ['default', 'drupal'],
    'keyvalue' => ['default', 'keyvalue'],
    'logger' => ['default', 'logger'],
  • With these settings:
    • The default database alias will handle collections in the drupal database on the default MongoDB server installed in earlier steps.
    • The keyvalue database alias will store key-value collections on the same default MongoDB server, but in a separate keyvalue database.
    • The logger database alias will store logger collections on the same default MongoDB server, but in a separate logger database.

Once the module is installed and enabled, you can check its requirements on /admin/reports/status:

MongoDB on status page

Installing using Composer

If you are already using Composer in your site to manage module dependencies, installing is just a two-steps process:

  • At the root of your site, add this package:

     composer require "drupal/mongodb:^2.0.0"
  • Enable the mongodb module. You now have access to the MongoDB services and Drush/Console commands for the mongodb module.

  1. This option is deprecated from 3.6 version