@apostrophecms/db
Extends: @apostrophecms/module ℹ️
This module establishes apos.db, the database object used throughout Apostrophe. It supports MongoDB, SQLite, and Postgres via pluggable adapters, using @apostrophecms/db-connect to select the right adapter based on the connection URI's protocol (mongodb://, sqlite://, or postgres://).
INFO
apos.db is the 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 underlying client object.
Options
| Property | Type | Description |
|---|---|---|
uri | String | The database connection URI. May use the mongodb://, sqlite://, postgres://, or multipostgres protocol. See the database usage and MongoDB URI documentation for the MongoDB format. |
defaultAdapter | String | Which adapter to use when building a URI from host/port/name/etc. rather than supplying uri directly. One of mongodb, sqlite, postgres, or multipostgres. Defaults to mongodb. Can also be set via the APOS_DEFAULT_DB_ADAPTER environment variable. |
connect | Object | If present, this object is passed on as options to the adapter's "connect" method, along with the uri. For MongoDB, see the MongoDB connect settings documentation. |
adapters | Array | An array of custom adapters, each providing name, connect(uri, options), and protocols properties. name may match a core adapter name (such as postgres or mongodb) to override it. connect must resolve to a client object supporting a sufficient subset of the MongoDB driver API. |
user | String | Used to construct a database URI (with the password option) if the uri option is not used. Not applicable to the sqlite adapter. |
password | String | Used to construct a database URI (with the user option) if the uri option is not used. Not applicable to the sqlite adapter. |
host | String | A hostname to use in the database URI if the uri option is not used. Falls back to localhost. Not applicable to the sqlite adapter. |
port | Integer | A port to use in the database URI if the uri option is not used. Falls back to 27017 for mongodb, or 5432 for postgres/multipostgres. Not applicable to the sqlite adapter. |
name | String | The project's database name. This falls back to the project shortname. For the sqlite adapter, this becomes the filename (as data/<name>.sqlite, relative to the project root). |
client | Object | An existing, MongoDB-compatible client object. If present, it is used and uri, host, connect, etc. are ignored. |
versionCheck | Boolean | If 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. |
INFO
In addition to the uri option and the host, port, and other options that build a connection URI, you can pass a connection URI using the APOS_DB_URI environment variable:
APOS_DB_URI=mongodb://db_user:D1fficultP%40ssw0rd@mongodb0.example.com:27017/?authSource=apos-site-db node appThe legacy APOS_MONGODB_URI environment variable is still supported for backward compatibility, but APOS_DB_URI is preferred and takes precedence if both are set.
INFO
When neither uri nor a URI-related environment variable is set, defaultAdapter (or APOS_DEFAULT_DB_ADAPTER) determines which adapter's URI gets built from host, port, name, etc. For example, setting defaultAdapter: 'sqlite' will use a local SQLite file at data/<shortname>.sqlite with no additional configuration required.
Featured methods
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.
connectToAdapter(uri, options)
Connect to a database using the adapter appropriate to the given URI's protocol, and return a client object compatible with the MongoDB driver interface. Unlike connectToDb(), this method has no side effects — it does not set apos.db or apos.dbClient. It's useful for making temporary connections, for example to drop a test database.
Module tasks
reset
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.