As Rocket.Chat evolves and new features are introduced, the database schema may also change to support those updates. Database migrations ensure that existing workspace data remains compatible with newer Rocket.Chat versions.
For guidelines on updating Rocket.Chat, see updating Rocket.Chat.
Understanding Rocket.Chat migrations
In Rocket.Chat, database migration refers to updates made to the internal database schema and stored data structures used by the application. When upgrading Rocket.Chat through supported upgrade paths, these migrations run automatically during application startup. In most cases, no manual action is required. Rocket.Chat migration definitions and version history are maintained in the Rocket.Chat GitHub repository.
Migration collection
Rocket.Chat stores migration state information in a dedicated MongoDB collection. This collection contains a single control document that tracks migration status and version information. For example:
{"_id": "control", "locked": false, "version": 19}Below is a brief description of the migration fields:
Field | Type | Description |
|---|---|---|
| String | Always set to |
| Boolean | Indicates whether a migration is currently in progress. If a migration fails, this value remains |
| Integer | The migration version currently applied to your server. |
If a specific migration needs to be skipped, set the version field to the next migration version number directly in the collection.
While Rocket.Chat automatically handles supported database schema migrations during application startup, administrators are still responsible for maintaining MongoDB version compatibility and following supported upgrade paths.
Rocket.Chat's approach to database migration ensures a smooth and efficient transition between different versions of the platform. By automating the migration process and providing mechanisms for controlling migration actions, Rocket.Chat ensures that its database schema is always up-to-date and compatible with the current version of the platform.