Use the redis-cli tool to migrate a self-managed Redis database to ApsaraDB for Redis - Tair (Redis® OSS-Compatible)

Use redis-cli to import data from a self-managed Redis database into a Tair (Redis OSS-compatible) instance via an AOF (Append Only File). This approach covers offline data migration only — it does not support real-time synchronization. Run the migration during a planned maintenance window, or when no new data is being written to the source instance.

For real-time migration, use Data Transmission Service (DTS) instead. See Migrate data from a self-managed Redis database to a Tair (Redis OSS-compatible) instance.

Prerequisites

Before you begin, make sure that:

The IP address of your client is added to a whitelist of the Tair (Redis OSS-compatible) instance. See Configure whitelists.
AOF persistence is enabled on the self-managed Redis instance. If not, run:
```
CONFIG SET appendonly yes
```
Hybrid persistence is disabled on the self-managed Redis instance. When aof-use-rdb-preamble is set to yes, the AOF file contains a binary RDB header that redis-cli cannot parse, causing the import to fail. If your self-managed instance runs Redis 5.0 or later, run:
```
CONFIG SET aof-use-rdb-preamble no
```

Migrate data

Step 1: Trigger an AOF rewrite

An active AOF accumulates all commands over time, including redundant ones — for example, incrementing a counter 100 times produces 100 separate entries. Running BGREWRITEAOF compacts those into the shortest equivalent sequence, giving you the latest and most efficient snapshot to import.

redis-cli -h <self-managed-instance-ip> -p <port> BGREWRITEAOF

Expected output:

Background append only file rewriting started

Step 2: Import the AOF into the Tair instance

The following example imports a file named appendonly.aof:

redis-cli -h <tair-instance-endpoint> -p <port> -a <password> --pipe < appendonly.aof

For example:

redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379 -a user:password --pipe < appendonly.aof

Expected output:

All data transferred. Waiting for the last reply...
Last reply received from server.
errors: 0, replies: 90

If a message similar to the preceding one is returned, the migration is successful.

What's next

If AOF persistence is no longer needed on the self-managed instance after the migration, disable it:

redis-cli -h <self-managed-instance-ip> -p <self-managed-instance-port> CONFIG SET appendonly no

FAQ

I get `ERR Protocol error: too big inline request` during import.

This error means the AOF file contains a binary RDB header produced by hybrid persistence. Run CONFIG GET aof-use-rdb-preamble on the self-managed instance to check the current value. If it returns yes, run CONFIG SET aof-use-rdb-preamble no, regenerate the AOF file by running BGREWRITEAOF, and retry the import.

Can I export an AOF file from a Tair instance?

No. Tair (Redis OSS-compatible) instances do not support AOF export.

I get `ERR syntax error` during import.

The Tair instance version is likely older than the self-managed Redis instance. Purchase a Tair instance that matches or exceeds the version of your self-managed instance. For example, if your self-managed instance is compatible with Redis 7.0, the Tair instance must also be Redis 7.0-compatible.