MongoDB: limits and operations #

This page is for database administrators who decide whether MongoDB fits a site, or who already run one. It answers: what the adapter does not support, how to recognize a feature that silently returns nothing, how upgrades and schema checks work without SQL, how to back up, and how a MySQL site is moved to MongoDB. Sources: MongoDB as the database, 9.5 MongoDB and section 26 of the porting reference.

Contents #

1. How the adapter works
2. Known limits
3. Finding untranslated SQL
4. Upgrades without SQL files
5. Backups
6. Moving a MySQL site to MongoDB
7. Performance
8. Checklist

How the adapter works #

expMongoDB never runs real SQL. It parses the kernel's SQL-shaped calls and turns them into find, aggregate, insert, upsert and delete operations on collections named like the kernel's tables (ezcontentobject, ezcontentobject_tree and so on). Its schema handler is expMongoSchema (settings/dbschema.ini, type mongo). eZDB::instance()->databaseName() returns mongo.

Known limits #

• Hand-written SQL that the adapter cannot translate returns an empty result and logs a warning. Extensions with SQL of their own may need a MongoDB path. An empty result is not an answer: code that decides access with its own SQL must read it as "no", never as "nothing restricts this". Check the log for untranslated SQL (below) before a site goes into production.
• Deep URL alias regeneration after moving subtrees is incomplete.
• Role and policy list pages can be empty although permissions are enforced.
• Some cronjobs are not ported.
• eztags is not usable.
• The shop checkout and ezflow scheduling are untested end to end.
• The SQL query cache does not apply.
• There are no SQL update files.
• Errors: errorNumber() reports MongoDB's codes (11000 for a duplicate key); the driver answers false and throws nothing (Database error codes and messages).

Test every extension and every workflow your site uses on a staging copy before you go live.

Finding untranslated SQL #

Search the logs for the marker the adapter writes:

grep -rn "MONGO TODO" var/log/ | tail -20

Each hit names a statement that returned an empty result instead of data. A page that shows "nothing found" where other engines show content usually has a hit here. Report kernel statements on the software tracker; fix your own extensions' SQL (Reviewing extension SQL for every engine).

Upgrades without SQL files #

MongoDB has no update/database/ directory. What replaces it:

• Setup > Upgrade check, "Check database consistency", compares collections instead of tables: missing collections grouped by feature, collections not in the schema, and the mongosh commands that create the missing ones (The upgrade check).
• php update/common/scripts/6.0/createaudittables.php creates the audit index collections of 6.0.15 through the schema handler (--dry-run first).
• The trash documents get trashed_by and trashed_via when written; older ones read as their defaults, so movetrashrecords.php runs as on the other engines.
• Run bin/mongodb/create_indexes.js again after an upgrade.

See 11.3 The update files.

Backups #

mongodump --uri="mongodb://exponential@localhost:27017/exponential" --out=/backup/$(date +%F)
mongorestore --uri="mongodb://exponential@localhost:27017/exponential" --drop /backup/2026-10-05

The tools ask for the password when the URI has none. Replica sets, oplog-based point-in-time backups and snapshots are MongoDB's own features and work as with any client. Back up var/storage and settings/override with the database (Backups per engine).

Moving a MySQL site to MongoDB #

The scripts in bin/mongodb/ move an existing MySQL site:

The procedure is section 18 of the porting reference. Plan a maintenance window, then create the indexes and run the cronjobs (Moving a site to another engine).

Performance #

Performance follows the number of statements per page, because each kernel call becomes one or more MongoDB operations. The indexes from create_indexes.js are the first lever; the caches in front of the database are the second (Performance and scaling).

Checklist #

• To do: Every extension and workflow tested on staging; no MONGO TODO in the logs after a full click-through.
• To do: eztags, shop checkout and ezflow not needed, or tested.
• To do: Indexes created after install and after each upgrade.
• To do: Upgrade check run after each upgrade; missing collections created.
• To do: mongodump backups scheduled and a restore tested.

Related pages #

• Setting up MongoDB
• Choosing an engine
• MongoDB for hosts
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.