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

Proposed by Hrvoje Matijakovic on 2014-03-28
Status: Merged
Approved by: Alexey Kopytov on 2014-03-28
Approved revision: no longer in the source branch.
Merged at revision: 4959
Proposed branch: lp:~hrvojem/percona-xtrabackup/doc-57-2.2
Merge into: lp:percona-xtrabackup/2.2
Diff against target: 159 lines (+108/-2)
4 files modified
storage/innobase/xtrabackup/doc/source/innobackupex/innobackupex_option_reference.rst (+12/-0)
storage/innobase/xtrabackup/doc/source/innobackupex/innobackupex_script.rst (+1/-0)
storage/innobase/xtrabackup/doc/source/innobackupex/storing_history.rst (+87/-0)
storage/innobase/xtrabackup/doc/source/release-notes/2.2/2.2.1-alpha1.rst (+8/-2)
To merge this branch: bzr merge lp:~hrvojem/percona-xtrabackup/doc-57-2.2
Reviewer Review Type Date Requested Status
Alexey Kopytov (community) 2014-03-28 Approve on 2014-03-28
Review via email: mp+213227@code.launchpad.net
To post a comment you must log in.
Alexey Kopytov (akopytov) :
review: Approve
4959. By Hrvoje Matijakovic on 2014-03-28

- DOC-57 - document storing history on server
- release notes updates

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'storage/innobase/xtrabackup/doc/source/innobackupex/innobackupex_option_reference.rst'
2--- storage/innobase/xtrabackup/doc/source/innobackupex/innobackupex_option_reference.rst 2014-03-15 12:18:51 +0000
3+++ storage/innobase/xtrabackup/doc/source/innobackupex/innobackupex_option_reference.rst 2014-03-28 11:49:26 +0000
4@@ -98,6 +98,10 @@
5
6 This option displays a help screen and exits.
7
8+.. option:: --history=NAME
9+
10+ 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.
11+
12 .. option:: --host=HOST
13
14 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.
15@@ -122,6 +126,14 @@
16
17 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.
18
19+.. option:: --incremental-history-name=NAME
20+
21+ 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.
22+
23+.. option:: --incremental-history-uuid=UUID
24+
25+ 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.
26+
27 .. option:: --incremental-lsn
28
29 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.
30
31=== modified file 'storage/innobase/xtrabackup/doc/source/innobackupex/innobackupex_script.rst'
32--- storage/innobase/xtrabackup/doc/source/innobackupex/innobackupex_script.rst 2013-11-15 12:42:15 +0000
33+++ storage/innobase/xtrabackup/doc/source/innobackupex/innobackupex_script.rst 2014-03-28 11:49:26 +0000
34@@ -51,6 +51,7 @@
35 restoring_individual_tables_ibk
36 pit_recovery_ibk
37 improved_ftwrl
38+ storing_history
39
40
41 Implementation
42
43=== added file 'storage/innobase/xtrabackup/doc/source/innobackupex/storing_history.rst'
44--- storage/innobase/xtrabackup/doc/source/innobackupex/storing_history.rst 1970-01-01 00:00:00 +0000
45+++ storage/innobase/xtrabackup/doc/source/innobackupex/storing_history.rst 2014-03-28 11:49:26 +0000
46@@ -0,0 +1,87 @@
47+.. _storing_history:
48+
49+====================================
50+ Store backup history on the server
51+====================================
52+
53+|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.
54+
55+To use this feature three new |innobackupex| options have been implemented:
56+
57+* :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.
58+
59+* :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.
60+* :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.
61+
62+.. note::
63+
64+ 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.
65+
66+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.
67+
68+Privileges
69+----------
70+
71+User performing the backup will need following privileges:
72+
73+* ``CREATE`` privilege in order to create the :ref:`PERCONA_SCHEMA.xtrabackup_history <xtrabackup_history>` database and table.
74+* ``INSERT`` privilege in order to add history records to the :ref:`PERCONA_SCHEMA.xtrabackup_history <xtrabackup_history>` table.
75+* ``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.
76+
77+.. _xtrabackup_history:
78+
79+PERCONA_SCHEMA.XTRABACKUP_HISTORY table
80+---------------------------------------
81+
82+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.
83+
84+.. list-table::
85+ :header-rows: 1
86+ :widths: 20 40
87+
88+ * - Column Name
89+ - Description
90+ * - uuid
91+ - Unique backup id
92+ * - name
93+ - User provided name of backup series. There may be multiple entries with the same name used to identify related backups in a series.
94+ * - tool_name
95+ - Name of tool used to take backup
96+ * - tool_command
97+ - Exact command line given to the tool with --password and --encryption_key obfuscated
98+ * - tool_version
99+ - Version of tool used to take backup
100+ * - ibbackup_version
101+ - Version of the xtrabackup binary used to take backup
102+ * - server_version
103+ - Server version on which backup was taken
104+ * - start_time
105+ - Time at the start of the backup
106+ * - end_time
107+ - Time at the end of the backup
108+ * - lock_time
109+ - Amount of time, in seconds, spent calling and holding locks for ``FLUSH TABLES WITH READ LOCK``
110+ * - binlog_pos
111+ - Binlog file and position at end of ``FLUSH TABLES WITH READ LOCK``
112+ * - innodb_from_lsn
113+ - LSN at beginning of backup which can be used to determine prior backups
114+ * - innodb_to_lsn
115+ - LSN at end of backup which can be used as the starting lsn for the next incremental
116+ * - partial
117+ - Is this a partial backup, if ``N`` that means that it's the full backup
118+ * - incremental
119+ - Is this an incremental backup
120+ * - format
121+ - Description of result format (``file``, ``tar``, ``xbstream``)
122+ * - compact
123+ - Is this a compact backup
124+ * - compressed
125+ - Is this a compressed backup
126+ * - encrypted
127+ - Is this an encrypted backup
128+
129+Limitiatons
130+-----------
131+
132+* :option:`innobackupex --history` option must be specified only on the innobackupex command line and not within a configuration file in order to be effective.
133+* :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.
134
135=== modified file 'storage/innobase/xtrabackup/doc/source/release-notes/2.2/2.2.1-alpha1.rst'
136--- storage/innobase/xtrabackup/doc/source/release-notes/2.2/2.2.1-alpha1.rst 2014-03-26 07:39:36 +0000
137+++ storage/innobase/xtrabackup/doc/source/release-notes/2.2/2.2.1-alpha1.rst 2014-03-28 11:49:26 +0000
138@@ -17,7 +17,7 @@
139
140 |Percona XtraBackup| implemented support for `Backup Locks <http://www.percona.com/doc/percona-server/5.6/management/backup_locks.html#backup-locks>`_.
141
142- |Percona XtraBackup| can now store backup history on the server itself in a special table created for that purpose.
143+ |Percona XtraBackup| can now store :ref:`backup history <storing_history>` on the server itself in a special table created for that purpose.
144
145 ``innobackupex-1.5.1`` symlink has been removed, instead |innobackupex| binary should be used.
146
147@@ -25,5 +25,11 @@
148
149 |Percona XtraBackup| has been rebased on |MySQL| 5.6.16.
150
151-
152+Bugs Fixed
153+----------
154
155+ Information about tool version used to take the backup was added by implementing :ref:`backup history <storing_history>` feature. Bug fixed :bug:`1133017`.
156+
157+ 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`.
158+
159+Other bugs fixed: :bug:`721690`, :bug:`1255899`, :bug:`1255901`, :bug:`1268300`, and :bug:`788316`.

Subscribers

People subscribed via source and target branches