Importing Data into Redis

Redis data can be imported using persistence restores (RDB or AOF files) or by synchronizing from a live source via replication. Each approach has different operational tradeoffs depending on dataset size, downtime tolerance, and Redis version compatibility. This article explains when to use each method, how to execute it safely, and how to resolve common version-related errors, such as “Unknown option”, during migration or restore operations.

This guidance applies to self-managed Redis and Redis Software deployments with OS-level access. 

Quick Fix Table

Prerequisites

Before importing data:

Version compatibility

• The target Redis version must be the same as, or newer than, the source version.

• Newer Redis can load older RDB files.

• Older Redis cannot load RDB files created by newer versions.

Capacity planning

• Ensure sufficient memory for the dataset.

• Ensure adequate disk space for RDB or AOF files.

Access requirements

• Ability to stop and start Redis.

• File system access to the Redis persistence directory.

Rollback planning

• Keep original RDB or AOF files.

• Take a fresh backup before final cutover.

Method 1: Restore from an RDB File

Best for fresh instances or controlled restarts

Step 1 – Identify Persistence Settings

Check redis.conf for:

• dir

• dbfilename

Or retrieve at runtime:

CONFIG GET dir
CONFIG GET dbfilename

Step 2 – Stop Redis

Example (systemd):

sudo systemctl stop redis

Step 3 – Place the RDB File

• Copy the RDB file into the configured dir.

• Ensure the filename matches dbfilename.

  • Rename the file, or

  • Update dbfilename in redis.conf.

Set ownership and permissions:

sudo chown redis:redis /path/to/dump.rdb
sudo chmod 640 /path/to/dump.rdb

Step 4 – Start Redis and Verify

sudo systemctl start redis

Verify load status:

INFO persistence

Confirm:

• rdb_last_load_status:ok

• loading:0

Validate dataset:

INFO keyspace
GET <key>
HGETALL <hash>
TTL <key>

Important: Loading an RDB replaces all existing in-memory data.

Method 2: Restore from an AOF File

Best for environments using append-only persistence

Important: Loading an AOF on startup reconstructs the dataset from the log and overwrites any existing in‑memory data.

Step 1 – Confirm AOF Settings

Ensure:

appendonly yes
appendfilename appendonly.aof

Step 2 – Stop Redis and Place File

• Stop Redis.

• Copy the AOF file into the configured dir.

• Set proper ownership and permissions.

Step 3 – Repair if Necessary

If corruption is suspected, repair a copy:

redis-check-aof --fix appendonly.aof

Step 4 – Start Redis and Verify

Check:

INFO persistence
INFO keyspace

Confirm:

• No loading errors

• No rewrite in progress

• Expected keys are present

Method 3: Migration via Replication

Best for minimal downtime migrations

Replication allows the target instance to download a snapshot and then replay incremental updates from the source.

Prechecks

• The target Redis version must be the same or newer.

• The dataset fits in the available memory.

• Network connectivity exists between the target and source (default port 6379).

• TLS replication is configured if required.

Step 1 – Configure Authentication

Redis 6 and newer:

CONFIG SET masteruser <user>
CONFIG SET masterauth <password>

Older Redis:

CONFIG SET masterauth <password>

Step 2 – Start Replication

On the target:

REPLICAOF <source_host> <source_port>

Note: When replication completes, the target dataset will match the source. Any pre‑existing keys on the target that don’t exist on the source will be removed.

Step 3 – Monitor Synchronization

INFO replication

Confirm:

• master_link_status:up

• master_sync_in_progress:0

Review logs for successful synchronization.

Step 4 – Cutover (Optional)

For exact timing:

• Temporarily stop writes on the source.

• Wait until replication lag reaches zero.

Step 5 – Promote Target

REPLICAOF NO ONE
CONFIG REWRITE

Update client applications to use the new instance.

Advanced: Key-by-Key Migration

Using MIGRATE (Version Dependent)

Redis 6 and newer with ACL:

MIGRATE <dest> <port> "" 0 5000 KEYS key1 key2 COPY REPLACE AUTH2 <user> <pass>

Older Redis:

MIGRATE <dest> <port> "" 0 5000 KEYS key1 key2 COPY REPLACE AUTH <pass>

Best practices:

• Use SCAN to iterate in small batches.

• Avoid blocking large transfers.

• Confirm supported options with HELP MIGRATE.

Capturing an RDB from a Live Source

To generate a snapshot without stopping the source:

redis-cli --rdb /tmp/source.rdb -h <host> -p <port> -a <password>

Then restore using the RDB method above.

Resolving “Unknown Option” Errors

These errors usually indicate a version mismatch or unsupported flags.

Verify Versions

redis-server -v
redis-cli -v
INFO server

Confirm Supported Syntax

HELP <command>
COMMAND DOCS <command>

Common causes:

• AUTH2 requires Redis 6+

• RESTORE REPLACE unsupported on older versions

• Some MIGRATE flags are missing in legacy releases

Startup Flag Errors

If Redis fails to start due to an unknown flag:

• Move configuration into redis.conf instead of CLI flags.

Common valid flags:

--port
--dir
--dbfilename
--appendonly yes

Important Clarification

There is no Redis command to import an RDB.

Correct process:

1. Stop Redis.

2. Place file as dbfilename in dir.

3. Start Redis.

redis-cli --rdb exports a snapshot. It does not load one.

Shell Quoting Issues

Wrap passwords containing special characters:

-u 'redis://user:pass@host:port'

Note: If passwords contain special characters like @ or : in Redis URLs, URL‑encode them (percent‑encoding) in addition to quoting.

Post-Import Validation Checklist

Run:

INFO keyspace
INFO persistence

Confirm:

• loading:0

• No background saves or rewrites in progress

• Expected database sizes

Spot-check critical keys:

GET <key>
TTL <key>

Review logs for:

• Memory pressure warnings

• Replication errors

• Persistence failures

Safety and Rollback Best Practices

• Test procedures in staging first.

• Keep original persistence files.

• Take a fresh backup before cutover.

• For large datasets, temporarily consider adjusting:

  • repl-backlog-size

  • client-output-buffer-limit (replica class)

• Return to standard values once migration stabilizes.

This article provides the correct operational procedures for importing data into Redis while avoiding common version mismatches and configuration errors.