Upgrade an Active-Active database

How to upgrade an Active-Active database.

Redis Software

To upgrade an Active-Active database (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.

The Active-Active database upgrade:

  • Upgrades the Redis version and modules of the database on all participating clusters.

  • Updates the module information in the Active-Active database configuration to match the upgraded databases.

  • Upgrades the CRDB feature set version after the database is upgraded on all participating clusters.

Default Redis database versions

When you upgrade an Active-Active database, it uses the latest Redis version bundled with Redis Software unless you specify a different version.

For the default Redis database version of each Redis Software release, see Default Redis database versions.

Upgrade prerequisites

Before upgrading an Active-Active database:

  • Review the relevant release notes for any preparation instructions.

  • Upgrade Redis Software 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.

  • Verify that the target database version is supported by the Redis Software version of every participating cluster.

  • Check the status of the Active-Active database on each participating cluster.

  • Check that your client libraries are compatible with the new Redis database version. See the database upgrade prerequisites for details.

  • To avoid data loss during the upgrade, back up your data.

Upgrade an Active-Active database

To upgrade an Active-Active database:

  1. Complete all prerequisites before starting the upgrade.

  2. Find the <CRDB-GUID> of your Active-Active database with the crdb-cli crdb list command:

    crdb-cli crdb list

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

    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

  3. Upgrade the Active-Active database with crdb-cli crdb upgrade. Use the --preserve-roles option to keep the current primary shard placement and prevent the clusters from becoming unbalanced.

    crdb-cli crdb upgrade --crdb-guid <CRDB-GUID> --preserve-roles

    To upgrade the database to a version other than the default version, use the --redis-version option:

    crdb-cli crdb upgrade --crdb-guid <CRDB-GUID> --redis-version <version> --preserve-roles

    For additional options, see the crdb-cli crdb upgrade parameters.

    By default, the command waits for the upgrade to finish and reports status changes:

    $ crdb-cli crdb upgrade --crdb-guid <CRDB-GUID> --preserve-roles
Task <task-id> created
  ---> CRDB GUID Assigned: crdb:<CRDB-GUID>
  ---> Status changed: queued -> started
  ---> Status changed: started -> finished

    If you use --no-wait, check the upgrade's progress with crdb-cli task status:

    crdb-cli task status --task-id <task-id>

  4. Use rladmin status databases extra all on each participating cluster to verify that the Redis version is set to the expected value.

    rladmin status databases extra all

Check database status

To check the status of the Active-Active database on a participating cluster, run rladmin status on a node of that cluster:

rladmin status

The statuses of the Active-Active database on the cluster can indicate:

  • 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 to a later version of Redis bundled with the cluster's current Redis Software version.

  • 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 for more information.

  • 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 for more information.

CRDB protocol version guidelines

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.

If you use the keep_crdt_protocol_version option, the database is upgraded without updating the CRDB protocol version. In this case:

  • You must upgrade the CRDB protocol version before the CRDB feature set version can be updated.

  • Upgrade the CRDB protocol version soon after with another upgrade request without the keep_crdt_protocol_version option.

Feature set version guidelines

Starting with Redis Software version 5.6.0, the feature set version helps support new Active-Active database features.

The 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.

By 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.

Follow these upgrade guidelines:

  • As of Redis Software version 6.0.20, feature set 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 Software 6.0.20 or later.

Upgrade feature set version

If the feature set version is old, as indicated by the OLD CRDB FEATURESET VERSION status:

  1. Upgrade the Active-Active database on all participating clusters and make sure the CRDB protocol version is not outdated.

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

    You can use the crdb-cli crdb list command:

    crdb-cli crdb list

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

    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

  3. Update the feature set version of the Active-Active database. See Feature set version guidelines for more information.

    crdb-cli crdb update --crdb-guid <CRDB-GUID> --featureset-version yes

Upgrade limitations

  • 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 and 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.

    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.

RATE THIS PAGE
Back to top ↑