Database Migration

As features are added to pimentaCHAT, the database schema may change between versions.

The action of updating an older schema to a newer one (or vice versa) is called database migration.

When you incrementally update pimentaCHAT versions, database migration is automatic and you do not have to take any explicit action.

However, from time to time, you may have need to skip multiple versions in your pimentaCHAT upgrades.

Database migration may fail in these scenarios.

A typical failure message is similar to:

|                    Your database migration failed:                   |
|        Object [object Object] has no method 'addUsersToRoles'        |
|                   This pimentaCHAT version: 0.39.0                   |
|                    Database locked at version: 18                    |
|                      Database target version: 58                     |

As an example, the above migration is locked and stuck on 18. We need a target of 19 before migration to 58.

One way to force migration is to manually unlock the migration in mongo and also increase database version to the target version (19).

use pimentaCHAT
db.migrations.update({_id: 'control'},{$set:{locked:false,version:19}})

Restart pimentaCHAT and the migration should succeed now to the latest version.

Note that certain new values that are vital to pimentaCHAT operations may remain unpopulated when you skip versions.

For example, you may have to manually apply roles to users.