Documentation

InfluxDB OSS

v1

Back up and restore data

This page documents an earlier version of InfluxDB OSS. InfluxDB OSS v2 is the latest stable version. See the equivalent InfluxDB v2 documentation.

Use the InfluxDB 1.11 backup and restore utilities to prevent unexpected data loss and preserve the ability to restore data if it ever is lost. These utilities let you:

  • Back up and restore multiple databases at a time.
  • Back up specific time ranges.
  • Import data from InfluxDB Enterprise clusters.
  • Create backup files compatible with InfluxDB Enterprise.

InfluxDB Enterprise users

See Back up and restore in InfluxDB Enterprise.

Backup formats

The InfluxDB backup utility outputs data backups in one of two formats: legacy or portable. Each format provides different functionality and support for other versions of InfluxDB. The major difference between the formats is that the legacy format can only be used with InfluxDB OSS 1.x. The portable format is “portable” between InfluxDB 1.5–1.11 and InfluxDB Enterprise.

Backup functionalityLegacy formatPortable format
Back up single databases
Back up multiple databases
Back up single retention polices
Back up multiple retention policies
Back up specific time ranges
Back up remote databases
Restore to InfluxDB OSS 1.0–1.4
Restore to InfluxDB OSS 1.5–1.11
Restore to InfluxDB Enterprise

Specify your backup format

By default, the backup and restore utilities create and restore backups in the legacy format. To create or restore from a backup or in the portable format, include the -portable flag with your backup command.

# Create a backup in the portable format
influxd backup -portable /path/to/backup-destination

# Restore from a portable backup
influxd restore -portable /path/to/backup-destination

We recommend the portable format

We recommend using the portable format unless you need to be able to restore the backup to InfluxDB 1.4 or earlier.

Determine your backup’s format

Use the directory structure of the backup directory to determine the format of the backup.

Portable format directory structure

  • backup-directory/
    • 20060102T150405Z.meta (InfluxDB metadata)
    • 20060102T150405Z.s00.tar.gz (InfluxDB time series data (shard))
    • 20060102T150405Z.s01.tar.gz (InfluxDB time series data (shard))
    • 20060102T150405Z.manifest (Backup manifest)

Legacy format directory structure

  • backup-directory/
    • meta.00 (InfluxDB metadata)
    • <db-name>.<rp-name>.00000.00 (InfluxDB time series data)
    • <db-name>.<rp-name>.00001.00 (InfluxDB time series data)

Backup and restore requirements

  • The InfluxDB service (influxd) must be running except when performing an offline legacy restore.
  • Both the source and target InfluxDB instances must be the same InfluxDB version or differ by only a minor version. For example, you can back up data from InfluxDB 1.7 and restore it to an InfluxDB 1.8 instance. The only exception is restoring data from InfluxDB 1.8 into 1.11.

Important notes

Time-based backups

When executing a backup with -start or -end flags, InfluxDB backs up shards, not individual points. Each shard is annotated with starting and ending timestamps for the time interval included in the shard. If a shard contains any points in the specified time range, the entire shard is included in the backup.

Since most shards are highly compacted, extracting shards to inspect each point would be highly inefficient and add a significant burden to the underlying system.

When restoring data from a time-based backup, you are likely to see data outside of the backed up time range.

Back up data

Use the influxd backup utility to create a backup of time series data and metadata stored in InfluxDB.

backup ignores WAL files and in-memory cache data.

Provide the following for each backup format:

Portable format Legacy format

  • -portable: (Required) Specifies the portable backup format
  • -host: InfluxDB bind address (Only required if creating a backup from a remote InfluxDB host)
  • -db: Database name (If no database name is specified, the command backs up all databases)
  • -rp: Retention policy name (If no retention policy is specified, the command backs up all retention policies)
  • -shard: Shard ID (If no shard ID is specified, the command backs up all shards. Requires a retention policy.)
  • -start: Start time (If no start time is specified, the command backs up data from all time.)
  • -stop: Stop time (If no stop time is specified, the command backs up data to now.)
  • (Required) Backup destination directory path

Backup examples

Back up all databases

influxd backup -portable /path/to/backup-directory

Back up all data from a remote InfluxDB instance

influxd backup -portable \
  -host 203.0.113.0:8088 \
  /path/to/backup-directory

Back up a specific time range

influxd backup -portable \
  -start 2022-01-01T00:00:00Z \
  -stop 2022-02-01T00:00:00Z \
  /path/to/backup-directory

For important information about how time-based backups work, see Time-based backups.

Back up data from a specific time to now

influxd backup -portable \
  -start 2022-01-01T00:00:00Z \
  /path/to/backup-directory

For important information about how time-based backups work, see Time-based backups.

Back up a specific database

influxd backup -portable \
  -db example-db \
  /path/to/backup-directory

Back up a specific retention policy

influxd backup -portable \
  -db example-db \
  -rp example-retention-policy \
  /path/to/backup-directory

Back up a specific shard

To view shard IDs, use the SHOW SHARDS InfluxQL statement.

influxd backup -portable \
  -rp example-retention-policy \
  -shard 123 \
  /path/to/backup-directory
  • -host: InfluxDB bind address (Only required if creating a backup from a remote InfluxDB host)
  • -db: (Required) Database name
  • -rp: Retention policy name (If no retention policy is specified, the command backs up all retention policies)
  • -shard: Shard ID (If no shard ID is specified, the command backs up all shards. Requires a retention policy.)
  • -start: Start time (If no start time is specified, the command backs up data from all time.)
  • -stop: Stop time (If no stop time is specified, the command backs up data to now.)
  • (Required) Backup destination directory path

Legacy backup examples

Back up a database

influxd backup \
  -db example-db \
  /path/to/backup-directory

Back up a database from a remote InfluxDB instance

influxd backup \
  -db example-db \
  -host 203.0.113.0:8088 \
  /path/to/backup-directory

Back up a specific time range

influxd backup \
  -db example-db \
  -start 2022-01-01T00:00:00Z \
  -stop 2022-02-01T00:00:00Z \
  /path/to/backup-directory

For important information about how time-based backups work, see Time-based backups.

Back up data from a specific time to now

influxd backup \
  -db example-db \
  -start 2022-01-01T00:00:00Z \
  /path/to/backup-directory

For important information about how time-based backups work, see Time-based backups.

Back up a specific retention policy

influxd backup \
  -db example-db \
  -rp example-retention-policy \
  /path/to/backup-directory

Back up a specific shard

To view shard IDs, use the SHOW SHARDS InfluxQL statement.

influxd backup -portable \
  -db example-db \
  -rp example-retention-policy \
  -shard 123 \
  /path/to/backup-directory

Restore data

Use the influxd restore utility to restore time series data and metadata to InfluxDB from an InfluxDB backup.

Cannot restore to an existing database

The InfluxDB OSS 1.11 restore utility does not support incremental backups. When restoring data to a running InfluxDB instance, the restore utility performs a full restore. To preserve existing data, the restore utility does not allow restoring data to a database that already exists.*

If the target database already exists, the restore utility returns an error similar to the following:

error updating meta: DB metadata not changed. database may already exist

There is a workaround for restoring data to an existing database. For more information, see Restore data to an existing database.

* Offline legacy restores can be used to restore data to an existing database, but overwrite all data in the database.

Requirements and commands necessary to restore a backup depend on the backup format:

Portable format Legacy format

  • -portable: (Required) Specifies the portable backup format
  • -host: InfluxDB bind address (Only required if restore a backup to a remote InfluxDB host)
  • -db: Database name (If no database name is specified, the command restores all databases)
  • -newdb: New database name (Required when restoring a database that already exists)
  • -rp: Retention policy name (If no retention policy is specified, the command restores all retention policies)
  • -newrp: New retention policy name (Required when restoring a retention policy that already exists)
  • -shard: Shard ID (If no shard ID is specified, the command backs up all shards. Requires a retention policy.)
  • (Required) Backup directory path

Restore examples

Restore all databases

influxd restore -portable /path/to/backup-directory

Restore all data to a remote InfluxDB instance

influxd restore -portable \
  -host 203.0.113.0:8088 \
  /path/to/backup-directory

Restore a specific database

influxd restore -portable \
  -db example-db \
  /path/to/backup-directory

Restore data to a database that already exists

influxd restore -portable \
  -db example-db \
  -newdb example-new-db \
  /path/to/backup-directory

Restore a specific retention policy

influxd backup -portable \
  -db example-db \
  -rp example-retention-policy \
  /path/to/backup-directory

Restore data to a retention policy that already exists

influxd restore -portable \
  -db example-db \
  -rp example-rp \
  -newrp example-new-rp \
  /path/to/backup-directory

Restore a specific shard

To restore a specific shard, you must specify a database and retention policy. To view shard IDs, use the SHOW SHARDS InfluxQL statement.

influxd backup -portable \
  -db example-db \
  -rp example-rp \
  -shard 123 \
  /path/to/backup-directory

Legacy backups can be restored to a running (online) or stopped (offline) InfluxDB instance.

Online legacy restore

  • -online: (Required) Specifies that the target InfluxDB instance is running
  • -host: InfluxDB bind address (Only required if restoring a backup from a remote InfluxDB host)
  • -db: (Required) Database name
  • -newdb: New database name (Required when restoring a database that already exists)
  • -rp: Retention policy name (If no retention policy is specified, the command backs up all retention policies)
  • -newrp: New retention policy name (Required when restoring a retention policy that already exists)
  • -shard: Shard ID (If no shard ID is specified, the command restores all shards. Requires a retention policy.)
  • (Required) Backup destination directory path

Online legacy restore examples

Restore a database
influxd restore -online \
  -db example-db \
  /path/to/backup-directory
Restore a database to a remote InfluxDB instance
influxd restore -online \
  -db example-db \
  -host 203.0.113.0:8088 \
  /path/to/backup-directory
Restore data to a database that already exists
influxd restore -online \
  -db example-db \
  -newdb example-new-db \
  /path/to/backup-directory
Restore a specific retention policy
influxd backup -online \
  -db example-db \
  -rp example-retention-policy \
  /path/to/backup-directory
Restore data to a retention policy that already exists
influxd restore -online \
  -db example-db \
  -rp example-rp \
  -newrp example-new-rp \
  /path/to/backup-directory
Restore a specific shard

To restore a specific shard, you must specify a database and retention policy. To view shard IDs, use the SHOW SHARDS InfluxQL statement.

influxd backup -online \
  -db example-db \
  -rp example-rp \
  -shard 123 \
  /path/to/backup-directory

Offline legacy restore

Offline restores overwrite data

Offline restores are destructive and will overwrite all data in the destination database.

Must be done on the same machine as InfluxDB

Offline restores must be done from the machine where InfluxDB is running. They cannot be done remotely unless you console into the machine InfluxDB is running on and execute the restore process there.

  • -db: (Required) Database name
  • -newdb: New database name (Required when restoring a database that already exists)
  • -rp: Retention policy name (If no retention policy is specified, the command backs up all retention policies)
  • -newrp: New retention policy name (Required when restoring a retention policy that already exists)
  • -datadir: (Required) Location of destination data directory on disk (See InfluxDB file system layout)
  • -metadir: (Required) Location of destination meta directory on disk (See InfluxDB file system layout)
  • -shard: Shard ID (If no shard ID is specified, the command backs up all shards. Requires a retention policy.)
  • (Required) Backup destination directory path

Offline legacy restore examples

Restore a database
influxd restore \
  -db example-db \
  -datadir /path/to/data-directory \
  -metadir /path/to/meta-directory \
  /path/to/backup-directory
Restore a specific retention policy
influxd backup \
  -db example-db \
  -rp example-retention-policy \
  -datadir /path/to/data-directory \
  -metadir /path/to/meta-directory \
  /path/to/backup-directory
Restore a specific shard

To restore a specific shard, you must specify a database and retention policy. To view shard IDs, use the SHOW SHARDS InfluxQL statement.

influxd backup \
  -db example-db \
  -rp example-rp \
  -shard 123 \
  -datadir /path/to/data-directory \
  -metadir /path/to/meta-directory \
  /path/to/backup-directory

Restore data to an existing database

While backups can’t be restored directly to an existing database (except for offline legacy restores), you can do the following to restore data to an existing database:

  1. Restore a backup to a temporary database.

    Portable format Legacy format

    influxd restore -portable \
  -db example-db \
  -newdb example-tmp-db \
  /path/to/backup-directory/

    influxd restore \
  -db example-db \
  -newdb example-tmp-db \
  /path/to/backup-directory/

  2. Use InfluxQL or Flux to query data from the temporary database and write it back to the existing database.

    InfluxQL Flux

    -- Repeat for each retention policy in the temporary database
SELECT *
INTO "example-db".autogen.:MEASUREMENT
FROM "example-tmp-db".autogen./.*/ GROUP BY *

    // Repeat for each retention policy in the temporary database
from(bucket: "example-tmp-db/autogen")
    |> range(start: 0)
    |> to(bucket: "example-db/autogen")

    InfluxDB handles duplicate points added by this query as it normally does. For more information, see How does InfluxDB handle duplicate points?

  3. Use InfluxQL to delete the temporary database.

    DROP DATABASE "example-tmp-db"

Configure backup and restore services

InfluxDB OSS 1.11 backup and restore utilities execute over a TCP connection. The default IP and port used for backup and restore remote procedure calls (RPCs) are 127.0.0.1:8088.

To customize the TCP IP and port the backup and restore services use, uncomment and update the bind-address configuration setting at the root level of your InfluxDB configuration file (influxdb.conf).

# Bind address to use for the RPC service for backup and restore.
bind-address = "127.0.0.1:8088"

Was this page helpful?

Thank you for your feedback!

© 2024 InfluxData, Inc.

What is your InfluxDB OSS URL?

Customize your InfluxDB OSS URL and we’ll update code examples for you.

Default
Custom

For more information, see InfluxDB OSS URLs.

Thank you for your feedback!

Let us know what we can do better:

Thank you!

No thanks

The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Read more

InfluxDB v3 enhancements and InfluxDB Clustered is now generally available

New capabilities, including faster query performance and management tooling advance the InfluxDB v3 product line. InfluxDB Clustered is now generally available.

InfluxDB v3 performance and features

The InfluxDB v3 product line has seen significant enhancements in query performance and has made new management tooling available. These enhancements include an operational dashboard to monitor the health of your InfluxDB cluster, single sign-on (SSO) support in InfluxDB Cloud Dedicated, and new management APIs for tokens and databases.

Learn about the new v3 enhancements

InfluxDB Clustered general availability

InfluxDB Clustered is now generally available and gives you the power of InfluxDB v3 in your self-managed stack.

Talk to us about InfluxDB Clustered