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

# Upgrade Redis

This guide covers how to upgrade a Redis [Database](https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/overview.md) to a newer release.

> [!TIP]
>
> 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, and `post-ACL` to describe Redis version 6 and beyond.

> [accordion] Pre-ACL to Pre-ACL and Post-ACL to Post-ACL Upgrades
>
> > [!NOTE]
> >
> > **Prerequisite:** Install the [Aptible CLI](https://www.aptible.com/docs/reference/aptible-cli/cli-commands/overview)
>
> **1. Collection Configuration Information**
>
> 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. Run `aptible db:versions` to see a full list of options.
>
> ```bash theme={null}
>   DB_HANDLE='my-redis'
>   ENVIRONMENT='test-environment'
>   VERSION='5.0-aof'
> ```
>
> **2. Contact the Aptible Support Team**
>
> An Aptible team member must update the Database's metadata to the new version in order to upgrade the Database. When contacting [Aptible Support](https://www.aptible.com/docs/how-to-guides/troubleshooting/aptible-support.md) please adhere to the following rules to ensure a smooth upgrade process:
>
> * Ensure that you have [Administrator Access](https://www.aptible.com/docs/core-concepts/security-compliance/access-permissions.md#write-permissions) to the Database's Environment. If you do not, please have someone with access contact support or CC an [Account Owner or Deploy Owner](https://www.aptible.com/docs/core-concepts/security-compliance/access-permissions.md) 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:
>
> ```bash theme={null}
>   echo "Please upgrade our Redis database, ${ENVIRONMENT} - ${DB_HANDLE}, to version ${VERSION}. Thank you."
> ```
>
> **3. Restart the Database**
>
> Once support has updated the Database version, you'll need to restart the database to apply the upgrade. You may do so at your convenience with the [`aptible db:reload`](https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-reload) CLI command:
>
> ```bash theme={null}
>   aptible db:reload --environment $ENVIRONMENT $DB_HANDLE
> ```

> [accordion] Pre-ACL to Post-ACL Upgrades
>
> > [accordion] Method 1: Use Replication to Orchestrate a Minimal-Downtime Upgrade
> >
> > > [!NOTE]
> > >
> > > **Prerequisite:** Install the [Aptible CLI](https://www.aptible.com/docs/reference/aptible-cli/cli-commands/overview) and [Redis CLI](https://redis.io/docs/install/install-redis/)
> >
> > **1. Collect Configuration Information**
> >
> > **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:
> >
> > ```bash theme={null}
> >   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. Run `aptible db:versions` to see a full list of options. Note that there are different ["flavors" of Redis](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/redis.md) 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](https://www.aptible.com/docs/core-concepts/scaling/database-scaling.md#ram-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:
> >
> > ```bash theme={null}
> >   NEW_HANDLE = 'upgrade-test'
> >   NEW_VERSION = '7.0'
> >   NEW_CONTAINER_SIZE = 2048
> >   NEW_DISK_SIZE = 10
> > ```
> >
> > **2. Provision the new Database**
> >
> > Create the new Database using `aptible db:create`.
> >
> > Example:
> >
> > ```bash theme={null}
> >   aptible db:create "$NEW_HANDLE" \
> >   --type "redis" \
> >   --version "$NEW_VERSION" \
> >   --container-size $NEW_CONTAINER_SIZE \
> >   --disk-size $NEW_DISK_SIZE \
> >   --environment "$ENVIRONMENT"
> > ```
> >
> > **3. Tunnel into the new Database**
> >
> > In a separate terminal, create a [Database Tunnel](https://www.aptible.com/docs/core-concepts/managed-databases/connecting-databases/database-tunnels.md) to the new Database using the `aptible db:tunnel` command.
> >
> > Example:
> >
> > ```bash theme={null}
> >   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](https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-tunnel.md), and store it in the `NEW_URL` environment variable in the original terminal.
> >
> > Example:
> >
> > ```bash theme={null}
> >   NEW_URL ='redis://aptible:pa$word@localhost.aptible.in:6379'
> > ```
> >
> > **4. Retrieve the Old Database's Database Credentials**
> >
> > To initialize replication, you'll need the [Database Credentials](https://www.aptible.com/docs/core-concepts/managed-databases/connecting-databases/database-credentials.md) of the old database. We'll refer to these values as follows:
> >
> > * `OLD_HOST`
> > * `OLD_PORT`
> > * `OLD_PASSWORD`
> >
> > **5. Connect to the New Database**
> >
> > Using the Redis CLI in the original terminal, connect to the new database:
> >
> > ```bash theme={null}
> >   redis-cli -u $NEW_URL
> > ```
> >
> > **6. Initialize Replication**
> >
> > Using the variables from Step 4, run the following commands on the new database to initialize replication.
> >
> > ```bash theme={null}
> >   REPLICAOF $OLD_HOST $OLD_PORT
> >   CONFIG SET masterauth $OLD_PASSWORD
> > ```
> >
> > **7. Cutover to the New Database**
> >
> > 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.
> >
> > > [!WARNING]
> > >
> > > Deleting a Database, even as part of an upgrade, automatically deletes its associated Backups. The only exception is a final backup, which Aptible retains if the Environment's **Keep final backup for deprovisioned databases** setting is enabled. If you'd like to retain historical Backups, open a ticket with [Aptible Support](https://www.aptible.com/docs/how-to-guides/troubleshooting/aptible-support.md) before deprovisioning.
>
> > [accordion] Method 2: Dump and Restore to a new Redis Database
> >
> > > [!TIP]
> > >
> > > 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.
> >
> > > [!NOTE]
> > >
> > > **Prerequisite:** Install the [Aptible CLI](https://www.aptible.com/docs/reference/aptible-cli/cli-commands/overview), [Redis CLI](https://redis.io/docs/install/install-redis/), and [rdb tool](https://github.com/sripathikrishnan/redis-rdb-tools)
> >
> > **1. Collection Configuration Information**
> >
> > 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:
> >
> > ```bash theme={null}
> >   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. Run `aptible db:versions` to see a full list of options. Note that there are different ["flavors" of Redis](https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/redis.md) 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](https://www.aptible.com/docs/core-concepts/scaling/database-scaling.md#ram-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:
> >
> > ```bash theme={null}
> >   NEW_HANDLE = 'upgrade-test'
> >   NEW_VERSION = '7.0'
> >   NEW_CONTAINER_SIZE = 2048
> >   NEW_DISK_SIZE = 10
> > ```
> >
> > **2. Provision the New Database**
> >
> > Create the new Database using `aptible db:create`.
> >
> > Example:
> >
> > ```bash theme={null}
> >   aptible db:create "$NEW_HANDLE" \
> >   --type "redis" \
> >   --version "$NEW_VERSION" \
> >   --container - size $NEW_CONTAINER_SIZE \
> >   --disk - size $NEW_DISK_SIZE \
> >   --environment "$ENVIRONMENT"
> > ```
> >
> > **3. Tunnel into the Old Database**
> >
> > In a separate terminal, create a [Database Tunnel](https://www.aptible.com/docs/core-concepts/managed-databases/connecting-databases/database-tunnels.md) to the old Database using the `aptible db:tunnel` command.
> >
> > Example:
> >
> > ```bash theme={null}
> >   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:
> >
> > ```bash theme={null}
> >   OLD_URL = 'redis://aptible:pa$word@localhost.aptible.in:6379'
> > ```
> >
> > **4. Dump the Old Database**
> >
> > Dump the old database to a file locally using rdb and the Redis CLI.
> >
> > Example:
> >
> > ```bash theme={null}
> >   redis-cli -u $OLD_URL --rdb dump.rdb
> > ```
> >
> > **5. Tunnel into the New Database**
> >
> > In a separate terminal, create a [Database Tunnel](https://www.aptible.com/docs/core-concepts/managed-databases/connecting-databases/database-tunnels.md) to the new Database using the `aptible db:tunnel` command, and save the Connection URL as `NEW_URL`.
> >
> > **6. Restore the Redis 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
> > ```
> >
> > **7. Cutover to the New Database**
> >
> > Point your Apps and other resources to your new database and deprovision the old database using the command `aptible db:deprovision`.
> >
> > > [!WARNING]
> > >
> > > Deleting a Database, even as part of an upgrade, automatically deletes its associated Backups. The only exception is a final backup, which Aptible retains if the Environment's **Keep final backup for deprovisioned databases** setting is enabled. If you'd like to retain historical Backups, open a ticket with [Aptible Support](https://www.aptible.com/docs/how-to-guides/troubleshooting/aptible-support.md) before deprovisioning.