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.8 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
- Backup formats
- Backup and restore requirements
- Important notes
- Back up data
- Restore data
- Configure backup and restore services
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.8 and InfluxDB Enterprise.
Backup functionality | Legacy format | Portable 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.8 | ||
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 and restore it to an InfluxDB 1.8.10 instance.
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
: (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
- Back up all data from a remote InfluxDB instance
- Back up a specific time range
- Back up data from a specific time to now
- Back up a specific database
- Back up a specific retention policy
- Back up a specific shard
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
- Back up a database from a remote InfluxDB instance
- Back up a specific time range
- Back up data from a specific time to now
- Back up a specific retention policy
- Back up a specific shard
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.8 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
: (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
- Restore all data to a remote InfluxDB instance
- Restore a specific database
- Restore data from a database that already exists
- Restore a specific retention policy
- Restore data from a retention policy that already exists
- Restore a specific shard
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
- Restore a database to a remote InfluxDB instance
- Restore data to a database that already exists
- Restore a specific retention policy
- Restore data to a retention policy that already exists
- Restore a specific shard
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:
-
Restore a backup to a temporary database.
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/
-
Use InfluxQL or Flux to query data from the temporary database and write it back to the existing database.
-- 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?
-
Use InfluxQL to delete the temporary database.
DROP DATABASE "example-tmp-db"
Configure backup and restore services
InfluxDB OSS 1.8 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!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.