CommCare Cloud

44. Migrate forms & cases from Couch to SQL

Date: 2021-06-09

Optional per env: required on all environments

CommCare Version Dependency

CommCare versions beyond the following commit require this change to function correctly: 8f11208a

Change Context

A series of management commands must be run to check for and migrate domains’ forms & cases from Couch to SQL.


Historically CommCareHQ stored form submissions and case data in CouchDB. About 5 years ago the default storage backend was changed from Couch to SQL, and all domains created since then should be using the SQL backend. However, a bug allowed some Couch domains to be created since then. It is recommended to check for and migrate all relevant domains since the Couch form processor is slated for removal, and domains using it will stop working if they are not migrated before that happens.

Steps to update

Follow the steps outlined in the migration document to find and migrate all Couch domains in your environment.

It is necessary to check out an older version of CommCareHQ to run the migration since the migration code has been deleted on the main branch. After running the command cd $RELEASE_PATH in the setup steps, run the following command to checkout a version that contains the migration code:

git checkout 8f11208ad6510473003ef4c5eef74fa5e1bc1bed