Upgrade Redis
This guide covers how to upgrade a Redis Database to a newer release.
📘 Starting with Redis 6, the Access Control List feature was introduced by Redis. In specific scenarios, this change also changes how a Redis Database can be upgraded. To help describe when each upgrade method applies, we’ll use the term
pre-ACL
to describe Redis version 5 and below, andpost-ACL
to describe Redis version 6 and beyond.
Pre-ACL to Pre-ACL / Post-ACL to Post-ACL Upgrades
Preparation
- Install the Aptible CLI
Step 1: Configuration
Collect information on the Database you’d like to upgrade and store it in the following environment variables for use later in the guide:
-
DB_HANDLE
- The handle (i.e. name) of the Database. -
ENVIRONMENT
- The handle of the environment the Database belongs to. -
VERSION
- The desired Redis version. Runaptible db:versions
to see a full list of options.
Example:
DB_HANDLE='my-redis'
ENVIRONMENT='test-environment'
VERSION='5.0-aof'
Step 2: Contact Aptible Support
An Aptible team member must update the Database’s metadata to the new version in order to upgrade the Database. When contacting Aptible Support please adhere to the following rules to ensure a smooth upgrade process:
-
Ensure that you have Administrator Access to the Database’s Environment. If you do not, please have someone with access contact support or CC an Account Owner or Deploy Owner for approval.
-
Use the same email address that’s associated with your Aptible user account to contact support.
-
Include the configuration values above. You may run the following command to generate a request with the required information:
echo "Please upgrade our Redis database, ${ENVIRONMENT} - ${DB_HANDLE}, to version ${VERSION}. Thank you."
Step 3: Restart
Once support has updated the Database, you’ll need to restart the database to apply the change. You may do so at your convenience with the aptible db:reload
CLI command:
aptible db:reload --environment "$ENVIRONMENT" "$DB_HANDLE"
Pre-ACL to Post-ACL Upgrades
Method 1: Use Replication to Orchestrate a Minimal-Downtime Upgrade
Preparation
-
Install the Aptible CLI
-
Install the Redis CLI
Step 1: Configuration
Collect information on the Database you’d like to upgrade and store it in the following environment variables in a terminal session for use later in the guide:
-
OLD_HANDLE
- The handle (i.e. name) of the Database. -
ENVIRONMENT
- The handle of the Environment the Database belongs to.
Example:
SOURCE_HANDLE = 'old-db'
ENVIRONMENT = 'test-environment'
Collect information for the new Database and store it in the following environment variables:
-
NEW_HANDLE
- The handle (i.e., name) for the Database. -
NEW_VERSION
- The desired Redis version. Runaptible db:versions
to see a full list of options. Note that there are different “flavors” of Redis for each version. Double-check that the new version has the same flavor as the original database’s version. -
NEW_CONTAINER_SIZE
(Optional) - The size of the new Database’s container in MB. You likely want this value to be the same as the original database’s container size. See the Database Scaling documentation for a full list of supported container sizes. -
NEW_DISK_SIZE
(Optional) - The size of the new Database’s disk in GB. You likely want this value to be the same as the original database’s disk size.
Example:
NEW_HANDLE = 'upgrade-test'
NEW_VERSION = '7.0'
NEW_CONTAINER_SIZE = 2048
NEW_DISK_SIZE = 10
Step 2: Provision the new Database
Create the new Database using aptible db:create
.
Example:
aptible db:create "$NEW_HANDLE" \
--type "redis" \
--version "$NEW_VERSION" \
--container-size $NEW_CONTAINER_SIZE \
--disk-size $NEW_DISK_SIZE \
--environment "$ENVIRONMENT"
Step 3: Tunnel into the new Database
In a separate terminal, create a Database Tunnel to the new Database using the aptible db:tunnel
command.
Example:
aptible db:tunnel "$NEW_HANDLE" --environment "$ENVIRONMENT"
The tunnel will block the current terminal until it’s stopped. Collect the tunnel’s full URL, which is printed by aptible db:tunnel, and store it in the NEW_URL
environment variable in the original terminal.
Example:
NEW_URL ='redis://aptible:pa$word@localhost.aptible.in:6379'
Step 4: Retrieve the Old Database’s Database Credentials
To initialize replication, you’ll need the Database Credentials of the old database. We’ll refer to these values as the following:
-
OLD_HOST
-
OLD_PORT
-
OLD_PASSWORD
Step 5: Connect to the New Database
Using the Redis CLI in the original terminal, connect to the new database:
redis-cli -u $NEW_URL
Step 6: Initialize Replication
Using the values from Step 4, run the following commands on the new database to initialize replication.
REPLICA OF $OLD_HOST $OLD_PORT
CONFIG SET masterauth $OLD_PASSWORD
Step 7: Cutover
When you’re ready to cutover, point your Apps to the new Database and run REPLICAOF NO ONE
via the Redis CLI to stop replication. Finally, deprovision the old database using the command aptible db:deprovision.
Method 2: Dump and Restore to a new Redis Database
We recommend Method 1 above, but you can also dump and restore to upgrade if you’d like. This method introduces extra downtime, as you must take your database offline before conducting the dump to prevent new writes and data loss.
Preparation
-
Install the Aptible CLI
-
Install the Redis CLI
-
Install the rdb tool
Step 1: Configuration
Collect information on the Database you’d like to upgrade and store it in the following environment variables in a terminal session for use later in the guide:
-
OLD_HANDLE
- The handle (i.e. name) of the Database. -
ENVIRONMENT
- The handle of the Environment the Database belongs to
Example:
SOURCE_HANDLE = 'old-db'
ENVIRONMENT = 'test-environment'
Collect information for the new Database and store it in the following environment variables:
-
NEW_HANDLE
- The handle (i.e., name) for the Database. -
NEW_VERSION
- The desired Redis version. Runaptible db:versions
to see a full list of options. Note that there are different “flavors” of Redis for each version. Double-check that the new version has the same flavor as the original database’s version. -
NEW_CONTAINER_SIZE
(Optional) - The size of the new Database’s container in MB. You likely want this value to be the same as the original database’s container size. See the Database Scaling documentation for a full list of supported container sizes. -
NEW_DISK_SIZE
(Optional) - The size of the new Database’s disk in GB. You likely want this value to be the same as the original database’s disk size.
Example:
NEW_HANDLE = 'upgrade-test'
NEW_VERSION = '7.0'
NEW_CONTAINER_SIZE = 2048
NEW_DISK_SIZE = 10
Step 2: Provision the new Database
Create the new Database using aptible db:create
.
Example:
aptible db:create "$NEW_HANDLE" \
--type "redis" \
--version "$NEW_VERSION" \
--container - size $NEW_CONTAINER_SIZE \
--disk - size $NEW_DISK_SIZE \
--environment "$ENVIRONMENT"
Step 3: Tunnel into the old Database
In a separate terminal, create a Database Tunnel to the old Database using the aptible db:tunnel
command.
Example:
aptible db:tunnel "$NEW_HANDLE" --environment "$ENVIRONMENT"
The tunnel will block the current terminal until it’s stopped. Collect the tunnel’s full URL, which is printed by aptible db:tunnel
, and store it in the OLD_URL
environment variable in the original terminal.
Example:
OLD_URL = 'redis://aptible:pa$word@localhost.aptible.in:6379'
Step 4: Dump the Old Database
Dump the old database to a file locally using rdb and the Redis CLI.
Example:
redis-cli -u $OLD_URL --rdb dump.rdb
Step 5: Tunnel into the new Database
In a separate terminal, create a Database Tunnel to the new Database using the aptible db:tunnel
command, and save the Connection URL as NEW_URL
.
Step 6: Restore the Dump using rdb
Using the rdb tool, restore the dump to the new Database.
rdb --command protocol dump.rdb | redis - cli - u $NEW_URL--pipe
Step 7: Cutover
Point your Apps and other resources to your new database and deprovision the old database using the command aptible db:deprovision.