---
title: "Rocket Chat Database Migration for Secure Deployment"
slug: "database-migration"
description: "Learn to migrate Rocket Chat databases securely. Ensure reliable messaging, scalable collaboration, and open source flexibility during deployment transitions."
updated: 2026-05-13T16:06:51Z
published: 2026-05-13T16:26:42Z
canonical: "docs.rocket.chat/database-migration"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Database Migration Notes

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.

> [!NOTE]
> For guidelines on updating Rocket.Chat, see [updating Rocket.Chat](/v1/docs/updating-rocketchat).

## 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](https://github.com/RocketChat/Rocket.Chat/blob/develop/apps/meteor/server/startup/migrations).

## 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:

```json
{"_id": "control", "locked": false, "version": 19}
```

Below is a brief description of the migration fields:

| Field | Type | Description |
| --- | --- | --- |
| `_id` | String | Always set to `control`. It means the collection has only one document to control migration actions. |
| `locked` | Boolean | Indicates whether a migration is currently in progress. If a migration fails, this value remains `true` and must be resolved manually before further migrations can run. |
| `version` | 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.

> [!NOTE]
> 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.