Back up and restore data

InfluxDB 3 Core persists all data and metadata to object storage. Back up your data by copying object storage files in a specific order to ensure consistency and reliability.

Supported object storage

InfluxDB 3 supports the following object storage backends for data persistence:

• File system (local directory)
• AWS S3 and S3-compatible storage (MinIO)
• Azure Blob Storage
• Google Cloud Storage

File structure

Backup process

Recommended backup order:

1. Snapshots directory
2. Database (dbs) directory
3. WAL directory
4. Catalog directory
5. Catalog checkpoint file

#!/bin/bash
NODE_ID="
NODE_ID
"
DATA_DIR="/path/to/data"
BACKUP_DIR="/backup/$(date +%Y%m%d-%H%M%S)"

mkdir -p "$BACKUP_DIR"

# Copy in recommended order
cp -r $DATA_DIR/${
NODE_ID}/snapshots "$BACKUP_DIR/"
cp -r $DATA_DIR/${
NODE_ID}/dbs "$BACKUP_DIR/"
cp -r $DATA_DIR/${
NODE_ID}/wal "$BACKUP_DIR/"
cp -r $DATA_DIR/${
NODE_ID}/catalog "$BACKUP_DIR/"
cp $DATA_DIR/${
NODE_ID}/_catalog_checkpoint "$BACKUP_DIR/"

echo "Backup completed to $BACKUP_DIR"

#!/bin/bash
NODE_ID="
NODE_ID
"
SOURCE_BUCKET="
SOURCE_BUCKET
"
BACKUP_BUCKET="
BACKUP_BUCKET
"
BACKUP_PREFIX="backup-$(date +%Y%m%d-%H%M%S)"

# Copy in recommended order
aws s3 sync s3://${
SOURCE_BUCKET}/${
NODE_ID}/snapshots \
  s3://${
BACKUP_BUCKET}/${BACKUP_PREFIX}/${
NODE_ID}/snapshots/

aws s3 sync s3://${
SOURCE_BUCKET}/${
NODE_ID}/dbs \
  s3://${
BACKUP_BUCKET}/${BACKUP_PREFIX}/${
NODE_ID}/dbs/

aws s3 sync s3://${
SOURCE_BUCKET}/${
NODE_ID}/wal \
  s3://${
BACKUP_BUCKET}/${BACKUP_PREFIX}/${
NODE_ID}/wal/

aws s3 sync s3://${
SOURCE_BUCKET}/${
NODE_ID}/catalog \
  s3://${
BACKUP_BUCKET}/${BACKUP_PREFIX}/${
NODE_ID}/catalog/

aws s3 cp s3://${
SOURCE_BUCKET}/${
NODE_ID}/_catalog_checkpoint \
  s3://${
BACKUP_BUCKET}/${BACKUP_PREFIX}/${
NODE_ID}/

echo "Backup completed to s3://${
BACKUP_BUCKET}/${BACKUP_PREFIX}"

Restore process

Recommended restore order:

1. Catalog checkpoint file
2. Catalog directory
3. WAL directory
4. Database (dbs) directory
5. Snapshots directory

File system restore example

#!/bin/bash
NODE_ID="
NODE_ID
"
BACKUP_DIR="/backup/
BACKUP_DATE
"
DATA_DIR="/path/to/data"

# 1. Stop InfluxDB
systemctl stop influxdb3 || docker stop influxdb3-core

# 2. Optional: Clear existing data for clean restore
rm -rf ${DATA_DIR}/${
NODE_ID}/*

# 3. Restore in reverse order of backup
mkdir -p ${DATA_DIR}/${
NODE_ID}
cp ${BACKUP_DIR}/_catalog_checkpoint ${DATA_DIR}/${
NODE_ID}/
cp -r ${BACKUP_DIR}/catalog ${DATA_DIR}/${
NODE_ID}/
cp -r ${BACKUP_DIR}/wal ${DATA_DIR}/${
NODE_ID}/
cp -r ${BACKUP_DIR}/dbs ${DATA_DIR}/${
NODE_ID}/
cp -r ${BACKUP_DIR}/snapshots ${DATA_DIR}/${
NODE_ID}/

# 4. Set correct permissions (important for Docker)
chown -R influxdb:influxdb ${DATA_DIR}/${
NODE_ID}

# 5. Start InfluxDB
systemctl start influxdb3 || docker start influxdb3-core

Replace the following:

• NODE_ID: your node ID
• BACKUP_DATE: backup directory timestamp (for example, 20240115-143022)

S3 restore example

#!/bin/bash
NODE_ID="
NODE_ID
"
BACKUP_BUCKET="
BACKUP_BUCKET
"
BACKUP_PREFIX="backup-
BACKUP_DATE
"
TARGET_BUCKET="
TARGET_BUCKET
"

# 1. Stop InfluxDB
# Implementation depends on your deployment method

# 2. Optional: Clear existing data for clean restore
aws s3 rm s3://${
TARGET_BUCKET}/${
NODE_ID} --recursive

# 3. Restore from backup
aws s3 sync s3://${
BACKUP_BUCKET}/${BACKUP_PREFIX}/${
NODE_ID}/ \
  s3://${
TARGET_BUCKET}/${
NODE_ID}/

# 4. Start InfluxDB
# Implementation depends on your deployment method

Replace the following:

• NODE_ID: your node ID
• BACKUP_DATE: backup timestamp
• BACKUP_BUCKET: bucket containing backup
• TARGET_BUCKET: target bucket for restoration

Recovery expectations

Object storage features and backup planning

Versioning

If your object storage provider supports it, consider enabling short-term object versioning on the object store backing InfluxDB 3 Core — typically 1–2 days — to protect against errant writes or accidental deletions. With versioning enabled, the object store retains distinct versions of each updated object, which can be used to recover from these incidents.

InfluxDB 3 Core writes mostly immutable Parquet files and rarely updates existing objects, so versioning helps most with recovering specific accidentally deleted files. If many files are affected at once, recovering them through individual version restores becomes impractical.

Versioning costs grow with object update frequency. InfluxDB 3 Core’s compaction process generates new Parquet files over time, so each compaction pass adds to the retained version count in a versioned bucket. Use the shortest retention window that meets your recovery needs, and treat versioning as a short-window safety net rather than a long-term backup substitute.

Periodic backups

Provider-side features like versioning, soft delete, and point-in-time recovery protect against many failure modes but do not replace backups. Periodic backups to a separate object store remain the only predictable, repeatable way to recover from:

• Corruption or compromise of the primary object store.
• Accidental or malicious deletion of data.
• Bad data written into the primary store (a replica of bad data is not a valid recovery point).

The backup process above is provider-agnostic — you can use any provider-native tool to copy to a separate bucket, container, or account, as long as you preserve the documented directory structure and file ordering. Schedule copies during low-load periods or downtime windows when possible.

Containerized deployments

When running InfluxDB 3 Core in containers:

• Volume consistency: Use the same volume mounts for backup and restore operations
• File permissions: Ensure container user can read restored files (use chown if needed)
• Backup access: Mount a backup directory to copy files from containers to the host

Excluded files

Files in <node_id>/table-snapshots/ are intentionally excluded from backup:

• These files are periodically overwritten
• They regenerate automatically on server restart
• Including them doesn’t harm but increases backup size unnecessarily

Backup timing

• Perform backups during downtime or minimal load periods
• Copying files while the database is active may create inconsistent backups
• Consider using filesystem or storage snapshots if available
• Compression is optional but recommended for long-term storage