Database Migrations

How erxes handles MongoDB schema changes during upgrades. This guide follows version 3.1.7 (03acdf712c).

For image selection and rollback planning, see Upgrades.

What to expect

• There is no single global migration runner documented for operators. Migrations are owned inside plugins and services (for example backend/plugins/operation_api/src/migrations/ and backend/plugins/frontline_api/src/migrations/).
• backend/saas-migrations/ holds SaaS data migrations per domain (core, sales, content, operation, and others). Review the directory matching your deployment before upgrading.
• The logs service uses a separate <application-database>_logs database; back it up alongside the application database.

Before upgrading

1. Record the running image tags or digests and the current product version.
2. Back up MongoDB and Redis persistence (or at least MongoDB) with your provider tooling. Verify the backup restores in staging.
3. Read the release notes and the saas-migrations changes for your version jump.
4. Stage the upgrade with a copy of production data, then exercise login, the enabled plugins, automations, and file access.

During the upgrade

1. Stop writes or schedule a maintenance window if the migration rewrites stored data.
2. Deploy the new images together; do not mix a new Core API with old plugin APIs unless the release notes allow it.
3. Watch Core API, gateway, and enabled plugin logs for migration or composition errors.
4. Verify /health, /graphql, owner login, and one write per enabled domain.

Restoring the previous website build does not reverse database migrations. Keep the database backup until the new version is confirmed.

Source references

• SaaS migrations.
• Core API Dockerfile.
• Logs database selection.