Skip to main content
RDB export and import move data between deployments without creating a new one. An export copies a deployment’s data to RDB files in a backup repository. An import loads RDB data into an existing deployment, in place. The source and target can have different topologies and shard counts, and the source can be a FalkorDB or Redis server that FalkorDB Enterprise doesn’t manage. Backups and restores are a separate feature. A backup can only be restored to a new deployment, while an RDB import writes into a running one.

​
How it works

The Admin Server runs the FalkorDB fork of redis-rdb-cli in Kubernetes Jobs:
  • Export. For each shard, the Job reads a snapshot from a replica (or the primary) over the replication protocol and writes it to <shard>.rdb in the backup repository. Each export gets its own folder, falkordb-rdb/<namespace>/<deployment>/<manual or schedule name>/<export name>/, which also holds a manifest.json.
  • Import. The Job replays every key of the source into the target’s primary. In a sharded target, keys are routed to the shard that owns them.
  • Schedules. A scheduled export is a Kubernetes CronJob. After each successful run, it deletes all but the newest exports of that schedule.
Connection details, including passwords, are passed to each Job through its own Secret. The Secret is deleted with the Job.

​
Requirements

  • A backup repository with the access method Mount. The default PVC repository qualifies. Repositories that use the Tool access method can’t be used.
  • A ready primary in every shard of the target.
  • For a deployment with TLS, the Admin Server must be able to read its CA certificate. This is always true for the Enterprise and cert-manager issuers.
A PVC repository keeps a separate volume in each namespace. An export written in one namespace is imported by a Job that runs in that namespace and connects to the target over the cluster network. If you use NetworkPolicies, allow traffic from pods labeled app.kubernetes.io/component=rdb-transfer to the target’s FalkorDB port.

​
Export a deployment

1

Open the deployment

In the Admin UI, open the deployment and select Data transfer.
2

Start the export

Click Export. Choose the repository and whether to read from a Replica (the default; falls back to the primary when a shard has no ready replica) or always from the Primary. Optionally, enter a key pattern.
3

Wait for it to finish

The export appears in the list as Pending, then Running, then Succeeded with its files, size, and key count. Click the logs icon to follow it.
From the Admin CLI:
Options: --repository <name>, --node replica|primary, --db 0,1, --key-pattern <regex>, --cpu <limit>, --memory <limit>.
A key pattern is a regular expression that can match anywhere in the key; anchor it with ^ and $. It must also match a graph’s other keys: FalkorDB stores a graph as its own key plus a telemetry{graph} stream and, for a large graph, keys named {graph}graph_<id>. A pattern like ^social$ drops those keys, and the exported graph can’t be loaded. social matches all of them.
Exports of a sharded deployment are taken shard by shard. They aren’t a consistent point-in-time copy across shards. Pause writes first if you need one.

​
Schedule exports

In Data transfer, click Add schedule, or choose On a schedule in the export dialog. Set: Runs never overlap: a run that is due while the previous one is still going is skipped. Use Run now to start one immediately, and the pause button to suspend the schedule.

​
Import into a deployment

1

Choose the source

Open the target deployment, select Data transfer, and click Import. Choose one of:
2

Choose what happens to existing data

  • Merge keeps every key that already exists in the target and skips the imported value. A graph that already exists in the target can’t be merged: the import checks for this first and fails without writing anything.
  • Replace deletes every key in the target, on every primary, before it imports. The target is only emptied once the source has been read successfully. Type the deployment’s name to confirm.
3

Choose a snapshot and rollback

  • Snapshot before importing (checked by default) saves the target before changing it, so the import can be rolled back.
  • Roll back automatically if the import fails (checked by default) restores that snapshot by itself when the import fails. Clear it to decide yourself.
Without a snapshot the import is faster and uses no repository space, but it can’t be undone. See Snapshots and rollback.
4

Check the result

When the import succeeds, it shows how many keys were imported and how many were skipped because they already existed.
From the Admin CLI, choose exactly one source:
The CLI reads a --from-uri password from FALKORDB_SOURCE_PASSWORD, or from standard input with --source-password-stdin, so it never appears in your shell history. --rollback auto|manual|none chooses what happens on failure, and --snapshot-repository <name> where the snapshot of a live copy is kept. For a live copy into an older target, --rdb-version <n> writes data in an older RDB format.
Importing a graph over an existing graph of the same name is not supported in either mode. On FalkorDB 4.20 it crashes the target. Merge mode refuses it, and replace mode deletes the existing graph first.
Every import reads its source once before writing anything: a merge to check for existing graphs, a replace to make sure the source can be read before the target is emptied. A live copy from another deployment or a Redis URI therefore makes the source take two snapshots.

​
Checks before an import

Before anything else, an import from an export or a repository file checks every file with redis-check-rdb, run from the target deployment’s own image. The import stops without changing the target when a file:
  • fails its checksum, or has a value that can’t be read, for example because it is truncated;
  • uses an RDB format version the target’s server can’t read, for example an export of a newer FalkorDB.
Because the check uses the target’s own server, a file that passes can be loaded by that deployment. Files are never converted to an older RDB format: export the data from a deployment running the same or an older version, or copy it live with rdbVersion. Live sources are read directly and aren’t checked first.

​
Snapshots and rollback

Unless Snapshot before importing is unchecked, an import saves the target before changing it. The snapshot is taken from the primary of each shard, after every check passed, into falkordb-rdb/<namespace>/<deployment>/pre-import/<import name>/ in a repository volume:
  • for an import from a file, in the repository holding the file;
  • for a live copy, in the default repository, or the one you choose.
The target is only changed after the snapshot is complete. An import that fails before then left the target as it was, and shows Data unchanged. To restore a snapshot, the Admin Server deletes every key in the target and imports the snapshot, as a replace-mode import listed with the target’s other imports. With Roll back automatically if the import fails, this starts within about 30 seconds of a failure. Otherwise, or to undo an import that succeeded, click Roll back on the import, or run:
Writes made to the target after the snapshot are lost when it is restored. Deleting an import deletes its snapshot too, unless you keep its files; an import can’t be deleted while its rollback runs.

​
Delete exports and imports

Deleting an export also deletes its files from the repository, unless you choose Keep the RDB files in the repository (--keep-files in the CLI). Deleting an import deletes its snapshot the same way. Deleting a running export or import stops it. A stopped import leaves the keys it has already written; roll it back first if it took a snapshot. Deleting a schedule deletes the history of its exports and, unless you keep them, their files.

​
Retention

Finished exports and imports are deleted automatically after a number of days set in the Admin UI, under Settings > Retention: 0 turns either one off. The count starts when the transfer finishes, and the Admin Server checks every 10 minutes. It deletes transfers exactly as Delete does, and records each deletion in the audit log as system. It never deletes a transfer that is still running, an import whose rollback is running or about to start, or an export from a schedule: a schedule keeps its newest exports by its own retention. Once an import is deleted, its snapshot is gone and the import can no longer be rolled back. To keep that option longer, raise RDB Import Retention. The Helm values adminServer.bootstrap.settingsConfig.settings.retention.rdb_import_retention_days and rdb_export_retention_days set the initial values when the chart creates the settings (adminServer.bootstrap.settingsConfig.create: true).

​
Permissions

RDB export and import use the clusters.transfers resource: An import that reads from another namespace, whether an export, a repository volume, or a deployment there, also needs create in that namespace. The predefined operator role has every action, and the viewer role has list and get.

​
Troubleshooting