Project: TiDB (App Definition and Development / Database)
File: user-guide.md

Dumpling is a tool and a Go library for creating SQL dump (CSV/SQL format) from a MySQL-compatible database. It is intended to replace `mysqldump` and `mydumper` when targeting TiDB; as a result, its basic usage is similar to that of Mydumper. The following table lists the major parameters of Dumpling. | Parameter | Description | | --| | | -B or --database | Dump the specified databases. | | -T or --tables-list | Dump the specified tables | | -f or --filter | Dump only the tables matching the patterns. See for syntax. | | --case-sensitive | whether the filter should be case-sensitive, default false(insensitive) | | -h or --host | Host to connect to. (default: `127.0.0.1`) | | -t or --threads | Number of threads for concurrent backup. | | -r or --rows | Split table into multiple files by number of rows. This allows Dumpling to generate multiple files concurrently. (default: unlimited) | | --loglevel | Log level. {debug, info, warn, error, dpanic, panic, fatal}. (default: `info`) | | -d or --no-data | Don't dump data, for schema-only case. | | --no-header | Dump table CSV without header. | | -W or --no-views | Don't dump views. (default: `true`) | | -m or --no-schemas | Don't dump schemas, dump data only. | | -s or --statement-size | Control the size of Insert Statement. Unit: byte. | | -F or --filesize | The approximate size of the output file. The unit should be explicitly provided (such as `128B`, `64KiB`, `32MiB`, `1.5GiB`) | | --filetype| The type of dump file. (sql/csv, default "sql") | | -o or --output | Output directory. The default value is based on time. | | --output-filename-template | Output file name templates. See below for details. | | -S or --sql | Dump data with given sql. This argument doesn't support concurrent dump | | --consistency | Which consistency control to use (default `auto`):<br>`flush`: Use FTWRL (flush tables with read lock)<br>`snapshot`: use a snapshot at a given timestamp<br>`lock`: execute lock tables read for all tables that need to be locked <br>`none`: dump without

It cannot guarantee consistency <br>`auto`: `flush` on MySQL, `snapshot` on TiDB | | --snapshot | Snapshot position. Valid only when consistency=snapshot. | | --where | Specify the dump range by `where` condition. Dump only the selected records. | | -p or --password | User password. | | -P or --port | TCP/IP port to connect to. (default: `4000`) | | -u or --user | Username with privileges to run the dump. (default "root") | To see more detailed usage, run the flag `-h` or `--help`. Download the nightly version of Dumpling . The `--output-filename-template` argument specifies how all files are named, before including the file extensions. It accepts strings in the . The following fields are available to the template: `.DB` database name `.Table` table name or object name `.Index` when a table is split into multiple files, this is the 0-based sequence number indicating which part we are dumping The database and table names may contain special characters like `/` not acceptable in the file system. Thus, Dumpling also provided a function `fn` to percent-escape these special characters: U+0000 to U+001F (control characters) `/`, `\`, `<`, `>`, `:`, `"`, ``, `?` (invalid Windows path characters) `.` (database/table name separator) `-`, if appeared as part of `-schema` For instance, using `--output-filename-template '{{fn .Table}}.{{printf "%09d" .Index}}'`, Dumpling will write the table `"db"."tbl:normal"` into files named like `tbl%3Anormal.000000000.sql`, `tbl%3Anormal.000000001.sql`, etc. Besides the data files, you could also define named templates to replace the file name of the schema files. The default are configuration is: | Name | Content | ||| | data | `{{fn .DB}}.{{fn .Table}}.{{.Index}}` | | schema | `{{fn .DB}}-schema-create` | | table | `{{fn .DB}}.{{fn .Table}}-schema` | | event | `{{fn .DB}}.{{fn .Table}}-schema-post` | | function | `{{fn .DB}}.{{fn .Table}}-schema-post` | | procedure | `{{fn .DB}}.{{fn .Table}}-schema-post` | | sequence | `{{fn .DB}}.{{fn .Table}}-schema-sequence` | | trigger | `{{fn .DB}}.{{fn .Table}}-schema-triggers` | | view | `{{fn .DB}}.{{fn .Table}}-schema-view` | For instance, using `--output-filename-template '{{define "table"}}{{fn .Table}}.$schema{{end}}{{define "data"}}{{fn .Table}}.{{printf "%09d" .Index}}{{end}}'`, Dumpling will write the schema of the table `"db"."tbl:normal"` into the file `tbl%3Anormal.$schema.sql`, and data into the files like `tbl%3Anormal.000000000.sql`.