.. _scripting-xtrabackup:

Scripting Backups With xtrabackup
=================================

The :program:`xtrabackup` tool has several features to enable scripts to control it while they perform related tasks. The :doc:`innobackupex script <../innobackupex/innobackupex_script>` is one example, but :program:`xtrabackup` is easy to control with your own command-line scripts too.

Suspending After Copying
------------------------

In backup mode, :program:`xtrabackup` normally copies the log files in a background thread, copies the data files in a foreground thread, and then stops the log copying thread and finishes. If you use the :option:`--suspend-at-end` option, instead of stopping the log thread and finishing, xtrabackup continues to copy the log files, and creates a file in the target directory called :file:`xtrabackup_suspended`. As long as that file exists, xtrabackup will continue to watch the log files and copy them into the :file:`xtrabackup_logfile` in the target directory. When the file is removed, :program:`xtrabackup` will finish copying the log file and exit.

This functionality is useful for coordinating the InnoDB data backups with other actions. Perhaps the most obvious is copying the table definitions (the :file:`.frm` files) so that the backup can be restored. You can start :program:`xtrabackup` in the  background, wait for the :file:`xtrabackup_suspended` file to be created, and then copy any other files you need to complete the backup. This is exactly what the :doc:`innobackupex <../innobackupex/innobackupex_script>` tool does (it also copies MyISAM data and other files).

.. _generating-meta-data:

Generating Meta-Data
--------------------

It is a good idea for the backup to include all the information you need to restore the backup. The :program:`xtrabackup` tool can print out the contents of a :file:`my.cnf` file that are needed to restore the data and log files. If you add the :option:`--print-param` option, it will print out something like the following: ::

  # This MySQL options file was generated by XtraBackup.
  [mysqld]
  datadir = /data/mysql/
  innodb_data_home_dir = /data/innodb/
  innodb_data_file_path = ibdata1:10M:autoextend
  innodb_log_group_home_dir = /data/innodb-logs/

You can redirect this output into a file in the target directory of the backup.

Agreeing on the Source Directory
--------------------------------

It's possible that the presence of a defaults file or other factors could cause :program:`xtrabackup` to back up data from a different location than you expected. To prevent this, you can use :option:`--print-param` to ask it where it will be copying data from. You can use the output to ensure that :program:`xtrabackup` and your script are working on the same dataset.

.. _xtra-log-streaming:

Log Streaming
-------------

You can instruct :program:`xtrabackup` to omit copying data files, and simply stream the log file to its standard output instead with :option:`--log-stream`. This automatically adds the :option:`--suspend-at-end` option. Your script can then perform tasks such as streaming remote backups by piping the log files into an SSH connection and copying the data files to another server with a tool such as :command:`rsync` or the :doc:`xbstream binary <../xbstream/xbstream>`.
