{ "schema_version": 2, "id": "operate/rs/installing-upgrading/upgrading/upgrade-active-active", "title": "Upgrade an Active-Active database", "url": "https://redis.io/docs/latest/operate/rs/installing-upgrading/upgrading/upgrade-active-active/", "summary": "How to upgrade an Active-Active database.", "tags": [ "docs", "operate", "rs" ], "last_updated": "2026-10-07T13:34:28-05:00", "page_type": "content", "content_hash": "4e81b2ca78de0bb0ba5f0c66ff916ce7954e6ac1cfd9dfd68b90bc5d9d4f3df6", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "To upgrade an [Active-Active database](https://redis.io/docs/latest/operate/rs/databases/active-active) (formerly known as CRDB), send a single upgrade request with `crdb-cli` or the REST API. The request upgrades the database on each participating cluster in the Active-Active database, so you don't need to upgrade each one separately.\n\nThe Active-Active database upgrade:\n\n- Upgrades the Redis version and modules of the database on all participating clusters.\n\n- Updates the module information in the Active-Active database configuration to match the upgraded databases.\n\n- Upgrades the CRDB feature set version after the database is upgraded on all participating clusters." }, { "id": "default-db-versions", "title": "Default Redis database versions", "role": "content", "text": "When you upgrade an Active-Active database, it uses the latest Redis version bundled with Redis Software unless you specify a different version.\n\nFor the default Redis database version of each Redis Software release, see [Default Redis database versions](https://redis.io/docs/latest/operate/rs/installing-upgrading/upgrading/upgrade-database#default-db-versions)." }, { "id": "upgrade-prerequisites", "title": "Upgrade prerequisites", "role": "content", "text": "Before upgrading an Active-Active database:\n\n- Review the relevant [release notes](https://redis.io/docs/latest/operate/rs/release-notes) for any preparation instructions.\n\n- [Upgrade Redis Software](https://redis.io/docs/latest/operate/rs/installing-upgrading/upgrading/upgrade-cluster) on each node of every participating cluster in the Active-Active database. A coordinated upgrade requires Redis Software version 8.0.18 or later on all participating clusters.\n\n- Verify that the target database version is [supported](https://redis.io/docs/latest/operate/rs/installing-upgrading/upgrading/upgrade-database#db-versions-table) by the Redis Software version of every participating cluster.\n\n- [Check the status](#check-database-status) of the Active-Active database on each participating cluster.\n\n- Check that your client libraries are compatible with the new Redis database version. See the [database upgrade prerequisites](https://redis.io/docs/latest/operate/rs/installing-upgrading/upgrading/upgrade-database#upgrade-prerequisites) for details.\n\n- To avoid data loss during the upgrade, [back up your data](https://redis.io/docs/latest/operate/rs/databases/import-export/schedule-backups)." }, { "id": "upgrade-an-active-active-database", "title": "Upgrade an Active-Active database", "role": "content", "text": "To upgrade an Active-Active database:\n\n**crdb-cli:**\n\n1. Complete all [prerequisites](#upgrade-prerequisites) before starting the upgrade.\n\n1. Find the `` of your Active-Active database with the [`crdb-cli crdb list`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/crdb-cli/crdb/list) command:\n\n [code example]\n\n Look for the fully qualified domain name (`CLUSTER-FQDN`) of your cluster and use the associated `GUID`:\n\n [code example]\n\n1. Upgrade the Active-Active database with [`crdb-cli crdb upgrade`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/crdb-cli/crdb/upgrade). Use the `--preserve-roles` option to keep the current primary shard placement and prevent the clusters from becoming unbalanced.\n\n [code example]\n\n To upgrade the database to a version other than the default version, use the `--redis-version` option:\n\n [code example]\n\n For additional options, see the [`crdb-cli crdb upgrade` parameters](https://redis.io/docs/latest/operate/rs/references/cli-utilities/crdb-cli/crdb/upgrade#parameters).\n\n By default, the command waits for the upgrade to finish and reports status changes:\n\n [code example]\n\n If you use `--no-wait`, check the upgrade's progress with [`crdb-cli task status`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/crdb-cli/task/status):\n\n [code example]\n\n1. Use [`rladmin status databases extra all`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/status#status-databases) on each participating cluster to verify that the Redis version is set to the expected value.\n\n [code example]\n\n**REST API:**\n\n1. Complete all [prerequisites](#upgrade-prerequisites) before starting the upgrade.\n\n1. Find the `` of your Active-Active database with a [`GET /v1/crdbs`](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/crdbs) REST API request or the [`crdb-cli crdb list`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/crdb-cli/crdb/list) command.\n\n1. Use an [upgrade Active-Active database](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/crdbs/upgrade) REST API request. Use the `preserve_roles` option to keep the current primary shard placement and prevent the clusters from becoming unbalanced.\n\n [code example]\n\n For additional options, see the [request body](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/crdbs/upgrade#request-body) section of the Active-Active database upgrade requests reference.\n\n1. Check the upgrade's progress with the ID of the [CRDB task](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/crdb_tasks#get-crdb_task) returned by the upgrade request:\n\n [code example]\n\n The task's `status` is `finished` when the upgrade is complete." }, { "id": "check-database-status", "title": "Check database status", "role": "content", "text": "To check the status of the Active-Active database on a participating cluster, run [`rladmin status`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/status) on a node of that cluster:\n\n[code example]\n\n![](https://redis.io/docs/latest/images/rs/crdb-upgrade-node.png)\n\nThe statuses of the Active-Active database on the cluster can indicate:\n\n- `OLD REDIS VERSION`: The database is running a Redis version that is outdated or not fully compatible with the current Redis Software cluster version. [Upgrade the Active-Active database](#upgrade-an-active-active-database) to a later version of Redis bundled with the cluster's current Redis Software version.\n\n- `OLD CRDB PROTOCOL VERSION`: The database uses an older CRDB protocol. The upgrade updates the CRDB protocol version unless you use the `--keep-crdt-protocol-version` option (`keep_crdt_protocol_version` in the REST API). See [CRDB protocol version guidelines](#crdb-protocol-version-guidelines) for more information.\n\n- `OLD CRDB FEATURESET VERSION`: The database feature set version is outdated. The upgrade updates the feature set version after the database is upgraded on all participating clusters, unless you use the `--keep-crdt-featureset-version` option (`keep_crdt_featureset_version` in the REST API). See [Feature set version guidelines](#feature-set-version-guidelines) for more information." }, { "id": "crdb-protocol-version-guidelines", "title": "CRDB protocol version guidelines", "role": "content", "text": "The CRDB protocol version determines how the database on each participating cluster replicates write operations to the others. By default, the upgrade updates the CRDB protocol version on all participating clusters.\n\nIf you use the `keep_crdt_protocol_version` option, the database is upgraded without updating the CRDB protocol version. In this case:\n\n- You must upgrade the CRDB protocol version before the CRDB feature set version can be updated.\n\n- Upgrade the CRDB protocol version soon after with another [upgrade request](#upgrade-an-active-active-database) without the `keep_crdt_protocol_version` option." }, { "id": "feature-set-version-guidelines", "title": "Feature set version guidelines", "role": "content", "text": "Starting with Redis Software version 5.6.0, the feature set version helps support new Active-Active database features.\n\nThe feature set version is an internal version of the Active-Active database that enables new capabilities and improvements across participating clusters. When the feature set version is updated, it is updated for the database on all participating clusters.\n\nBy default, the upgrade updates the feature set version after the database is upgraded on all participating clusters. If you use the `keep_crdt_featureset_version` option, the upgrade keeps the current feature set version.\n\nFollow these upgrade guidelines:\n\n- As of Redis Software version 6.0.20, feature set version 0 is deprecated and support will be removed in a future version.\n\n- To avoid upgrade failures, make sure all your Active-Active databases are configured with the latest feature set version before upgrading to Redis Software 6.0.20 or later." }, { "id": "upgrade-feature-set-version", "title": "Upgrade feature set version", "role": "content", "text": "If the feature set version is old, as indicated by the `OLD CRDB FEATURESET VERSION` status:\n\n1. [Upgrade the Active-Active database](#upgrade-an-active-active-database) on all participating clusters and make sure the CRDB protocol version is not outdated.\n\n1. Find the `` of your Active-Active database.\n\n You can use the [`crdb-cli crdb list`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/crdb-cli/crdb/list) command:\n\n [code example]\n\n Look for the fully qualified domain name (`CLUSTER-FQDN`) of your cluster and use the associated `GUID`:\n\n [code example]\n\n1. Update the feature set version of the Active-Active database. See [Feature set version guidelines](#feature-set-version-guidelines) for more information.\n\n [code example]" }, { "id": "upgrade-limitations", "title": "Upgrade limitations", "role": "content", "text": "- When upgrading an Active-Active database from Redis 7.4 or earlier to version 8.0 or later, if you add a module to the database during the upgrade, you cannot use that module's commands, such as [Redis Search](https://redis.io/docs/latest/commands/?group=search) and [JSON](https://redis.io/docs/latest/commands/?group=json) commands, until the database has been upgraded on all participating clusters. These commands are not blocked automatically, and running these commands before finishing the upgrade process can cause syncer crashes.\n\n This limitation applies only when you add modules to a database during the upgrade. If the database already had modules configured before the upgrade, this limitation does not apply." } ], "examples": [ { "id": "upgrade-an-active-active-database-ex0", "language": "sh", "code": "crdb-cli crdb list", "section_id": "upgrade-an-active-active-database" }, { "id": "upgrade-an-active-active-database-ex1", "language": "sh", "code": "CRDB-GUID NAME REPL-ID CLUSTER-FQDN\n 700140c5-478e-49d7-ad3c-64d517ddc486 aatest 1 aatest1.example.com\n 700140c5-478e-49d7-ad3c-64d517ddc486 aatest 2 aatest2.example.com", "section_id": "upgrade-an-active-active-database" }, { "id": "upgrade-an-active-active-database-ex2", "language": "sh", "code": "crdb-cli crdb upgrade --crdb-guid --preserve-roles", "section_id": "upgrade-an-active-active-database" }, { "id": "upgrade-an-active-active-database-ex3", "language": "sh", "code": "crdb-cli crdb upgrade --crdb-guid --redis-version --preserve-roles", "section_id": "upgrade-an-active-active-database" }, { "id": "upgrade-an-active-active-database-ex4", "language": "sh", "code": "$ crdb-cli crdb upgrade --crdb-guid --preserve-roles\n Task created\n ---> CRDB GUID Assigned: crdb:\n ---> Status changed: queued -> started\n ---> Status changed: started -> finished", "section_id": "upgrade-an-active-active-database" }, { "id": "upgrade-an-active-active-database-ex5", "language": "sh", "code": "crdb-cli task status --task-id ", "section_id": "upgrade-an-active-active-database" }, { "id": "upgrade-an-active-active-database-ex6", "language": "sh", "code": "rladmin status databases extra all", "section_id": "upgrade-an-active-active-database" }, { "id": "upgrade-an-active-active-database-ex7", "language": "sh", "code": "POST https://:/v1/crdbs//upgrade\n {\n \"preserve_roles\": true,\n // Additional fields\n }", "section_id": "upgrade-an-active-active-database" }, { "id": "upgrade-an-active-active-database-ex8", "language": "sh", "code": "GET https://:/v1/crdb_tasks/", "section_id": "upgrade-an-active-active-database" }, { "id": "check-database-status-ex0", "language": "sh", "code": "rladmin status", "section_id": "check-database-status" }, { "id": "upgrade-feature-set-version-ex0", "language": "sh", "code": "crdb-cli crdb list", "section_id": "upgrade-feature-set-version" }, { "id": "upgrade-feature-set-version-ex1", "language": "sh", "code": "CRDB-GUID NAME REPL-ID CLUSTER-FQDN\n 700140c5-478e-49d7-ad3c-64d517ddc486 aatest 1 aatest1.example.com\n 700140c5-478e-49d7-ad3c-64d517ddc486 aatest 2 aatest2.example.com", "section_id": "upgrade-feature-set-version" }, { "id": "upgrade-feature-set-version-ex2", "language": "sh", "code": "crdb-cli crdb update --crdb-guid --featureset-version yes", "section_id": "upgrade-feature-set-version" } ] }