Backing Up Your TDengine Database

TDengine offers a variety of backup and restore methods tailored to different scenarios, from lightweight exports for quick snapshots to full-scale disaster recovery solutions. In this article, we’ll walk you through the four main approaches, comparing their strengths, limitations, and best-fit use cases to help you choose the right strategy for your environment.

taosdump

taosdump is the preferred data backup tool for TDengine OSS, though it is also supported in TDengine Enterprise. Its key features include multi-threaded processing and the Apache Avro format for backup files. Avro is a widely adopted data exchange format among big data platforms, making it convenient to share data with other systems. taosdump supports cross-platform remote server connections for backup and restore operations and is compatible with multiple connection protocols such as WebSocket.

Pros and Cons

• Pros: Easy to use and supported in the TDengine OSS; uses the open Apache Avro format for exports.
• Cons: Relatively basic feature set that may not cover more complex backup scenarios.

Perform Backup with taosdump

• Full backup (including system databases):

  taosdump -A -o /data/backup

  -A indicates a full backup of all databases, and -o specifies the backup directory.

• Back up a specified database or table:

  taosdump -D db01 -o /data/backup/db01

  -D specifies the database name.

  This method can back up multiple or all tables in a database but cannot back up multiple databases at once.

• Back up a specified time range:

  taosdump -S '2024-01-01T00:00:00+0800' -E '2024-01-02T00:00:00+0800' -D db01 -o /data/backup/time_range

  -S and -E specify the start and end times, respectively.

• Specify the number of threads:

  taosdump -T 32 -A -o /data/backup

  -T specifies the number of backup threads. The default is 8.
  

• Back up metadata only:

  taosdump -s -D db01 -o /data/backup/meta

  -s indicates that only metadata will be backed up.

Restore Data with taosdump

• Full restore:

  taosdump -i /data/backup

  -i specifies the backup directory and restores all data.

• Restore to a new database:

  taosdump -i /data/backup -W "db01=new_db01"

  This command restores the original database db01 as new_db01.

• Restore with specified number of threads:

  taosdump -i /data/backup -T 16

  -T specifies the number of threads to use during restoration.

• Restore a Specific Database

  After performing a full backup, open the backup director and delete the directories of databases you do not wish to restore. Keep only the directories for the desired database. Then run:

  taosdump -i /data/backup

  Only the remaining databases will be restored.

• Restore metadata:

  If the target database or table already exists, the metadata will not be overwritten—only the existing structure will be retained.

Backup/Restore with Table Structure Changes:

• Before TDengine 3.3.6.0: If the target database or table has structural changes (e.g., added or removed columns), a direct restore will fail. You must use a workaround: import the old backup into a new temporary database → export a new backup from the temporary database → import the new backup into the target database.
• From TDengine 3.3.6.0 onward: Supports adding or removing columns (changing column types with the same name is still not supported). Newly added columns during restore will be filled with null values.

taosX

taosX is an enterprise-only data pipeline tool for TDengine, designed as a zero-code data integration platform. Its core functionalities include data ingestion, synchronization, backup, restore, and migration. It supports asynchronous data replication across clusters or instances and can serve as a bridge between TDengine and third-party data sources such as relational databases and message queues.

taosX supports incremental backup and restore (with graphical interface available in version 3.3.x and above), as well as resume-from-breakpoint functionality. Backup files can be exported in CSV and Parquet (columnar storage) formats.

Pros and Cons

• Pros: Comprehensive functionality (supports incremental backup, resume from breakpoint, etc.), high performance, and multiple export formats (CSV/Parquet columnar storage).
• Cons: Not available in TDengine OSS; higher complexity in usage.

Back Up Data with taosX

1. To configure backup tasks, log in to TDengine Explorer and click System Management > Backup.

2. Click Create New Backup.

   

3. Configure parameters such as backup frequency (daily / every 7 days / every 30 days), target database (must have wal_retention_period > 0), and backup directory (e.g., /root/data_backup).

4. Click Confirm to start the task. The interface supports monitoring task status, including data volume and latency.

Restore Data with taosX

1. Log in to TDengine Explorer and click System Management > Backup.

2. Go to the Backup Files list and select the backup point you want to restore.

3. Click the Data Restore button, choose the target database, and complete the restore process.

TDengine CLI

taos is the built-in CLI provided in TDengine OSS and Enterprise. Its backup and restore functions are primarily based on CSV files, making it suitable for small-scale, temporary backup scenarios. While easy to use, it has limited performance and should be used based on specific needs.

Pros and Cons

• Pros: Simple to operate; allows flexible backup of any query result, such as specific subtables, selected columns, or custom queries.
• Cons: Supports only single-threaded operations, making it relatively slow—best suited for small-scale, temporary backups.

Back Up Data with TDengine CLI

Use the redirection symbol >> in the TDengine CLI to export query results as CSV files. Supported scenarios include:

• Full Subtable Backup: Export all data from a specific subtable.

  SELECT * FROM child_table >> /path/to/backup.csv

• Query Result Backup: Export data that meets specific query conditions (e.g., time range, filters).

  SELECT * FROM sensor_data WHERE ts BETWEEN '2025-06-01' AND '2025-06-30' >> /path/to/query_backup.csv

• Partial Column Backup: Export only selected columns from a table (useful in scenarios with significant schema changes).

  SELECT id, value FROM sensor_data >> /path/to/partial_columns_backup.csv

Restore Data with TDengine CLI

Before restoring data, make sure to delete the first header row from the CSV file to avoid importing column names as data. Then, choose the appropriate syntax based on the data you backed up:

• Full Subtable Restore: Directly import the CSV data into the target subtable.

  INSERT INTO child_table FILE /path/to/backup.csv;

• Partial Column Restore: You must explicitly specify the target table’s column names and ensure the column order in the CSV file matches.

  INSERT INTO target_table (id, value) FILE /path/to/partial_columns_backup.csv;

Manually Back Up Data Files

You can manually back up the TDengine data directory (specified by the dataDir parameter). This is a full snapshot approach commonly used for disaster recovery scenarios, such as when TDengine cannot start, similar to creating a database image.

Pros and Cons

• Pros: Does not rely on the TDengine service; fast backup speed.
• Cons: The TDengine version during recovery must match the version at the time of backup. All data (including metadata) can only be restored as a complete snapshot from the backup point.

Back Up Data Files

Note the following before proceeding:

• It is recommended to use automated scripts for scheduled backups to improve reliability.
• It is not necessary to back up write-ahead log (WAL) files.
• In multi-replica clusters, it is only necessary to back up the leader replica.
• In multi-node clusters, ensure all nodes are backed up at the same point in time to minimize data inconsistency between nodes.
• If possible, stop TDengine before backing up data files. In the event that this is truly impossible, run the command FLUSH DATABASE <dbname> to force in-memory data to be written to disk before performing the backup.

Then copy the TDengine data directory to your backup medium.

Restore a Data Directory

Note the following before proceeding:

1. Before you restore a data directory, the TDengine service must be stopped.
2. The TDengine version must match the one used at the time of backup.
3. In a multi-node cluster, all nodes must be restored using the same backup data. Restoring only some of the nodes may result in startup failure or unpredictable behavior.

To restore data, perform one of the following:

• Modify the dataDir parameter to point to the backup directory
• Delete the original data directory and replacing it entirely with the backup directory. Do not mix old and new files.

In a multi-replica scenario, ensure that you also copy the leader’s backup directory to all nodes.

Conclusion

TDengine offers four distinct backup and restore methods, each with its own strengths and suitable scenarios.

• taosdump: The main option for TDengine OSS, suitable for small to medium datasets with open-format backups.
• taosX: The main option for Enterprise users, supporting complex migrations and incremental operations.
• TDengine CLI: Best for lightweight, temporary backups and flexible for exporting small amounts of data.
• Database File Backup: Suitable for disaster recovery, offline and full-coverage, but requires version consistency.

Enterprises should choose the right method based on data scale, available resources, and use case (disaster recovery, migration, temporary backups, etc.) to ensure data safety and business continuity.