Skip to content

RS: Rearranged upgrade Active-Active DB page and added more details about rladmin status output #2321

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Nov 3, 2025
Merged

RS: Rearranged upgrade Active-Active DB page and added more details about rladmin status output #2321

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ac4e7fd
Upgrade A-A DB improvements
rrelledge Oct 24, 2025
629406b
DOC-5437 Copy edits and added in-page links to upgrade A-A DB
rrelledge Oct 29, 2025
838f4f2
Fix rladmin status relref
rrelledge Oct 29, 2025
84b207f
Merge branch 'main' into DOC-5437
rrelledge Oct 30, 2025
f2c6752
Merge branch 'main' into DOC-5437
rrelledge Oct 31, 2025
1fbceb7
DOC-5437 Feedback updates to clarify CRDB featureset and how to check…
rrelledge Oct 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
179 changes: 101 additions & 78 deletions content/operate/rs/installing-upgrading/upgrading/upgrade-active-active.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,138 +5,161 @@ categories:
- docs
- operate
- rs
description: Upgrade an Active-Active database.
description: How to upgrade an Active-Active database.
linkTitle: Active-Active databases
weight: 70
---

When you upgrade an [Active-Active (CRDB) database]({{< relref "/operate/rs/databases/active-active" >}}), you can also upgrade the CRDB protocol version and feature version.
## Upgrade an Active-Active database

## CRDB protocol version guidelines
To upgrade an [Active-Active (CRDB) database]({{< relref "/operate/rs/databases/active-active" >}}):

Redis Enterprise Software versions 5.4.2 and later use CRDB protocol version 1 to help support Active-Active features.
1. [Upgrade Redis Enterprise Software]({{< relref "/operate/rs/installing-upgrading/upgrading/upgrade-cluster" >}}) on each node in the clusters where the Active-Active instances are located.

CRDB protocol version 1 is backward compatible, which means Redis Enterprise v5.4.2 CRDB instances can understand write operations from instances using the earlier CRDB protocol version 0.
1. [Check the status](#check-database-status) of all Active-Active database instances.

After you upgrade one instance's CRDB protocol to version 1:
1. [Upgrade all Active-Active database instances](#upgrade-database-instances) to a later version of Redis.

- Any instances that use CRDB protocol version 1 can receive updates from both version 1 and version 0 instances.
1. If the status indicates `OLD CRDB FEATURESET VERSION`, [upgrade the featureset version](#upgrade-featureset-version).

- However, instances that still use CRDB protocol version 0 cannot receive write updates from version 1 instances.
1. If your Active-Active database uses modules, [update module information](#update-module-information).

- After you upgrade an instance from CRDB protocol version 0 to version 1, it automatically receives any missing write operations.
## Check database status

Follow these upgrade guidelines:
To check the status of an Active-Active database instance, run [`rladmin status`]({{<relref "/operate/rs/references/rladmin/status">}}):

- Upgrade all instances of a specific CRDB within a reasonable time frame to avoid temporary inconsistencies between the instances.
```sh
rladmin status
```

- Make sure that you upgrade all instances of a specific CRDB before you do global operations on the CRDB, such as removing instances and adding new instances.
{{< image filename="/images/rs/crdb-upgrade-node.png" >}}

- As of v6.0.20, protocol version 0 is deprecated and support will be removed in a future version.
The statuses of the Active-Active instances on the node can indicate:

- To avoid upgrade failures, update all Active-Active databases to protocol version 1 _before_ upgrading Redis Enterprise Software to v6.0.20 or later.
- `OLD REDIS VERSION`: The database instance is running a Redis version that is outdated or not fully compatible with the current Redis Enterprise Software cluster version. You should [upgrade the database](#upgrade-database-instances) to a later version of Redis bundled with the cluster's current Redis Enterprise Software version.

## Feature version guidelines
- `OLD CRDB PROTOCOL VERSION`: This instance uses an older CRDB protocol. Redis Enterprise Software versions 5.4.2 and later use CRDB protocol version 1. You can upgrade the CRDB protocol version when you [upgrade the Active-Active database instances](#upgrade-database-instances). See [CRDB protocol version guidelines](#crdb-protocol-version-guidelines) for more information.

Starting with version 5.6.0, a new feature version (also called a _feature set version_) helps support new Active-Active features.
- `OLD CRDB FEATURESET VERSION`: The database feature set version is outdated. After all [Active-Active database instances are upgraded](#upgrade-database-instances), [upgrade the feature set version](#upgrade-featureset-version). See [Feature version guidelines](#feature-version-guidelines) for more information.

When you update the feature version for an Active-Active database, the feature version is updated for all database instances.

Follow these upgrade guidelines:
## Upgrade database instances

- As of v6.0.20, feature version 0 is deprecated and support will be removed in a future version.
For each Active-Active database instance:

- To avoid upgrade failures, update all Active-Active databases to protocol version 1 _before_ upgrading Redis Enterprise Software to v6.0.20 or later.
1. Upgrade the Redis database version and enabled modules with [`rladmin upgrade db`]({{<relref "/operate/rs/references/cli-utilities/rladmin/upgrade#upgrade-db">}}):

## Upgrade Active-Active database instance
```sh
rladmin upgrade db <database_name | database_ID>
```

To upgrade an Active-Active database (CRDB) instance:
1. If the CRDB protocol version is old, read the warning message carefully and confirm that you want to update the CRDB protocol. See [CRDB protocol version guidelines](#crdb-protocol-version-guidelines) for more information.

1. [Upgrade Redis Enterprise Software]({{< relref "/operate/rs/installing-upgrading/upgrading/upgrade-cluster" >}}) on each node in the clusters where the Active-Active instances are located.
{{< image filename="/images/rs/crdb-upgrade-protocol.png" >}}

1. To see the status of your Active-Active instances, run:
After confirmation, the Active-Active instance will use the new Redis version and CRDB protocol version.

```sh
rladmin status
```
{{<note>}}
You can use the `keep_crdt_protocol_version` option to upgrade the database version without upgrading the CRDB protocol version. However, you must upgrade the CRDB protocol before you update the CRDB feature set version.

The statuses of the Active-Active instances on the node can indicate:
If you use `keep_crdt_protocol_version`, make sure that you upgrade the CRDB protocol soon after with the [`rladmin upgrade db`]({{< relref "/operate/rs/references/cli-utilities/rladmin/upgrade#upgrade-db" >}}) command.
{{</note>}}

- `OLD REDIS VERSION`
- `OLD CRDB PROTOCOL VERSION`
- `OLD CRBD FEATURESET VERSION`
### CRDB protocol version guidelines

{{< image filename="/images/rs/crdb-upgrade-node.png" >}}
Redis Enterprise Software versions 5.4.2 and later use CRDB protocol version 1 to help support Active-Active features.

1. To upgrade each Active-Active instance and its modules, including the Redis version and CRDB protocol version, run:
CRDB protocol version 1 is backward compatible, which means Redis Enterprise v5.4.2 CRDB instances can understand write operations from instances using the earlier CRDB protocol version 0.

```sh
rladmin upgrade db <database_name | database_ID>
```
After you upgrade one instance's CRDB protocol to version 1:

If the protocol version is old, read the warning message carefully and confirm.
- Any instances that use CRDB protocol version 1 can receive updates from both version 1 and version 0 instances.

{{< image filename="/images/rs/crdb-upgrade-protocol.png" >}}
- However, instances that still use CRDB protocol version 0 cannot receive write updates from version 1 instances.

- After you upgrade an instance from CRDB protocol version 0 to version 1, it automatically receives any missing write operations.

The Active-Active instance uses the new Redis version and CRDB protocol version.
Follow these upgrade guidelines:

Use the `keep_crdt_protocol_version` option to upgrade the database feature version
without upgrading the CRDB protocol version.
- Upgrade all instances of a specific CRDB within a reasonable time frame to avoid temporary inconsistencies between the instances.

If you use this option, make sure that you upgrade the CRDB protocol soon after with the [`rladmin upgrade db`]({{< relref "/operate/rs/references/cli-utilities/rladmin/upgrade#upgrade-db" >}}) command.
- Make sure that you upgrade all instances of a specific CRDB before you perform global operations on the CRDB, such as removing instances and adding new instances.

You must upgrade the CRDB protocol before you update the CRDB feature set version.
- As of v6.0.20, protocol version 0 is deprecated and support will be removed in a future version.

1. If the feature set version is old, you must upgrade all of the Active-Active instances. Then, to update the feature set for each active-active database, run:
- To avoid upgrade failures, update all Active-Active databases to protocol version 1 _before_ upgrading Redis Enterprise Software to v6.0.20 or later.

```sh
crdb-cli crdb update --crdb-guid <CRDB-GUID> --featureset-version yes
```
## Upgrade featureset version

You can retrieve the `<CRDB-GUID>` with the following command:
If the feature set version is old, as indicated by the `OLD CRDB FEATURESET VERSION` status:

1. [Upgrade all Active-Active database instances](#upgrade-database-instances) and make sure the CRDB protocol is not outdated.

1. Find the `<CRDB-GUID>` of your Active-Active database.

You can use the [`crdb-cli crdb list`]({{<relref "/operate/rs/references/cli-utilities/crdb-cli/crdb/list">}}) command:

```sh
crdb-cli crdb list
```

Look for the fully qualified domain name (CLUSTER-FDQN) of your cluster and use the associated GUID:
Look for the fully qualified domain name (`CLUSTER-FDQN`) of your cluster and use the associated `GUID`:

```sh
CRDB-GUID NAME REPL-ID CLUSTER-FQDN
700140c5-478e-49d7-ad3c-64d517ddc486 aatest 1 aatest1.example.com
700140c5-478e-49d7-ad3c-64d517ddc486 aatest 2 aatest2.example.com
```

1. Update module information in the CRDB configuration using the following command syntax:
1. Update the feature set for each Active-Active database. See [Feature version guidelines](#feature-version-guidelines) for more information.

```sh
crdb-cli crdb update --crdb-guid <guid> --default-db-config \
'{ "module_list":
[
{
"module_name": "<module1_name>",
"semantic_version": "<module1_version>"
},
{
"module_name": "<module2_name>",
"semantic_version": "<module2_version>"
}
]}'
crdb-cli crdb update --crdb-guid <CRDB-GUID> --featureset-version yes
```

For example:
### Feature version guidelines

```sh
crdb-cli crdb update --crdb-guid 82a80988-f5fe-4fa5-bca0-aef2a0fd60db --default-db-config \
'{ "module_list":
[
{
"module_name": "search",
"semantic_version": "2.4.6"
},
{
"module_name": "ReJSON",
"semantic_version": "2.4.5"
}
]}'
```
Starting with version 5.6.0, a new feature version (also called a _feature set version_) helps support new Active-Active features.

When you update the feature version for an Active-Active database, the feature version is updated for all database instances.

Follow these upgrade guidelines:

- As of v6.0.20, feature version 0 is deprecated and support will be removed in a future version.

- To avoid upgrade failures, make sure all your Active-Active databases are configured with the latest feature set version before upgrading to Redis Enterprise Software 6.0.20 or later.

## Update module information

If your Active-Active database uses modules, update module information in the CRDB configuration using the following command syntax:

```sh
crdb-cli crdb update --crdb-guid <guid> --default-db-config \
'{ "module_list":
[
{
"module_name": "<module1_name>",
"semantic_version": "<module1_version>"
},
{
"module_name": "<module2_name>",
"semantic_version": "<module2_version>"
}
]}'
```

For example:

```sh
crdb-cli crdb update --crdb-guid 82a80988-f5fe-4fa5-bca0-aef2a0fd60db --default-db-config \
'{ "module_list":
[
{
"module_name": "search",
"semantic_version": "2.4.6"
},
{
"module_name": "ReJSON",
"semantic_version": "2.4.5"
}
]}'
```