RadiatorDB Backup

RadiatorDB backup operations export and import complete RadiatorDB backend data through Radiator Management API. Use backups to move data between environments or restore a RadiatorDB backend from a saved backup file. The API can also export and import gzip-compressed backups.

Backup export and import require Radiator Management API authentication with user.privilege write or all. Collection roles do not restrict backup operations.

Export and import stream backup data instead of loading the full backup into memory. This keeps memory usage low for large backups.

Export Backup

Export a RadiatorDB backup:

POST /api/v1/backends/radiatordb/:db_name/backups/export
Content-Type: application/json

{
  "includeRevisions": true,
  "batchSize": 1000,
  "gzip": true
}

The export request accepts these JSON fields:

Returns 200 OK with a backup stream.

The attachment filename uses the backend name and a sortable timestamp in the server timezone. Radiator picks the timezone from the operating system local timezone setting. If the server timezone cannot be detected, Radiator uses UTC.

The backup contains a consistent snapshot from the start of the export. Other clients can continue to write while the export is running, but those later changes are not included in the backup. Large exports can temporarily increase database load until the export finishes or fails.

Example:

Save a backup file with curl. Use -JO so curl saves the file with the name from the Content-Disposition response header:

curl -JO -u alice:password \
  --json '{"includeRevisions": true, "gzip": true}' \
  https://radiator.example.com/api/v1/backends/radiatordb/RADIATORDB/backups/export

For example, this command can save a compressed backup as RADIATORDB-2026-06-22T13-55-32+0300.jsonl.gz.

Import Backup

Import a gzip-compressed RadiatorDB backup. The import endpoint accepts gzip compressed and plain backup streams:

POST /api/v1/backends/radiatordb/:db_name/backups/import

<backup file stream>

The import endpoint accepts these query parameters:

For strategy behavior, use cases, and caveats, see Import Strategies.

Returns 200 OK with an import summary:

Example response:

{
  "documents": 2,
  "revisions": 5
}

Import a backup file with curl:

curl -u alice:password \
  -X POST \
  --data-binary @RADIATORDB-2026-06-22T13-55-32+0300.jsonl.gz \
  'https://radiator.example.com/api/v1/backends/radiatordb/RADIATORDB/backups/import?importRevisions=true&batchSize=1000'

Use the same request for an uncompressed backup file. RadiatorDB automatically detects the content type from the incoming stream bytes.

Import Strategies

Use strategy to choose whether import replaces the backend or merges backup documents into existing data.

reset

reset is the default strategy. It removes existing live documents and revisions on all configured RadiatorDB nodes, then imports the backup stream.

Before clearing existing data, RadiatorDB waits for cluster synchronization and validates the backup metadata line. After metadata validation, import opens a transaction on every physical RadiatorDB node and truncates documents and revisions inside those transactions. The import then restores backup documents through one transaction node and commits all node transactions after the stream imports successfully and finally commits the transaction on the import node.

Use reset for full restores, disaster recovery, and replacing a test or staging database with a known backup. Use it when you need the imported backend to match the backup file exactly, including revision history.

reset is the only strategy that can import and validate revision records. If importRevisions is omitted, reset imports revisions by default. Set importRevisions=false when you want to restore live documents without revision history.

reset is destructive. Keep a separate valid backup before you run it on production data. If a backup line is malformed, contains a duplicate key, or cannot be written before commit starts, RadiatorDB rolls back all import transactions and preserves the previous backend contents.

If a transaction commit fails after one or more nodes have already committed, RadiatorDB cannot roll back the committed nodes. Keep a separate valid backup file and retry the import to repopulate the backend if a fatal commit error occurs.

override

override imports backup documents into the existing backend and makes conflicting backup documents win over existing documents. A conflict means an existing document has the same collection and key as an imported document.

Use override when the backup file is the desired source for the documents it contains, but you do not want to remove unrelated existing documents. This is useful for partial restores and controlled promotion from another environment.

When an imported document conflicts with an existing document, RadiatorDB may assign a newer updated_at value and a fresh revision UUID to the imported document. This is required for the imported document to win RadiatorDB last-write-wins replication on synchronized clusters.

override cannot import revisions.

skip

skip imports backup documents only when the backend does not already have an document with the same collection and key.

Use skip to seed missing documents without overwriting operator changes. This is useful when you import a baseline data set into a backend that may already contain local edits.

Import summary document counts include only documents imported or restored. Skipped conflicts are not included in the document count.

skip cannot import revisions.

newest

newest imports backup documents and lets RadiatorDB last-write-wins conflict resolution choose between an imported document and an existing document.

Use newest when you merge backups from synchronized or related environments and want the document with the newest RadiatorDB update metadata to win. This can preserve newer production edits while still restoring older missing documents.

If an imported document has the same timestamp as an existing document, RadiatorDB uses its normal conflict tie-break rules.

newest cannot import revisions.

Backup File Format

The backup file is a JSON Lines stream, or a gzip-compressed JSON Lines stream. Each non-empty line in the uncompressed stream must contain one complete JSON object. The first non-empty line must be a metadata record. The remaining lines can be document or revision records.

When export compression is enabled, the attachment filename ends with .jsonl.gz. When export compression is disabled, the response uses Content-Type: application/x-jsonl, and the attachment filename ends with .jsonl. Use the same content type when you import an uncompressed backup file.

For example, an export from backend RADIATORDB can create RADIATORDB-2026-06-22T13-55-32+0300.jsonl.gz for a compressed backup, or RADIATORDB-2026-06-22T13-55-32+0300.jsonl for an uncompressed backup.

Metadata records have these fields:

Document and revision records have these fields:

When previous is not null, it has this shape:

Example backup stream:

{"type":"metadata","format":"radiatordb-backup-jsonl","version":1,"createdAt":"2026-06-12T10:00:00+03:00","includeRevisions":true}
{"type":"document","key":["helsinki","edge-1"],"rev":"00000000-0000-0000-0000-000000000001","data":{"hostname":"edge-1","enabled":true},"expire_at":null,"previous":null,"collection":"DEVICES","created_at":"2026-06-12T10:00:00Z","updated_at":"2026-06-12T10:15:00Z","updated_by":"alice","origin":"node-1"}
{"type":"revision","key":["helsinki","edge-1"],"rev":"00000000-0000-0000-0000-000000000002","data":null,"expire_at":null,"previous":null,"collection":"DEVICES","created_at":"2026-06-12T10:00:00Z","updated_at":"2026-06-12T10:20:00Z","updated_by":"alice","origin":"node-1"}

Related Documentation

• RadiatorDB REST API
• RadiatorDB overview
• RadiatorDB backend configuration