# Restoring a Backup

Restoring KeyDB backups is critical for disaster recovery, staging environment replication, or rolling back to a known good state. Elestio supports restoration via its web dashboard and manual methods using Docker Compose and command-line tools. This guide covers how to restore KeyDB backups from RDB or AOF files, for both full and partial restore scenarios, and includes fixes for common errors during the process.

## **Restoring from a Backup via Terminal**

This method assumes you already have a backup file such as <span class="s3">dump.rdb</span> or <span class="s3">appendonly.aof</span>. Restoring involves stopping the container, replacing the data file(s), and restarting KeyDB so it can load the new data at boot time.

#### **Stop the KeyDB Container**

Cleanly stop the container to prevent data corruption:

```bash
docker-compose down
```

#### **Replace the Backup File**

Move the desired backup file into the volume directory that maps to the KeyDB container’s <span class="s2">/data</span>.

Example for RDB:

```bash
cp ./backup_2025_06_24.rdb /opt/app/data/dump.rdb
```

> Ensure your <span class="s1">docker-compose.yml</span> contains the correct volume mapping:

```yaml
volumes:
  - ./data:/data
```

For AOF-based persistence:

```bash
cp ./appendonly_2025_06_24.aof /opt/app/data/appendonly.aof
```

#### **Restart KeyDB**

Bring the container back up:

```bash
docker-compose up -d
```

KeyDB will automatically load <span class="s1">dump.rdb</span> or <span class="s1">appendonly.aof</span> depending on its configuration in <span class="s1">keydb.conf</span> or Docker entrypoint.

## **Restoring via Docker Compose Terminal**

If you prefer working inside the container environment, you can directly inject the backup file into the KeyDB container using Docker commands.

#### **Copy the Backup File into the Container**

For RDB:

```bash
docker cp ./backup_2025_06_24.rdb $(docker-compose ps -q keydb):/data/dump.rdb
```

For AOF:

```bash
docker cp ./appendonly_2025_06_24.aof $(docker-compose ps -q keydb):/data/appendonly.aof
```

#### **Restart the KeyDB Container**

```bash
docker-compose restart keydb
```

KeyDB will now reload the updated data file(s) during startup.

## **Partial Restores in KeyDB**

KeyDB, like Redis, does not support partial data restoration out of the box. However, workarounds exist to selectively restore key-value pairs or subsets of data.

#### **Restore Selected Keys via CLI**

If you’ve exported a list of keys and their values, you can restore them using a script with <span class="s2">keydb-cli</span>:

```bash
cat keys_to_restore.txt | while read key; do
  value=$(cat dump.json | jq -r ".\"$key\"")
  keydb-cli SET "$key" "$value"
done
```

This method is useful when working with pre-filtered exports in JSON, CSV, or key dumps

#### **Restore from a Partial AOF**

If your backup is a trimmed-down AOF file (e.g., created by filtering certain operations), KeyDB will replay it entirely at startup:

1. Replace the existing <span class="s1">appendonly.aof</span> file.
2. Restart the container.
3. KeyDB will process only the included operations, effectively performing a partial restore.

## **Common Errors &amp; How to Fix Them**

Restoring KeyDB may occasionally fail due to configuration mismatches, permission issues, or corrupted backup files. Below are common errors and their solutions.

##### **1. NOAUTH Authentication Required**

**Error:**

```
(error) NOAUTH Authentication required.
```

<span class="s1">**Cause:**</span> The KeyDB instance requires authentication for any CLI interaction.

**Fix:**

```
keydb-cli -a yourpassword
```

In scripts:

```
keydb-cli -a "$KEYDB_PASSWORD" < restore_script.txt
```

##### **2. KeyDB Fails to Start After Restore**

**Error:**

```
Fatal error loading the DB: Invalid RDB format
```

<span class="s1">**Cause:**</span> The backup file is corrupted or incompatible with the KeyDB version.

**Fix:**

- Make sure the backup was created with the same or compatible KeyDB version.
- If necessary, downgrade or upgrade the container image to match the backup version.

##### **3. Data Not Restored**

<span class="s1">**Cause:**</span> KeyDB is configured to use a different persistence method than the one you restored.

**Fix:**

Check your persistence mode in <span class="s3">keydb.conf</span> or Docker entry:

```
appendonly yes    # for AOF
appendonly no     # for RDB
```

Ensure the right file (<span class="s1">dump.rdb</span> or <span class="s1">appendonly.aof</span>) exists at <span class="s1">/data</span>.

##### **4. Permission Denied When Copying Files**

**Error:**

```
cp: cannot create regular file ‘/opt/app/data/dump.rdb’: Permission denied
```

**Fix:**

Use <span class="s1">sudo</span> if your shell user doesn’t have write access:

```
sudo cp ./backup_2025_06_24.rdb /opt/app/data/dump.rdb
```

Or adjust directory permissions:

```
sudo chown $USER:$USER /opt/app/data
```