Skip to content


Extends: @apostrophecms/module ℹ️

This module establishes apos.db, the MongoDB driver database object.


apos.db is the MongoDB database object, not an alias to this module. You shouldn't need to talk to this module after startup, but you can access it as apos.modules['@apostrophecms/db'] if needed. You can also access apos.dbClient if you need the MongoClient object.


uriStringThe MongoDB connection URI. See the MongoDB URI documentation.
connectObjectIf present, this object is passed on as options to MongoDB's "connect" method, along with the uri. See the MongoDB connect settings documentation.
userStringUsed to construct a database URI (with the password option) if the uri option is not used.
passwordStringUsed to construct a database URI (with the user option) if the uri option is not used.
hostStringA hostname to use in the database URI if the uri option is not used. This falls back to localhost.
portIntegerA port to use in the database URI if the uri option is not used. This falls back to 27017.
nameStringThe project's database name. This falls back to the project shortname.
clientStringAn existing MongoDB connection (MongoClient) object. If present, it is used and uri, host, connect, etc. are ignored.
versionCheckBooleanIf true, Apostrophe checks the database and exits if it belongs to an older, incompatible major version of Apostrophe. Defaults to true. Set to false to avoid an extra query at startup.


In addition to the uri option and the host, port, and other options that build a MongoDB connection URI, we can pass a connection URI using the APOS_MONGODB_URI environment variable.

APOS_MONGODB_URI=mongodb:// node app

The following methods belong to this module and may be useful in project-level code. See the source code for all methods that belong to this module.

Because this module has an alias, you can call these from another module from the alias path. For example, self.apos.db.connectToMongo().


Open the database connection. Always uses mongo.MongoClient with its sensible defaults. Build a URI if necessary, so we can call it in a consistent way. One default we override: if the connection is lost, we keep attempting to reconnect forever. This is sensible behavior for a persistent process that requires MongoDB in order to operate.

If you need to change the way MongoDB connections are made, override connectToMongo in your project. In many cases it is easier to just use the client option.

Module tasks


Full command: node app @apostrophecms/db:reset

This task command fully resets the database. It drops all collections (other than system collections) and destroys all project content. Useful in local development. Very terrible in production.