Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 32.6Mb
PDF (A4) - 32.6Mb
PDF (RPM) - 30.6Mb
HTML Download (TGZ) - 7.8Mb
HTML Download (Zip) - 7.9Mb
HTML Download (RPM) - 6.7Mb
Man Pages (TGZ) - 143.2Kb
Man Pages (Zip) - 202.3Kb
Info (Gzip) - 3.0Mb
Info (Zip) - 3.0Mb

MySQL 8.0 Reference Manual  /  ...  /  mysqlpump — A Database Backup Program

Pre-General Availability Draft: 2017-06-23

4.5.6 mysqlpump — A Database Backup Program

The mysqlpump client utility performs logical backups, producing a set of SQL statements that can be executed to reproduce the original database object definitions and table data. It dumps one or more MySQL databases for backup or transfer to another SQL server.

mysqlpump features include:

  • Parallel processing of databases, and of objects within databases, to speed up the dump process

  • Better control over which databases and database objects (tables, stored programs, user accounts) to dump

  • Dumping of user accounts as account-management statements (CREATE USER, GRANT) rather than as inserts into the mysql system database

  • Capability of creating compressed output

  • Progress indicator (the values are estimates)

  • For dump file reloading, faster secondary index creation for InnoDB tables by adding indexes after rows are inserted


mysqlpump uses MySQL features introduced in MySQL 5.7, and thus assumes use with MySQL 5.7 or higher.

mysqlpump requires at least the SELECT privilege for dumped tables, SHOW VIEW for dumped views, TRIGGER for dumped triggers, and LOCK TABLES if the --single-transaction option is not used. The SELECT privilege on the mysql system database is required to dump user definitions. Certain options might require other privileges as noted in the option descriptions.

To reload a dump file, you must have the privileges required to execute the statements that it contains, such as the appropriate CREATE privileges for objects created by those statements.


A dump made using PowerShell on Windows with output redirection creates a file that has UTF-16 encoding:

shell> mysqlpump [options] > dump.sql

However, UTF-16 is not permitted as a connection character set (see Section 10.1.4, “Connection Character Sets and Collations”), so the dump file will not load correctly. To work around this issue, use the --result-file option, which creates the output in ASCII format:

shell> mysqlpump [options] --result-file=dump.sql

mysqlpump Invocation Syntax

By default, mysqlpump dumps all databases (with certain exceptions noted in mysqlpump Restrictions). To specify this behavior explicitly, use the --all-databases option:

shell> mysqlpump --all-databases

To dump a single database, or certain tables within that database, name the database on the command line, optionally followed by table names:

shell> mysqlpump db_name
shell> mysqlpump db_name tbl_name1 tbl_name2 ...

To treat all name arguments as database names, use the --databases option:

shell> mysqlpump --databases db_name1 db_name2 ...

By default, mysqlpump does not dump user account definitions, even if you dump the mysql system database that contains the grant tables. To dump grant table contents as logical definitions in the form of CREATE USER and GRANT statements, use the --users option and suppress all database dumping:

shell> mysqlpump --exclude-databases=% --users

In the preceding command, % is a wildcard that matches all database names for the --exclude-databases option.

mysqlpump supports several options for including or excluding databases, tables, stored programs, and user definitions. See mysqlpump Object Selection.

To reload a dump file, execute the statements that it contains. For example, use the mysql client:

shell> mysqlpump [options] > dump.sql
shell> mysql < dump.sql

The following discussion provides additional mysqlpump usage examples.

To see a list of the options mysqlpump supports, issue the command mysqlpump --help.

mysqlpump Option Summary

mysqlpump supports the following options, which can be specified on the command line or in the [mysqlpump] and [client] groups of an option file. For information about option files used by MySQL programs, see Section 4.2.6, “Using Option Files”.

Table 4.13 mysqlpump Options

--add-drop-databaseAdd DROP DATABASE statement before each CREATE DATABASE statement 
--add-drop-tableAdd DROP TABLE statement before each CREATE TABLE statement 
--add-drop-userAdd DROP USER statement before each CREATE USER statement 
--add-locksSurround each table dump with LOCK TABLES and UNLOCK TABLES statements 
--all-databasesDump all databases 
--bind-addressUse specified network interface to connect to MySQL Server 
--character-sets-dirDirectory where character sets are installed 
--column-statisticsWrite ANALYZE TABLE statements to generate statistics histograms8.0.2
--complete-insertUse complete INSERT statements that include column names 
--compressCompress all information sent between client and server 
--compress-outputOutput compression algorithm 
--databasesInterpret all name arguments as database names 
--debugWrite debugging log 
--debug-checkPrint debugging information when program exits 
--debug-infoPrint debugging information, memory, and CPU statistics when program exits 
--default-authAuthentication plugin to use 
--default-character-setSpecify default character set 
--default-parallelismDefault number of threads for parallel processing 
--defaults-extra-fileRead named option file in addition to usual option files 
--defaults-fileRead only named option file 
--defaults-group-suffixOption group suffix value 
--defer-table-indexesFor reloading, defer index creation until after loading table rows 
--eventsDump events from dumped databases 
--exclude-databasesDatabases to exclude from dump 
--exclude-eventsEvents to exclude from dump 
--exclude-routinesRoutines to exclude from dump 
--exclude-tablesTables to exclude from dump 
--exclude-triggersTriggers to exclude from dump 
--exclude-usersUsers to exclude from dump 
--extended-insertUse multiple-row INSERT syntax 
--helpDisplay help message and exit 
--hex-blobDump binary columns using hexadecimal notation 
--hostHost to connect to (IP address or hostname) 
--include-databasesDatabases to include in dump 
--include-eventsEvents to include in dump 
--include-routinesRoutines to include in dump 
--include-tablesTables to include in dump 
--include-triggersTriggers to include in dump 
--include-usersUsers to include in dump 
--insert-ignoreWrite INSERT IGNORE rather than INSERT statements 
--log-error-fileAppend warnings and errors to named file 
--login-pathRead login path options from .mylogin.cnf 
--max-allowed-packetMaximum packet length to send to or receive from server 
--net-buffer-lengthBuffer size for TCP/IP and socket communication 
--no-create-dbDo not write CREATE DATABASE statements 
--no-create-infoDo not write CREATE TABLE statements that re-create each dumped table 
--no-defaultsRead no option files 
--parallel-schemasSpecify schema-processing parallelism 
--passwordPassword to use when connecting to server 
--plugin-dirDirectory where plugins are installed 
--portTCP/IP port number to use for connection 
--print-defaultsPrint default options 
--protocolConnection protocol to use 
--replaceWrite REPLACE statements rather than INSERT statements 
--result-fileDirect output to a given file 
--routinesDump stored routines (procedures and functions) from dumped databases 
--secure-authDo not send passwords to server in old (pre-4.1) format 
--set-charsetAdd SET NAMES default_character_set to output 
--set-gtid-purgedWhether to add SET @@GLOBAL.GTID_PURGED to output8.0.1
--single-transactionDump tables within single transaction 
--skip-definerOmit DEFINER and SQL SECURITY clauses from view and stored program CREATE statements 
--skip-dump-rowsDo not dump table rows 
--socketFor connections to localhost, the Unix socket file to use 
--ssl-caPath of file that contains list of trusted SSL CAs 
--ssl-capathPath of directory that contains trusted SSL CA certificates in PEM format 
--ssl-certPath of file that contains X509 certificate in PEM format 
--ssl-cipherList of permitted ciphers to use for connection encryption 
--ssl-crlPath of file that contains certificate revocation lists 
--ssl-crlpathPath of directory that contains certificate revocation list files 
--ssl-keyPath of file that contains X509 key in PEM format 
--ssl-modeSecurity state of connection to server 
--tls-versionProtocols permitted for secure connections 
--triggersDump triggers for each dumped table 
--tz-utcAdd SET TIME_ZONE='+00:00' to dump file 
--userMySQL user name to use when connecting to server 
--usersDump user accounts 
--versionDisplay version information and exit 
--watch-progressDisplay progress indicator 

mysqlpump Option Descriptions

mysqlpump Object Selection

mysqlpump has a set of inclusion and exclusion options that enable filtering of several object types and provide flexible control over which objects to dump:

Any inclusion or exclusion option may be given multiple times. The effect is additive. Order of these options does not matter.

The value of each inclusion and exclusion option is a comma-separated list of names of the appropriate object type. For example:


Wildcard characters are permitted in the object names:

  • % matches any sequence of zero or more characters.

  • _ matches any single character.

For example, --include-tables=t%,__tmp matches all table names that begin with t and all five-character table names that end with tmp.

For users, a name specified without a host part is interpreted with an implied host of %. For example, u1 and u1@% are equivalent. This is the same equivalence that applies in MySQL generally (see Section 6.2.4, “Specifying Account Names”).

Inclusion and exclusion options interact as follows:

  • By default, with no inclusion or exclusion options, mysqlpump dumps all databases (with certain exceptions noted in mysqlpump Restrictions).

  • If inclusion options are given in the absence of exclusion options, only the objects named as included are dumped.

  • If exclusion options are given in the absence of inclusion options, all objects are dumped except those named as excluded.

  • If inclusion and exclusion options are given, all objects named as excluded and not named as included are not dumped. All other objects are dumped.

If multiple databases are being dumped, it is possible to name tables, triggers, and routines in a specific database by qualifying the object names with the database name. The following command dumps databases db1 and db2, but excludes tables db1.t1 and db2.t2:

shell> mysqlpump --include-databases=db1,db2 --exclude-tables=db1.t1,db2.t2

The following options provide alternative ways to specify which databases to dump:

mysqlpump Parallel Processing

mysqlpump can use parallelism to achieve concurrent processing. You can select concurrency between databases (to dump multiple databases simultaneously) and within databases (to dump multiple objects from a given database simultaneously).

By default, mysqlpump sets up one queue with two threads. You can create additional queues and control the number of threads assigned to each one, including the default queue:

  • --default-parallelism=N specifies the default number of threads used for each queue. In the absence of this option, N is 2.

    The default queue always uses the default number of threads. Additional queues use the default number of threads unless you specify otherwise.

  • --parallel-schemas=[N:]db_list sets up a processing queue for dumping the databases named in db_list and optionally specifies how many threads the queue uses. db_list is a comma-separated list of database names. If the option argument begins with N:, the queue uses N threads. Otherwise, the --default-parallelism option determines the number of queue threads.

    Multiple instances of the --parallel-schemas option create multiple queues.

    Names in the database list are permitted to contain the same % and _ wildcard characters supported for filtering options (see mysqlpump Object Selection).

mysqlpump uses the default queue for processing any databases not named explicitly with a --parallel-schemas option, and for dumping user definitions if command options select them.

In general, with multiple queues, mysqlpump uses parallelism between the sets of databases processed by the queues, to dump multiple databases simultaneously. For a queue that uses multiple threads, mysqlpump uses parallelism within databases, to dump multiple objects from a given database simultaneously. Exceptions can occur; for example, mysqlpump may block queues while it obtains from the server lists of objects in databases.

With parallelism enabled, it is possible for output from different databases to be interleaved. For example, INSERT statements from multiple tables dumped in parallel can be interleaved; the statements are not written in any particular order. This does not affect reloading because output statements qualify object names with database names or are preceded by USE statements as required.

The granularity for parallelism is a single database object. For example, a single table cannot be dumped in parallel using multiple threads.


shell> mysqlpump --parallel-schemas=db1,db2 --parallel-schemas=db3

mysqlpump sets up a queue to process db1 and db2, another queue to process db3, and a default queue to process all other databases. All queues use two threads.

shell> mysqlpump --parallel-schemas=db1,db2 --parallel-schemas=db3

This is the same as the previous example except that all queues use four threads.

shell> mysqlpump --parallel-schemas=5:db1,db2 --parallel-schemas=3:db3

The queue for db1 and db2 uses five threads, the queue for db3 uses three threads, and the default queue uses the default of two threads.

As a special case, with --default-parallelism=0 and no --parallel-schemas options, mysqlpump runs as a single-threaded process and creates no queues.

mysqlpump Restrictions

mysqlpump does not dump the performance_schema, ndbinfo, or sys schema by default. To dump any of these, name them explicitly on the command line. You can also name them with the --databases or --include-databases option.

mysqlpump does not dump the INFORMATION_SCHEMA schema.

mysqlpump dumps user accounts in logical form using CREATE USER and GRANT statements (for example, when you use the --include-users or --users option). For this reason, dumps of the mysql system database do not by default include the grant tables that contain user definitions: user, db, tables_priv, columns_priv, procs_priv, or proxies_priv. To dump any of the grant tables, name the mysql database followed by the table names:

shell> mysqlpump mysql user db ...

User Comments
Sign Up Login You must be logged in to post a comment.