Backup and Restore
This document provides a high-level overview of XTDB’s stateful architecture and outlines what data is stored where, what typical backups include, and how to think about restoring XTDB in different failure scenarios.
Overview of Stateful Components
XTDB consists of two primary stateful components:
Log
The log contains the record of all submitted transactions and inter-node messages.
-
The log is structured as a totally ordered, append-only sequence of entries.
-
Each transaction is recorded immutably and assigned a durable log offset.
-
The log guarantees ACID-compliant, serial execution of all writes across the cluster.
From a backup perspective, the log is the source of truth for all changes made to the database. Losing log entries that have not yet been indexed into storage risks permanent data loss.
For more information on the available implementations of the transaction log, see the Log docs.
Storage Module
The storage module contains the database’s state: tables, indexes, and supporting metadata.
-
Storage consists of immutable, append-only files.
-
Each file represents a snapshot of the database’s state at a specific point in the transaction log.
From a backup perspective, storage files can be treated as immutable snapshots aligned with specific log offsets, making them well-suited to incremental or full backup strategies.
For more information on available storage backends and configuration, see the Storage Module docs.
What Data Is at Risk?
| Component | Risk if Lost |
|---|---|
Log |
All transactions on the log since the last indexed offset would be lost. |
Storage Module |
Without a backup or infinite retention on the log, all indexed data would be lost. |
XTDB compute nodes |
Only transient, in-memory cache state would be lost. All critical data is durably recorded in the log and storage module. Compute nodes can be restarted or replaced without risking data loss. |
Failure and Recovery Scenarios
The following are common failure scenarios and links to detailed guidance for each: