Tair (Redis® OSS-Compatible):Migrate from on-premises or other clouds to Alibaba Cloud Tair

Choose a migration method

This topic covers DTS-based migration (full or full + incremental). For AOF import, see Migrate data from an AOF file.

How it works

Full migration copies all existing data from the source database to the destination. It is free of charge.

Incremental migration runs on top of full migration. After the initial copy, DTS continuously synchronizes new writes from the source to the destination using native Redis replication (PSYNC or SYNC). It is billed based on the duration of the migration, not data volume. For pricing details, see Billing items.

Before starting an incremental migration, disable the replication output buffer limit on the source database to prevent connection drops:

CONFIG SET client-output-buffer-limit 'slave 0 0 0'

Prerequisites

Before you begin, make sure that:

Destination instance

• A Tair (Redis OSS-compatible) instance is created. See Create an instance.

• The destination instance has at least 10% more memory than the memory currently used by the source database. Insufficient memory causes data inconsistency or task failure.

• Transparent Data Encryption (TDE) is not enabled on the destination instance. DTS does not support migrating to TDE-enabled instances.

Source Database

• If using incremental migration, confirm that the source allows the PSYNC or SYNC command.

• The source database account has read permissions. If using a custom account, the password format is <user>:<password> — for example, admin:Rp829dlwa.

Network

• If the source is in an on-premises data center or a third-party cloud, add the DTS server IP addresses for your region to the source firewall's allowlist. See Add the CIDR blocks of DTS servers to a whitelist.

Usage notes

• Do not scale the instance, change the instance type, or change the endpoint of the source or destination database during migration. These operations cause the task to fail and require you to reconfigure it from scratch.

• Migration consumes resources on both databases. Run the migration during off-peak hours.

• The destination database account must have write permissions.

Migrate your Redis database

What's next

• Incremental migration only: After all data is in sync, manually stop or release the task in the DTS console before switching your application to the new instance.

• Verify migrated data: See Validate migrated data.

FAQ

Why does the connection test fail?

Check the password format — Redis credentials use user:password syntax. For more details on login methods, see Logon methods for an instance. If the source is behind a firewall (on-premises or third-party cloud), add the DTS server IP addresses for your region to the allowlist. See Add the CIDR blocks of DTS servers to a whitelist.

Why did the migration task fail?

The most common causes are:

• Scaling, changing the instance type, or changing the endpoint during migration — these require you to reconfigure the task from scratch.

• Destination instance out of memory, or a shard in a cluster instance reaching its memory limit. DTS reports an OOM (out of memory) error and stops.

• TDE enabled on the destination instance — DTS does not support this configuration.

Why is there data inconsistency after migration?

A few known scenarios cause this:

• Expired keys: Keys with a TTL (time-to-live) policy may expire before being deleted. The destination may have fewer keys than the source.

• Duplicate List entries: For List objects, DTS does not flush existing data in the destination when using PSYNC or SYNC. This can produce duplicates.

• Network retries during full migration: If the network is interrupted, DTS retries and overwrites keys with the same name. Delete operations from the source during that retry window are not synced, leaving the destination with more data than the source.

Why does the precheck verify the Redis eviction policy?

The default maxmemory-policy for Tair (Redis OSS-compatible) is volatile-lru. If the destination runs out of memory, this policy evicts keys and causes data inconsistency. Setting the policy to noeviction instead means writes fail when memory is full — the task stops, but no data is silently dropped. For details on eviction policies, see Redis data eviction policies.

Why is there a `DTS_REDIS_TIMESTAMP_HEARTBEAT` key in my source database?

DTS writes a heartbeat key with the prefix DTS_REDIS_TIMESTAMP_HEARTBEAT to track update timestamps. For cluster sources, it writes one key per shard. The key is filtered out during migration and expires automatically after the task ends.

Which commands does incremental migration support?

DTS captures all standard Redis write commands, including:

APPEND, BITOP, BLPOP, BRPOP, BRPOPLPUSH, DECR, DECRBY, DEL, EVAL, EVALSHA, EXEC, EXPIRE, EXPIREAT, FLUSHALL, FLUSHDB, GEOADD, GETSET, HDEL, HINCRBY, HINCRBYFLOAT, HMSET, HSET, HSETNX, INCR, INCRBY, INCRBYFLOAT, LINSERT, LPOP, LPUSH, LPUSHX, LREM, LSET, LTRIM, MOVE, MSET, MSETNX, MULTI, PERSIST, PEXPIRE, PEXPIREAT, PFADD, PFMERGE, PSETEX, PUBLISH, RENAME, RENAMENX, RESTORE, RPOP, RPOPLPUSH, RPUSH, RPUSHX, SADD, SDIFFSTORE, SELECT, SET, SETBIT, SETEX, SETNX, SETRANGE, SINTERSTORE, SMOVE, SPOP, SREM, SUNIONSTORE, ZADD, ZINCRBY, ZINTERSTORE, ZREM, ZREMRANGEBYLEX, ZUNIONSTORE, ZREMRANGEBYRANK, ZREMRANGEBYSCORE, XADD, XCLAIM, XDEL, XAUTOCLAIM, XGROUP CREATECONSUMER, XTRIM

For Lua scripts executed via EVAL or EVALSHA, DTS cannot confirm whether the script succeeded because the destination does not return an explicit result.