taosdump Reference

taosdump is a high-performance backup and restore tool provided by TDengine TSDB. It stores backup data in a highly compressed columnar format and supports full backup, database-level backup, table-level backup, time-range backup, metadata-only backup, and resumable execution for a wide range of data protection and migration scenarios.

taosdump New Upgraded Version

Starting from v3.4.2.0, taosdump has been fully upgraded with higher performance, smaller backup data size, and more practical features. The new version supports importing avro format data generated by the old version, but no longer supports generating avro format backup data.

Getting the Tool

taosdump is included in both the server and client installation packages of TDengine TSDB. For installation details, see TDengine TSDB Installation.

Running taosdump

taosdump runs on Windows, macOS, and Linux. It must be run from a command-line terminal, and you must specify either backup mode with -o or restore mode with -i.

tip

Before running taosdump, make sure that the target TDengine TSDB cluster is up and running correctly.

Backup Example

taosdump -h my-server -D test -o /root/backup/

This command backs up the test database from the TDengine service running on host my-server to the /root/backup/ directory.

taosdump -h my-server -o /root/backup/

If -D is not specified, taosdump backs up all user databases by default, excluding the system databases information_schema and performance_schema.

Restore Example

taosdump -h my-server -i /root/backup/

This command restores the backup data under /root/backup/ to the TDengine service running on host my-server.

taosdump -h my-server -D test -i /root/backup/

This command restores the backup data under /root/backup/ to the TDengine service running on host my-server, and restores only the test database.

Command-Line Parameters

Usage: taosdump [OPTION...] dbname [tbname ...] -o outpath
  or:  taosdump [OPTION...] -o outpath
  or:  taosdump [OPTION...] -i inpath
  or:  taosdump [OPTION...] --databases db1,db2,...

Command-Line Parameter	Description
-h, --host=HOST	FQDN or IP address of the TDengine server to connect to. Default: localhost
-P, --port=PORT	TDengine server port. Default: 6030
-c, --config-dir=CONFIG_DIR	Directory containing the taos.cfg configuration file. If not specified, the default path is used
-u, --user=USER	Username for the connection. Default: root
-p, --password	Prompt for the connection password. You can also specify the password on the command line with -pPASSWORD or --password=PASSWORD. Default: taosdata
-o, --outpath=OUTPATH	Output directory for backup files. Default: ./output
-i, --inpath=INPATH	Input path containing backup files for restore operations
-D, --databases=DATABASES	Databases to back up or restore. Separate multiple databases with commas. If omitted, all user databases are processed
-F, --format=FORMAT	Backup storage format. Supported values: binary (default) or parquet
-M, --content=CONTENT	Content to back up or restore. Effective for both backup and restore. Supported values: basic (default) — basic data: super tables, child tables, normal tables, tags and time-series data; ext-meta — extended metadata: virtual tables, streams and topics; all — basic + ext-meta. See Content Selection
-s, --schemaonly	Flag. Back up only table schemas and tag data, without time-series data
-S, --start-time=START_TIME	Start time for backup data. Supports millisecond timestamps or ISO8601 format such as 2017-10-01T00:00:00.000+0800. Effective only for backup
-E, --end-time=END_TIME	End time for backup data. Supports millisecond timestamps or ISO8601 format. Effective only for backup
-T, --thread-num=THREAD_NUM	Number of parallel threads for data backup or restore. Default: 8
-m, --tag-thread-num=THREAD_NUM	Number of parallel threads for tag-data backup. Default: 2
-B, --data-batch=DATA_BATCH	Number of rows written in each STMT batch during restore. For STMT2 (default), the valid range is [1, 16384] and the default is 10000. For STMT1, the valid range is [1, 100000] and the default is 60000. Effective only for restore
-v, --stmt-version=VER	STMT API version used during restore: 2 (default, TAOS_STMT2, faster, requires TDengine v3.3+) or 1 (compatible with the legacy TAOS_STMT API). Effective only for restore
-W, --rename=RENAME-LIST	Rename databases during restore. Format: "db1->newdb1|db2->newdb2", which renames db1 to newdb1 and db2 to newdb2. Effective only for restore
-C, --checkpoint	Flag parameter for resumable transfer, disabled by default. When specified, it enables checkpoint mode, skipping already backed-up tables or previously restored files. Effective for both backup and restore operations. Suitable for large-scale backup/restore scenarios
-k, --retry-count=VALUE	Number of retries after a connection or query failure. Default: 3
-z, --retry-sleep-ms=VALUE	Wait time between retries in milliseconds. Default: 1000
-X, --dsn=DSN	DSN for connecting to a cloud service, for example https://host?token=<TOKEN>. You can also set it through the TDENGINE_CLOUD_DSN environment variable. The command-line parameter takes precedence
-Z, --driver=DRIVER	Connection driver. Supported values: Native (port 6030, faster, 0 also accepted, default) or WebSocket (port 6041, no client driver install needed, better compatibility, 1 also accepted). When a DSN is set, the default automatically switches to WebSocket
-g, --debug	Flag. Enable debug output. Disabled by default
-V, --version	Show version information and exit
--help	Show help information and exit

Content Selection

Starting from v3.4.2.5, taosdump supports selecting the content to back up or restore with the -M, --content parameter.

Value	Content	Backup files
basic (default)	Super tables, child tables, normal tables, tags and time-series data	db.sql, stb.sql, {stbname}.csv, tags/, ntb.sql, {stbname}_data{N}/, _ntb_data{N}/
ext-meta	Virtual tables, streams, topics	vtb.sql, vtags/, stream.sql, topic.sql
all	basic + ext-meta	All of the above

Why the Split

Each column of a virtual table can be sourced from any table in any database (for example, a virtual table in db2 referencing a physical table in db1). If the restore processed one database completely at a time, CREATE VTABLE would fail whenever the database holding the virtual tables was restored before the database it references. The restore therefore runs in two stages:

1. Stage 1: create the physical tables and import the time-series data for all databases (basic)
2. Stage 2: once every database is in place, apply the virtual table, stream and topic DDL for all databases (ext-meta)

Cross-database references then resolve correctly no matter what order the databases are listed in.

Typical Usage

# Back up everything (basic data + extended metadata)
taosdump --content=all -D db1,db2 -o /root/backup/

# Back up basic data only (the default, same as omitting --content)
taosdump -D db1,db2 -o /root/backup/

# Restore: import the basic data first, then the extended metadata
taosdump --content=basic   -i /root/backup/
taosdump --content=ext-meta -i /root/backup/

Splitting the restore means a failure on an individual stream, virtual table or topic does not affect the basic data that has already been imported: after fixing the problem you only rerun --content=ext-meta instead of re-importing all the time-series data.

note

• When restoring with --content=ext-meta, a missing target database is created by executing db.sql first, which is why ext-meta backups also contain db.sql.
• The DDL of a virtual super table is stored in stb.sql and belongs to the basic content. It carries no cross-database reference of its own (the column-to-source mapping lives on the virtual child / virtual normal tables), so a basic backup contains a virtual super table structure without its virtual child tables.
• Backup directories in the old avro format contain no vtb.sql / stream.sql / topic.sql; their virtual tables are handled inside stage 1 and the ext-meta stage skips them with a warning.
• When renaming databases with -W/--rename, virtual table, stream and topic database references are rewritten as follows (verified empirically). -W can carry several old-db → new-db pairs at once, and the restore applies every configured pair to the DDL text, not just the pair for the database currently being restored — so a virtual table's cross-database source is rewritten too, as long as that source database is also part of the -W mapping.
  • Virtual table columns, whether sourced from their own database or a different one: rewritten to the new name whenever the referenced database appears in the -W mapping. A referenced database that is not being renamed is left unchanged, so the virtual table keeps pointing at it under its original name.
  • Streams: all database references in the DDL (source and target databases) and the stream name's database prefix are rewritten under the same rule.
  • Topics: topics are cluster-level objects, so the topic name itself is not affected by -W/--rename, but database references inside its query are rewritten. Restoring into the same cluster hits "already exists" for the topic name, which is treated as success.
• Topic and stream DDL is read from the sql column of information_schema.ins_topics / ins_streams. That column is capped at 2048 bytes, so longer DDL is truncated by the server.

Backup File Structure

Under the backup output directory, each database has its own subdirectory containing the following content:

{outpath}/
└── {dbname}/
    ├── db.sql                        # CREATE DATABASE SQL
    ├── stb.sql                       # All super table DDL, one per line (incl. virtual super tables)
    ├── ntb.sql                       # All normal table DDL
    ├── {stbname}.csv                 # Super table column/tag schema (DESCRIBE output)
    ├── tags/
    │   └── {stbname}_data{N}.{ext}   # Child table tag data
    ├── {stbname}_data{dirIndex}/
    │   └── {ctbname}.{ext}           # Child table time-series data files
    ├── _ntb_data{dirIndex}/
    │   └── {ntbname}.{ext}           # Normal table time-series data files
    ├── vtb.sql                       # Virtual table DDL (ext-meta)
    ├── vtags/
    │   └── {vstbname}_data{N}.{ext}  # Virtual child table tag data (ext-meta)
    ├── stream.sql                    # Stream DDL (ext-meta)
    ├── topic.sql                     # Topic DDL (ext-meta)
    └── backup_complete.flag          # Backup completion marker

The file extension is .dat for binary format and .par for parquet format. vtb.sql, vtags/, stream.sql and topic.sql are produced only when --content is ext-meta or all.

Output Metrics

Startup Summary

At the start of backup or restore, taosdump prints a summary of the current runtime parameters, for example:

===========================================================================
  taosdump - BACKUP
===========================================================================
  Connect Mode : Native
  Server       : my-server:6030
  User         : root
  Output Path  : /root/backup/
  Content      : basic
  Databases    : test
  Data Threads : 8
  Tag Threads  : 2
  Format       : binary
  Schema Only  : no
  Time Range   : ALL
  Check Point  : no
===========================================================================

Real-Time Progress

During execution, taosdump continuously prints progress information, including the current database, super table, completed child tables, and estimated remaining time:

[DB 1/2: test] [STB 3/10: meters] [CTB 1500/5000 (30.0%)] elapsed: 12s, eta: 28s

Final Summary

After backup or restore completes, taosdump prints the final statistics summary:

===========================================================================
  Result       : SUCCESS (BACKUP)
---------------------------------------------------------------------------
  Databases    : total=1, success=1, failed=0
  Super Tables : 10
  Child Tables : 5000 (data exported)
  Normal Tables: 2
  Total Rows   : 50000000
  Ext Meta     : vtable=8, stream=2, topic=1
  Elapsed      : 45 s
===========================================================================

Field descriptions:

• Result: SUCCESS/FAILED/CANCELLED BY USER, with the action (BACKUP or RESTORE) in parentheses.
• Databases: Total number of processed databases, and the numbers of successful and failed databases.
• Super Tables: Number of processed super tables.
• Child Tables: Number of child tables whose data was exported or restored.
• Normal Tables: Number of processed normal tables.
• Total Rows: Total number of backed-up or restored rows.
• Ext Meta: Number of processed virtual tables, streams and topics. Printed only when --content is ext-meta or all.
• Elapsed: Total elapsed time in seconds.

tip

If the number of failed items is not zero, add -g to enable debug output for detailed errors, or check the TDengine server logs for troubleshooting.

Log Files

• Backup: The log file is named backup.log and stored in the root directory of the backup folder.
• Restore: The log file is named restore.log and saved in the current directory.

Common Usage Scenarios

Back Up Data

Back Up All Databases

taosdump -h my-server -o /root/backup/

Back up all user databases, automatically excluding information_schema and performance_schema, to the /root/backup/ directory.

Back Up Specific Databases

taosdump -h my-server -D db1,db2 -o /root/backup/

Back up only the db1 and db2 databases.

Back Up Specific Tables

taosdump -h my-server -o /root/backup/ test meters t1 t2

Back up the super table meters and the normal tables t1 and t2 in the test database. The first positional argument is the database name, and the remaining positional arguments are one or more super table, child table, or normal table names in that database, separated by spaces. Note: only one database name can be specified; multiple databases are not supported.

Back Up by Time Range

taosdump -h my-server -D test -S "2024-01-01T00:00:00.000+0800" -E "2024-12-31T23:59:59.999+0800" -o /root/backup/

Back up only data from the test database for the full year of 2024.

Back Up Metadata Only

taosdump -h my-server -D test -s -o /root/backup/

Back up only the schema and tag information of the test database, without time-series data. This is suitable for fast schema migration.

Back Up Virtual Tables, Streams and Topics

taosdump -h my-server -D test --content=all -o /root/backup/

The default basic mode backs up basic data only. Use --content=all to include virtual tables, streams and topics, or --content=ext-meta to back up only those three object types. See Content Selection.

Back Up in Parquet Format

taosdump -h my-server -D test -F parquet -o /root/backup/

Export the test database in Parquet format for integration with big-data ecosystems such as Spark, Hive, and DuckDB.

Resumable Backup

Resumable execution is disabled by default and must be explicitly enabled with -C. If a backup is interrupted, rerun the same command with -C and taosdump will automatically skip databases, super tables, and child tables that were already completed, then continue with the unfinished portion.

Note: Resumable execution is only effective for data backup. Metadata backup does not support resumable execution because it is fast enough.

# First backup attempt (interrupted for some reason)
taosdump -h my-server -D test -o /root/backup/

# Run again with resumable execution enabled
taosdump -h my-server -D test -o /root/backup/ -C

taosdump always writes checkpoint files to the output directory. When rerun with -C, it reads the checkpoint files, skips completed items, and resumes from the interruption point.

tip

• If backup files already exist under the directory specified by -o, taosdump overwrites files with the same names when resumable execution is not enabled. Use an empty directory for a fresh full backup.
• If the backup volume is large, consider splitting the backup with -S and -E, or enabling resumable execution with -C.

Restore Data

Restore to the Original Databases

taosdump -h my-server -i /root/backup/

Restore the backup data under /root/backup/ to my-server. During restore, taosdump automatically creates the corresponding databases, super tables, and child tables. If a table already exists, table creation is skipped.

Rename Databases During Restore

taosdump -h my-server -i /root/backup/ -W "db1->db1_restored|db2->db2_restored"

Restore db1 in the backup as db1_restored and db2 as db2_restored. This is useful for testing, validation, or parallel environments.

Restore Specific Tables

taosdump -h my-server -i /root/backup/ test t1

Restore only the normal table t1 in the test database. The first positional argument is the database name, and the remaining positional arguments are one or more super table, child table, or normal table names in that database, separated by spaces.

Resumable Restore

taosdump -h my-server -i /root/backup/ -C

Restore also supports resumable execution. When rerun, it automatically skips data files that have already been restored successfully.

Restore Virtual Tables, Streams and Topics in Two Stages

# Step 1: restore physical tables and time-series data
taosdump -h my-server --content=basic -i /root/backup/

# Step 2: restore virtual tables, streams and topics
taosdump -h my-server --content=ext-meta -i /root/backup/

This is equivalent to a single --content=all restore but runs the extended metadata separately. It suits the case where an individual object in the extended metadata fails to import: the basic data is already fully imported and unaffected, and after fixing the problem only step 2 needs to be rerun.

Restore Cross-Database Virtual Tables

Columns of a virtual table can come from any database. During restore taosdump first completes the physical tables and data of all databases and only then applies the virtual table DDL, so the order of databases in -D does not matter:

# db2's virtual tables reference db1's physical tables; restoring db2 first still works
taosdump -h my-server --content=all -D db2,db1 -i /root/backup/

Restore When the Schema Has Changed

During restore, taosdump automatically detects schema differences between the backup and the current target server. If the target super table has a different column set than the backup, such as added or removed columns, taosdump calculates the common columns and performs partial-column writes automatically to ensure safe data restoration without manual intervention.

Adjust Batch Size to Avoid WAL Overflow

taosdump -h my-server -i /root/backup/ -B 2000

If you encounter a WAL size exceeds limit error during restore, reduce the number of rows written in each batch with -B.

Connect to TDengine Cloud

taosdump -i /root/backup/ -X "https://cloud-host?token=<TOKEN>"

Restore data through a DSN connection to TDengine Cloud. The driver automatically switches to WebSocket.

Enter the Connection Password

If no password option is specified, taosdump uses the default password taosdata. To enter a password, the recommended method is interactive input, which avoids exposing the password in shell history or process lists:

taosdump -u root -p -D test -o /root/backup/

You can also use the long option to enter the password interactively:

taosdump -u root --password -D test -o /root/backup/

To specify the password directly on the command line, the short option must be followed by the password without a space:

taosdump -u root -ptaosdata -D test -o /root/backup/

For the long option, use the equals-sign form:

taosdump -u root --password=taosdata -D test -o /root/backup/

The following forms are not supported. taosdump treats them as password option usage errors:

taosdump -u root -p taosdata -D test -o /root/backup/
taosdump -u root --password taosdata -D test -o /root/backup/

If you need to enter the password interactively and specify the database name as a positional argument, use -- to explicitly end option parsing, or use -D to specify the database. Using -D is recommended:

taosdump -u root -p -D test -o /root/backup/

New Version Behavior Changes

Performance Improvement

Tool	Backup	Restore
Old version (baseline)	1x	1x
New version	5x	3x

Backup Data Compression Improvement

Tool	Storage Format	Relative Size
Old version (baseline)	Row-store	100%
New version	Columnar	42%

New Features

• Resumable execution (checkpoint)
• Export to Parquet format
• STMT2 import
• Multi-threaded metadata backup
• Restore only specified databases
• Brand-new display interface
• Optimized backup/restore performance for multi-table low-frequency scenarios
• Content selection (-M/--content) to back up or restore only the basic data or only the extended metadata
• Backup and restore of topics
• The restore runs in two stages, fixing cross-database virtual table failures caused by database restore ordering

The new version supports the vast majority of old version command-line parameters (with a few exceptions).