7.4 Using mysqldump for Backups

Menu:
mysqldump-sql-format:: Dumping Data in SQL Format with mysqldump
reloading-sql-format-dumps:: Reloading SQL-Format Backups
mysqldump-delimited-text:: Dumping Data in Delimited-Text Format with mysqldump
reloading-delimited-text-dumps:: Reloading Delimited-Text Format Backups
mysqldump-tips:: mysqldump Tips

This section describes how to use *note 'mysqldump': mysqldump. to produce dump files, and how to reload dump files. A dump file can be used in several ways:

As a backup to enable data recovery in case of data loss.
As a source of data for setting up replicas.

As a source of data for experimentation:

* To make a copy of a database that you can use without changing
  the original data.

* To test potential upgrade incompatibilities.

*note 'mysqldump': mysqldump. produces two types of output, depending on whether the '--tab' option is given:

Without '--tab', note 'mysqldump': mysqldump. writes SQL statements to the standard output. This output consists of 'CREATE' statements to create dumped objects (databases, tables, stored routines, and so forth), and 'INSERT' statements to load data into tables. The output can be saved in a file and reloaded later using note 'mysql': mysql. to recreate the dumped objects. Options are available to modify the format of the SQL statements, and to control which objects are dumped.
With '--tab', note 'mysqldump': mysqldump. produces two output files for each dumped table. The server writes one file as tab-delimited text, one line per table row. This file is named 'TBL_NAME.txt' in the output directory. The server also sends a note 'CREATE TABLE': create-table. statement for the table to *note 'mysqldump': mysqldump, which writes it as a file named 'TBL_NAME.sql' in the output directory.

File: manual.info.tmp, Node: mysqldump-sql-format, Next: reloading-sql-format-dumps, Prev: using-mysqldump, Up: using-mysqldump

7.4.1 Dumping Data in SQL Format with mysqldump

This section describes how to use note 'mysqldump': mysqldump. to create SQL-format dump files. For information about reloading such dump files, see note reloading-sql-format-dumps::.

By default, *note 'mysqldump': mysqldump. writes information as SQL statements to the standard output. You can save the output in a file:

 $> mysqldump [ARGUMENTS] > FILE_NAME

To dump all databases, invoke *note 'mysqldump': mysqldump. with the '--all-databases' option:

 $> mysqldump --all-databases > dump.sql

To dump only specific databases, name them on the command line and use the '--databases' option:

 $> mysqldump --databases db1 db2 db3 > dump.sql

The '--databases' option causes all names on the command line to be treated as database names. Without this option, *note 'mysqldump': mysqldump. treats the first name as a database name and those following as table names.

With '--all-databases' or '--databases', note 'mysqldump': mysqldump. writes note 'CREATE DATABASE': create-database. and note 'USE': use. statements prior to the dump output for each database. This ensures that when the dump file is reloaded, it creates each database if it does not exist and makes it the default database so database contents are loaded into the same database from which they came. If you want to cause the dump file to force a drop of each database before recreating it, use the '--add-drop-database' option as well. In this case, note 'mysqldump': mysqldump. writes a note 'DROP DATABASE': drop-database. statement preceding each note 'CREATE DATABASE': create-database. statement.

To dump a single database, name it on the command line:

 $> mysqldump --databases test > dump.sql

In the single-database case, it is permissible to omit the '--databases' option:

 $> mysqldump test > dump.sql

The difference between the two preceding commands is that without '--databases', the dump output contains no note 'CREATE DATABASE': create-database. or note 'USE': use. statements. This has several implications:

When you reload the dump file, you must specify a default database name so that the server knows which database to reload.
For reloading, you can specify a database name different from the original name, which enables you to reload the data into a different database.
If the database to be reloaded does not exist, you must create it first.
Because the output contains no note 'CREATE DATABASE': create-database. statement, the '--add-drop-database' option has no effect. If you use it, it produces no note 'DROP DATABASE': drop-database. statement.

To dump only specific tables from a database, name them on the command line following the database name:

 $> mysqldump test t1 t3 t7 > dump.sql

File: manual.info.tmp, Node: reloading-sql-format-dumps, Next: mysqldump-delimited-text, Prev: mysqldump-sql-format, Up: using-mysqldump

7.4.2 Reloading SQL-Format Backups

To reload a dump file written by note 'mysqldump': mysqldump. that consists of SQL statements, use it as input to the note 'mysql': mysql. client. If the dump file was created by note 'mysqldump': mysqldump. with the '--all-databases' or '--databases' option, it contains note 'CREATE DATABASE': create-database. and *note 'USE': use. statements and it is not necessary to specify a default database into which to load the data:

 $> mysql < dump.sql

Alternatively, from within *note 'mysql': mysql, use a 'source' command:

 mysql> source dump.sql

If the file is a single-database dump not containing note 'CREATE DATABASE': create-database. and note 'USE': use. statements, create the database first (if necessary):

 $> mysqladmin create db1

Then specify the database name when you load the dump file:

 $> mysql db1 < dump.sql

Alternatively, from within *note 'mysql': mysql, create the database, select it as the default database, and load the dump file:

 mysql> CREATE DATABASE IF NOT EXISTS db1;
 mysql> USE db1;
 mysql> source dump.sql

Note:

For Windows PowerShell users: Because the "<" character is reserved for future use in PowerShell, an alternative approach is required, such as using quotes 'cmd.exe /c "mysql < dump.sql"'.

File: manual.info.tmp, Node: mysqldump-delimited-text, Next: reloading-delimited-text-dumps, Prev: reloading-sql-format-dumps, Up: using-mysqldump

7.4.3 Dumping Data in Delimited-Text Format with mysqldump

This section describes how to use note 'mysqldump': mysqldump. to create delimited-text dump files. For information about reloading such dump files, see note reloading-delimited-text-dumps::.

If you invoke note 'mysqldump': mysqldump. with the '--tab=DIR_NAME' option, it uses DIR_NAME as the output directory and dumps tables individually in that directory using two files for each table. The table name is the base name for these files. For a table named 't1', the files are named 't1.sql' and 't1.txt'. The '.sql' file contains a note 'CREATE TABLE': create-table. statement for the table. The '.txt' file contains the table data, one line per table row.

The following command dumps the contents of the 'db1' database to files in the '/tmp' database:

 $> mysqldump --tab=/tmp db1

The '.txt' files containing table data are written by the server, so they are owned by the system account used for running the server. The server uses *note 'SELECT ... INTO OUTFILE': select-into. to write the files, so you must have the 'FILE' privilege to perform this operation, and an error occurs if a given '.txt' file already exists.

The server sends the 'CREATE' definitions for dumped tables to note 'mysqldump': mysqldump, which writes them to '.sql' files. These files therefore are owned by the user who executes note 'mysqldump': mysqldump.

It is best that '--tab' be used only for dumping a local server. If you use it with a remote server, the '--tab' directory must exist on both the local and remote hosts, and the '.txt' files are written by the server in the remote directory (on the server host), whereas the '.sql' files are written by *note 'mysqldump': mysqldump. in the local directory (on the client host).

For note 'mysqldump --tab': mysqldump, the server by default writes table data to '.txt' files one line per row with tabs between column values, no quotation marks around column values, and newline as the line terminator. (These are the same defaults as for note 'SELECT ... INTO OUTFILE': select-into.)

To enable data files to be written using a different format, *note 'mysqldump': mysqldump. supports these options:

'--fields-terminated-by=STR'

The string for separating column values (default: tab).
'--fields-enclosed-by=CHAR'

The character within which to enclose column values (default: no character).
'--fields-optionally-enclosed-by=CHAR'

The character within which to enclose non-numeric column values (default: no character).
'--fields-escaped-by=CHAR'

The character for escaping special characters (default: no escaping).
'--lines-terminated-by=STR'

The line-termination string (default: newline).

Depending on the value you specify for any of these options, it might be necessary on the command line to quote or escape the value appropriately for your command interpreter. Alternatively, specify the value using hex notation. Suppose that you want *note 'mysqldump': mysqldump. to quote column values within double quotation marks. To do so, specify double quote as the value for the '--fields-enclosed-by' option. But this character is often special to command interpreters and must be treated specially. For example, on Unix, you can quote the double quote like this:

 --fields-enclosed-by='"'

On any platform, you can specify the value in hex:

 --fields-enclosed-by=0x22

It is common to use several of the data-formatting options together. For example, to dump tables in comma-separated values format with lines terminated by carriage-return/newline pairs (''), use this command (enter it on a single line):

 $> mysqldump --tab=/tmp --fields-terminated-by=,
          --fields-enclosed-by='"' --lines-terminated-by=0x0d0a db1

Should you use any of the data-formatting options to dump table data, you must specify the same format when you reload data files later, to ensure proper interpretation of the file contents.

File: manual.info.tmp, Node: reloading-delimited-text-dumps, Next: mysqldump-tips, Prev: mysqldump-delimited-text, Up: using-mysqldump

7.4.4 Reloading Delimited-Text Format Backups

For backups produced with note 'mysqldump --tab': mysqldump, each table is represented in the output directory by an '.sql' file containing the note 'CREATE TABLE': create-table. statement for the table, and a '.txt' file containing the table data. To reload a table, first change location into the output directory. Then process the '.sql' file with *note 'mysql': mysql. to create an empty table and process the '.txt' file to load the data into the table:

 $> mysql db1 < t1.sql
 $> mysqlimport db1 t1.txt

An alternative to using note 'mysqlimport': mysqlimport. to load the data file is to use the note 'LOAD DATA': load-data. statement from within the *note 'mysql': mysql. client:

 mysql> USE db1;
 mysql> LOAD DATA INFILE 't1.txt' INTO TABLE t1;

If you used any data-formatting options with note 'mysqldump': mysqldump. when you initially dumped the table, you must use the same options with note 'mysqlimport': mysqlimport. or *note 'LOAD DATA': load-data. to ensure proper interpretation of the data file contents:

 $> mysqlimport --fields-terminated-by=,
          --fields-enclosed-by='"' --lines-terminated-by=0x0d0a db1 t1.txt

Or:

 mysql> USE db1;
 mysql> LOAD DATA INFILE 't1.txt' INTO TABLE t1
        FIELDS TERMINATED BY ',' FIELDS ENCLOSED BY '"'
        LINES TERMINATED BY '\r\n';

File: manual.info.tmp, Node: mysqldump-tips, Prev: reloading-delimited-text-dumps, Up: using-mysqldump

7.4.5 mysqldump Tips

Menu:
mysqldump-copying-database:: Making a Copy of a Database
mysqldump-copying-to-other-server:: Copy a Database from one Server to Another
mysqldump-stored-programs:: Dumping Stored Programs
mysqldump-definition-data-dumps:: Dumping Table Definitions and Content Separately
mysqldump-upgrade-testing:: Using mysqldump to Test for Upgrade Incompatibilities

This section surveys techniques that enable you to use *note 'mysqldump': mysqldump. to solve specific problems:

How to make a copy a database
How to copy a database from one server to another
How to dump stored programs (stored procedures and functions, triggers, and events)
How to dump definitions and data separately

File: manual.info.tmp, Node: mysqldump-copying-database, Next: mysqldump-copying-to-other-server, Prev: mysqldump-tips, Up: mysqldump-tips

7.4.5.1 Making a Copy of a Database ...................................

 $> mysqldump db1 > dump.sql
 $> mysqladmin create db2
 $> mysql db2 < dump.sql

Do not use '--databases' on the note 'mysqldump': mysqldump. command line because that causes 'USE db1' to be included in the dump file, which overrides the effect of naming 'db2' on the note 'mysql': mysql. command line.

File: manual.info.tmp, Node: mysqldump-copying-to-other-server, Next: mysqldump-stored-programs, Prev: mysqldump-copying-database, Up: mysqldump-tips

7.4.5.2 Copy a Database from one Server to Another ..................................................

On Server 1:

 $> mysqldump --databases db1 > dump.sql

Copy the dump file from Server 1 to Server 2.

On Server 2:

 $> mysql < dump.sql

Use of '--databases' with the note 'mysqldump': mysqldump. command line causes the dump file to include note 'CREATE DATABASE': create-database. and *note 'USE': use. statements that create the database if it does exist and make it the default database for the reloaded data.

Alternatively, you can omit '--databases' from the *note 'mysqldump': mysqldump. command. Then you need to create the database on Server 2 (if necessary) and to specify it as the default database when you reload the dump file.

On Server 1:

 $> mysqldump db1 > dump.sql

On Server 2:

 $> mysqladmin create db1
 $> mysql db1 < dump.sql

You can specify a different database name in this case, so omitting '--databases' from the *note 'mysqldump': mysqldump. command enables you to dump data from one database and load it into another.

File: manual.info.tmp, Node: mysqldump-stored-programs, Next: mysqldump-definition-data-dumps, Prev: mysqldump-copying-to-other-server, Up: mysqldump-tips

7.4.5.3 Dumping Stored Programs ...............................

Several options control how *note 'mysqldump': mysqldump. handles stored programs (stored procedures and functions, triggers, and events):

'--events': Dump Event Scheduler events
'--routines': Dump stored procedures and functions
'--triggers': Dump triggers for tables

The '--triggers' option is enabled by default so that when tables are dumped, they are accompanied by any triggers they have. The other options are disabled by default and must be specified explicitly to dump the corresponding objects. To disable any of these options explicitly, use its skip form: '--skip-events', '--skip-routines', or '--skip-triggers'.

File: manual.info.tmp, Node: mysqldump-definition-data-dumps, Next: mysqldump-upgrade-testing, Prev: mysqldump-stored-programs, Up: mysqldump-tips

7.4.5.4 Dumping Table Definitions and Content Separately ........................................................

The '--no-data' option tells note 'mysqldump': mysqldump. not to dump table data, resulting in the dump file containing only statements to create the tables. Conversely, the '--no-create-info' option tells note 'mysqldump': mysqldump. to suppress 'CREATE' statements from the output, so that the dump file contains only table data.

For example, to dump table definitions and data separately for the 'test' database, use these commands:

 $> mysqldump --no-data test > dump-defs.sql
 $> mysqldump --no-create-info test > dump-data.sql

For a definition-only dump, add the '--routines' and '--events' options to also include stored routine and event definitions:

 $> mysqldump --no-data --routines --events test > dump-defs.sql

File: manual.info.tmp, Node: mysqldump-upgrade-testing, Prev: mysqldump-definition-data-dumps, Up: mysqldump-tips

7.4.5.5 Using mysqldump to Test for Upgrade Incompatibilities .............................................................

When contemplating a MySQL upgrade, it is prudent to install the newer version separately from your current production version. Then you can dump the database and database object definitions from the production server and load them into the new server to verify that they are handled properly. (This is also useful for testing downgrades.)

On the production server:

 $> mysqldump --all-databases --no-data --routines --events > dump-defs.sql

On the upgraded server:

 $> mysql < dump-defs.sql

Because the dump file does not contain table data, it can be processed quickly. This enables you to spot potential incompatibilities without waiting for lengthy data-loading operations. Look for warnings or errors while the dump file is being processed.

After you have verified that the definitions are handled properly, dump the data and try to load it into the upgraded server.

On the production server:

 $> mysqldump --all-databases --no-create-info > dump-data.sql

On the upgraded server:

 $> mysql < dump-data.sql

Now check the table contents and run some test queries.

File: manual.info.tmp, Node: point-in-time-recovery, Next: myisam-table-maintenance, Prev: using-mysqldump, Up: backup-and-recovery