Merge lp:~hrvojem/percona-xtrabackup/doc-57-2.2 into lp:percona-xtrabackup/2.2

[Hrvoje Matijakovic]

[Alexey Kopytov (akopytov)]

review: Approve

=== modified file 'storage/innobase/xtrabackup/doc/source/innobackupex/innobackupex_option_reference.rst'
--- storage/innobase/xtrabackup/doc/source/innobackupex/innobackupex_option_reference.rst	2014-03-15 12:18:51 +0000
+++ storage/innobase/xtrabackup/doc/source/innobackupex/innobackupex_option_reference.rst	2014-03-28 11:49:26 +0000
@@ -98,6 +98,10 @@
 
    This option displays a help screen and exits.
 
+.. option:: --history=NAME
+
+   This option enables the tracking of backup history in the ``PERCONA_SCHEMA.xtrabackup_history`` table. An optional history series name may be specified that will be placed with the history record for the current backup being taken.
+
 .. option:: --host=HOST
 
    This option accepts a string argument that specifies the host to use when connecting to the database server with TCP/IP. It is passed to the mysql child process without alteration. See :command:`mysql --help` for details.
@@ -122,6 +126,14 @@
 
    This option accepts a string argument that specifies the directory where the incremental backup will be combined with the full backup to make a new full backup. It is used with the :option:`--incremental` option.
 
+.. option:: --incremental-history-name=NAME
+
+   This option specifies the name of the backup series stored in the :ref:`PERCONA_SCHEMA.xtrabackup_history <xtrabackup_history>` history record to base an incremental backup on. Percona Xtrabackup will search the history table looking for the most recent (highest innodb_to_lsn), successful backup in the series and take the to_lsn value to use as the starting lsn for the incremental backup. This will be mutually exclusive with :option:`innobackupex --incremental-history-uuid`,:option:`innobackupex --incremental-basedir` and :option:`innobackupex --incremental-lsn`. If no valid lsn can be found (no series by that name, no successful backups by that name) xtrabackup will return with an error. It is used with the :option:`innobackupex --incremental` option.
+
+.. option:: --incremental-history-uuid=UUID
+
+   This option specifies the UUID of the specific history record stored in the :ref:`PERCONA_SCHEMA.xtrabackup_history <xtrabackup_history>` to base an incremental backup on. :option:`innobackupex --incremental-history-name`,:optionL`innobackupex --incremental-basedir` and :option:`innobackupex --incremental-lsn`. If no valid lsn can be found (no success record with that uuid) xtrabackup will return with an error. It is used with the :option:`innobackupex --incremental` option.
+
 .. option:: --incremental-lsn
 
    This option accepts a string argument that specifies the log sequence number (:term:`LSN`) to use for the incremental backup. It is used with the :option:`--incremental` option. It is used instead of specifying :option:`--incremental-basedir`. For databases created by *MySQL* and *Percona Server* 5.0-series versions, specify the as two 32-bit integers in high:low format. For databases created in 5.1 and later, specify the LSN as a single 64-bit integer.
 
=== modified file 'storage/innobase/xtrabackup/doc/source/innobackupex/innobackupex_script.rst'
--- storage/innobase/xtrabackup/doc/source/innobackupex/innobackupex_script.rst	2013-11-15 12:42:15 +0000
+++ storage/innobase/xtrabackup/doc/source/innobackupex/innobackupex_script.rst	2014-03-28 11:49:26 +0000
@@ -51,6 +51,7 @@
    restoring_individual_tables_ibk
    pit_recovery_ibk
    improved_ftwrl
+   storing_history
 
 
 Implementation
 
=== added file 'storage/innobase/xtrabackup/doc/source/innobackupex/storing_history.rst'
--- storage/innobase/xtrabackup/doc/source/innobackupex/storing_history.rst	1970-01-01 00:00:00 +0000
+++ storage/innobase/xtrabackup/doc/source/innobackupex/storing_history.rst	2014-03-28 11:49:26 +0000
@@ -0,0 +1,87 @@
+.. _storing_history:
+
+====================================
+ Store backup history on the server
+====================================
+ 
+|Percona XtraBackup| supports storing the backups history on the server. This feature was implemented in |Percona XtraBackup| 2.2. Storing backup history on the server was implemented to provide users with additional information about backups that are being taken. Backup history information will be stored in the :ref:`PERCONA_SCHEMA.XTRABACKUP_HISTORY <xtrabackup_history>` table.
+
+To use this feature three new |innobackupex| options have been implemented:
+
+* :option:`innobackupex --history` =<name> : This option enables the history feature and allows the user to specify a backup series name that will be placed within the history record.
+
+* :option:`innobackupex --incremental-history-name` =<name> : This option allows an incremental backup to be made based on a specific history series by name. |innobackupex| will search the history table looking for the most recent (highest ``to_lsn``) backup in the series and take the ``to_lsn`` value to use as it's starting lsn. This is mutually exclusive with :option:`innobackupex --incremental-history-uuid`, :option:`innobackupex --incremental-basedir` and :option:`innobackupex --incremental-lsn` options. If no valid LSN can be found (no series by that name) |innobackupex| will return with an error.
+* :option:`innobackupex --incremental-history-uuid` =<uuid> : Allows an incremental backup to be made based on a specific history record identified by UUID. |innobackupex| will search the history table looking for the record matching UUID and take the ``to_lsn`` value to use as it's starting LSN. This options is mutually exclusive with :option:`innobackupex --incremental-basedir`, :option:`innobackupex --incremental-lsn` and :option:`innobackupex --incremental-history-name` options. If no valid LSN can be found (no record by that UUID or missing ``to_lsn``), |innobackupex| will return with an error.
+
+.. note::
+
+   Backup that's currently being performed will **NOT** exist in the xtrabackup_history table within the resulting backup set as the record will not be added to that table until after the backup has been taken.
+
+If you want access to backup history outside of your backup set in the case of some catastrophic event, you will need to either perform a ``mysqldump``, partial backup or ``SELECT`` * on the history table after |innobackupex| completes and store the results with you backup set.
+
+Privileges
+----------
+
+User performing the backup will need following privileges: 
+
+* ``CREATE`` privilege in order to create the :ref:`PERCONA_SCHEMA.xtrabackup_history <xtrabackup_history>` database and table.
+* ``INSERT`` privilege in order to add history records to the :ref:`PERCONA_SCHEMA.xtrabackup_history <xtrabackup_history>` table.
+* ``SELECT`` privilege in order to use :option:`innobackupex --incremental-history-name` or :option:`innobackupex --incremental-history-uuid` in order for the feature to look up the ``innodb_to_lsn`` values in the  :ref:`PERCONA_SCHEMA.xtrabackup_history <xtrabackup_history>` table.
+
+.. _xtrabackup_history:
+
+PERCONA_SCHEMA.XTRABACKUP_HISTORY table
+---------------------------------------
+
+This table contains the information about the previous server backups. Information about the backups will only be written if the backup was taken with :option:`innobackupex --history` option.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40
+  
+   * - Column Name
+     - Description
+   * - uuid 
+     - Unique backup id
+   * - name
+     - User provided name of backup series. There may be multiple entries with the same name used to identify related backups in a series.
+   * - tool_name
+     - Name of tool used to take backup
+   * - tool_command
+     - Exact command line given to the tool with --password and --encryption_key obfuscated 
+   * - tool_version
+     - Version of tool used to take backup
+   * - ibbackup_version
+     - Version of the xtrabackup binary used to take backup
+   * - server_version
+     - Server version on which backup was taken
+   * - start_time
+     - Time at the start of the backup
+   * - end_time
+     - Time at the end of the backup
+   * - lock_time
+     - Amount of time, in seconds, spent calling and holding locks for ``FLUSH TABLES WITH READ LOCK``
+   * - binlog_pos
+     - Binlog file and position at end of ``FLUSH TABLES WITH READ LOCK``
+   * - innodb_from_lsn
+     - LSN at beginning of backup which can be used to determine prior backups
+   * - innodb_to_lsn
+     - LSN at end of backup which can be used as the starting lsn for the next incremental
+   * - partial
+     - Is this a partial backup, if ``N`` that means that it's the full backup
+   * - incremental
+     - Is this an incremental backup
+   * - format
+     - Description of result format (``file``, ``tar``, ``xbstream``) 
+   * - compact
+     - Is this a compact backup
+   * - compressed
+     - Is this a compressed backup
+   * - encrypted
+     - Is this an encrypted backup
+ 
+Limitiatons
+-----------
+
+* :option:`innobackupex --history` option must be specified only on the innobackupex command line and not within a configuration file in order to be effective.
+* :option:`innobackupex --incremental-history-name` and :option:`innobackupex --incremental-history-uuid` options must be specified only on the innobackupex command line and not within a configuration file in order to be effective.
 
=== modified file 'storage/innobase/xtrabackup/doc/source/release-notes/2.2/2.2.1-alpha1.rst'
--- storage/innobase/xtrabackup/doc/source/release-notes/2.2/2.2.1-alpha1.rst	2014-03-26 07:39:36 +0000
+++ storage/innobase/xtrabackup/doc/source/release-notes/2.2/2.2.1-alpha1.rst	2014-03-28 11:49:26 +0000
@@ -17,7 +17,7 @@
 
  |Percona XtraBackup| implemented support for `Backup Locks <http://www.percona.com/doc/percona-server/5.6/management/backup_locks.html#backup-locks>`_.
 
- |Percona XtraBackup| can now store backup history on the server itself in a special table created for that purpose. 
+ |Percona XtraBackup| can now store :ref:`backup history <storing_history>` on the server itself in a special table created for that purpose. 
 
  ``innobackupex-1.5.1`` symlink has been removed, instead |innobackupex| binary should be used.
 
@@ -25,5 +25,11 @@
 
  |Percona XtraBackup| has been rebased on |MySQL| 5.6.16.
 
- 
+Bugs Fixed
+----------
 
+ Information about tool version used to take the backup was added by implementing :ref:`backup history <storing_history>` feature. Bug fixed :bug:`1133017`.
+ 
+ If an XtraDB-based binary was used to a backup an |InnoDB| database, it will convert it to |XtraDB| by adding the ``XTRADB_1`` marker in the dictionary header page and by adding the ``SYS_STATS`` table. Bug fixed :bug:`988310`.
+ 
+Other bugs fixed: :bug:`721690`, :bug:`1255899`, :bug:`1255901`, :bug:`1268300`, and :bug:`788316`.