RadiatorDB Backup

RadiatorDB backup operations export and import full or filtered 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 write or all privilege. Collection-level RadiatorDB roles cannot grant access to backup operations.

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

Backup metadata records source time-series collection names and effective export bounds. It does not record source partition intervals. Restore uses the target collection's configured interval. Management API import can restore an included time-series collection when the target configuration registers it as time-series storage. An excluded time-series collection does not block a filtered normal-collection import.

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,
  "collections": {
    "include": [
      {"name": "users"},
      {
        "name": "events",
        "from": "2026-07-01T00:00:00Z",
        "until": "2026-08-01T00:00:00Z"
      }
    ]
  }
}

The export request accepts these JSON fields:

collections.include must contain one or more unique entries. Each entry contains name and can contain from or until. from is inclusive and until is exclusive. Either bound can be omitted. Bounds apply only to live rows in that time-series collection. Normal documents and revisions remain unbounded. A bound on a normal collection returns 400 Bad Request.

Time-series bounds select rows during export. They do not create an import range. Import collection filters select complete collections by name.

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'

Import only users and devices by percent-encoding {"include":[{"name":"users"},{"name":"devices"}]}:

curl -u alice:password \
  -X POST \
  --data-binary @selected.jsonl.gz \
  'https://radiator.example.com/api/v1/backends/radiatordb/RADIATORDB/backups/import?collections=%7B%22include%22%3A%5B%7B%22name%22%3A%22users%22%7D%2C%7B%22name%22%3A%22devices%22%7D%5D%7D'

The importer parses every JSON Lines record. It skips excluded document and revision records before field validation, conflict handling, batching, and summary counting. Malformed JSON and a second metadata line still fail the import.

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

By default, import validates and canonicalizes document keys and document and revision payloads with the active collection schemas. Set validate_schema=false only when disaster recovery requires restoring values that no longer match the active configuration. This setting preserves those values without schema-driven canonicalization. The import still enforces the backup format, metadata, structural key, storage, transaction, database, and PostgreSQL constraints. Schema-invalid data can be unavailable to normal operations until you repair the data or restore a compatible schema.

Import Strategies

Use strategy to choose whether import replaces the backend or merges backup documents into existing data. The strategy descriptions in this section apply to normal collections. For time-series restrictions, see Time-series Import Strategies.

reset

reset is the default strategy. An unfiltered reset removes all existing live documents and revisions on every configured RadiatorDB node. A filtered reset clears only included normal documents, revisions, and time-series collection parents. It preserves excluded rows and topology.

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.

Time-series Import Strategies

Time-series from and until bounds select live rows during backup export. They do not define an import range. An import collection filter selects the complete time-series collection by name, not a time range. Time-series import supports only reset and skip.

Use reset only when the included time-series collection must match the backup contents. For example, importing a backup exported with from and until removes existing events before from and at or after until.

Use skip to restore deleted events from a bounded backup without changing events that still exist. Do not use override or newest when the selected backup data contains time-series documents. RadiatorDB rejects the import when it reaches a selected time-series document.

The target backend must register the collection as time-series storage. During import, RadiatorDB creates required partitions from each imported event timestamp and the target collection's configured partition interval. The source partition interval is not stored in the backup.

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:

Version 1 backups created before timeseriesCollections remain importable. A missing or empty list means that source storage information is unknown. Time-series restore derives every required partition from each document key and the target collection configuration.

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