MongoDB in Server Upgrades Best Practices
Schema Upgrade for Embedded and User-Managed MongoDB
Most quarterly upgrades change the database schema to accommodate new features. A schema migration is done automatically the first time the Alteryx Server service is started after your upgrade. While this is automatic, any issues in this process prevent the Server from properly starting.
Check the Alteryx Pre-Upgrade Checks as they are the best way to ensure your Mongo database schema is ready to migrate without error.
To confirm the schema migrated to the expected version after starting the Alteryx Server service, review the end of the migration log and compare it to the correct schema for your Server version: C:\ProgramData\Alteryx\Gallery\Logs\alteryx-migration.csv
For more information about MongoDB schema, check the MongoDB Schema Reference help page.
Determine if Your Mongo Database Version Needs to Upgrade
The Mongo DB Schema Reference lists the "Embedded MongoDB Version" and "Supported MongoDB Version for User-Managed Instances" for each Server version.
Embedded MongoDB
If a version upgrade is shown, it occurs automatically at the end of the Server upgrade process. Refer to the details below on the amount of free space needed and what folders you can delete or archive after the upgrade completes.
If you are making a significant upgrade (for example, from 2019.2 to 2021.4) that shows 2 Mongo version upgrades (3.4 to 4.0, then 4.0 to 4.2), you need to pit-stop in your upgrade to a Server version that uses the middle Mongo version (so upgrade 2019.2 to 2019.3 to get to Mongo 4.0, then 2019.3 to 2021.4 to get to Mongo 4.2).
User-Managed MongoDB
You'll notice that multiple Mongo versions are supported for each version of Server. Determine if you are required to upgrade your Mongo or if it's optional.
Version Upgrade for Different Types of MongoDB
Some Server upgrades also upgrade the Embedded MongoDB version. The Version-to-Version Guide indicates these as Pit Stops. For the MongoDB version upgrade, you can upgrade directly from a version prior to one of these Pit Stops to a version after, as long as you don't pass 2 Mongo Pit Stops.
Important
If your Server upgrade will upgrade the Mongo database, you will need free space equal to 1-3 times the size of your current Mongo database during the upgrade.
If your Server upgrade will not upgrade the Mongo database version, no additional space is used during the Server upgrade and this section does not apply.
To plan the space needed, check the size of your current MongoDB.
Folder: C:\ProgramData\Alteryx\Service\Persistence\MongoDB
Manual backup of database prior to upgrade, MongoDB Backups. To conserve space, you can archive the backup before you proceed.
During the Mongo upgrade the database is copied to a
\MongoDB_PreUpgradefolder. You are asked for the location of this folder during the Server upgrade and can choose another drive on your machine. While you can specify a network location, it's not recommended because a large database might fail due to a network connection issue.For Server upgrades 2018-2021.3.5, the upgraded database is created in a new folder named
\MongoDB_MongoVer. After the upgrade, you can delete your original\MongoDBfolder.
MongoDB Version Upgrade Folder Organization 2021.3.6+
MongoDB Version Upgrade Folder Organization 2018 - 2021.3.5
If you determine above you must or wish to upgrade your On-Prem User-Managed Mongo, you should do so independently of your Alteryx Server upgrade. Don't upgrade both at the same time without thoroughly testing your Server after upgrading the application.
To upgrade On-Prem User-Managed Mongo:
Stop the AlteryxService.
Back up your MongoDB.
Follow Mongo's recommendations for upgrading, which may require pit stops. For example, if you are migrating from Mongo 3.4 -> 4.0, Mongo recommends updating 3.4 -> 3.6 and then 3.6 -> 4.0.
Start Mongo.
Start AlteryxService.
Test that Server and workflows are running as expected.
For more information refer to these articles:
If you determine above that you must or wish to upgrade your Atlas User-Managed MongoDB, you should do so independently of your Alteryx Server upgrade. Don't upgrade both at the same time without thoroughly testing your Server after you upgrade the application.
To upgrade Atlas User-Managed Mongo:
Stop the AlteryxService.
Back up your database per Mongo Atlas documentation.
Use the Upgrade Version button per Mongo documentation.
Start AlteryxService.
Test that Server and workflows are running as expected.