Merge lp:~hrvojem/percona-xtrabackup/bug1222818-2.0 into lp:percona-xtrabackup/2.0

[Hrvoje Matijakovic]

[Alexey Kopytov (akopytov)]

Hrvoje,

1. This text is a bit misleading:

"When :doc:`restoring individual tables
<xtrabackup_bin/restoring_individual_tables>` with |Percona XtraBackup|,
it creates a file with ``.exp`` extension per exported table containing
the information for importing it"

I suggest something along the following lines:

"Files with the ``.exp`` extension are created by |Percona XtraBackup|
per each InnoDB tablespace when the --export option is used on
prepare. These files can be used to import those tablespaces on Percona
Server 5.5 or lower versions, see :doc:`restoring individual tables
<xtrabackup_bin/restoring_individual_tables>`"

2. Strictly speaking, a .cfg file is _not_ required to import a
tablespace to MySQL 5.6 or Percona Server 5.6. A tablespace will be
imported successfully even if it is from another server, but InnoDB will
do schema validation if the corresponding .cfg file is present in the
same directory.

3. “In |InnoDB| versions prior to 5.6” -> “In server versions...”?

4. “However, with the |xtrabackup| binary” – you don’t necessarily have
to use the xtrabackup binary, “innobackupex --apply-log --export” will
work as well. Can we just say “with Percona XtraBackup” in both
innobackupex and xtrabackup sections?

5. We should make it clear that innodb_import_table_from_xtrabackup is
only required when importing a table to Percona Server version 5.5 or
lower. Which we do in the following note, but that means the following
text can be removed from preceding paragraph: “... and requires
`innodb_import_table_from_xtrabackup
<http://www.percona.com/doc/percona-server/5.5/management/innodb_expand_import.html#innodb_import_table_from_xtrabackup>`_
to be enabled on the destination server”

review: Needs Fixing

[Alexey Kopytov (akopytov)]

review: Approve

=== modified file 'doc/source/faq.rst'
--- doc/source/faq.rst	2013-08-30 08:52:03 +0000
+++ doc/source/faq.rst	2013-11-14 12:32:00 +0000
@@ -55,3 +55,8 @@
 ============================================================================================
 
 In case the ibdata and ib_log files are located in different directories outside of the datadir, you will have to put them in their proper place after the logs have been applied.
+
+Backup fails with Error 24: 'Too many open files'
+=================================================
+
+This usually happens when database being backed up contains large amount of files and |Percona XtraBackup| can't open all of them to create a successful backup. In order to avoid this error the operating system should be configured appropriately so that |Percona XtraBackup| can open all its files. On Linux, this can be done with the ``ulimit`` command for specific backup session or by editing the :file:`/etc/security/limits.conf` to change it globally (**NOTE**: the maximum possible value that can be set up is 1048576 which is a hard-coded constant in the Linux kernel). 

=== modified file 'doc/source/glossary.rst'
--- doc/source/glossary.rst	2013-08-30 08:52:03 +0000
+++ doc/source/glossary.rst	2013-11-14 12:32:00 +0000
@@ -88,7 +88,7 @@
      Each |MyISAM| table has ``.MYI`` (MYIndex) file which contains the table's indexes.
 
    .exp
-     When :doc:`exporting a table <xtrabackup_bin/exporting_importing_tables>` with |Percona XtraBackup|, it creates a file with ``.exp`` extension per exported table containing the information for importing it.
+     Files with the ``.exp`` extension are created by |Percona XtraBackup| per each |InnoDB| tablespace when the :option:`xtrabckup --export` option is used on prepare. These files can be used to import those tablespaces on |Percona Server| 5.5 or lower versions, see :doc:`restoring individual tables <xtrabackup_bin/restoring_individual_tables>`"
 
    .MRG
      Each table using the :program:`MERGE` storage engine, besides of a :term:`.frm` file, will have :term:`.MRG` file containing the names of the |MyISAM| tables associated with it.

=== modified file 'doc/source/howtos/recipes_ibkx_partition.rst'
--- doc/source/howtos/recipes_ibkx_partition.rst	2013-08-30 08:52:03 +0000
+++ doc/source/howtos/recipes_ibkx_partition.rst	2013-11-14 12:32:00 +0000
@@ -36,7 +36,7 @@
 Preparing the backup
 =====================
 
-For preparing partial backups, the procedure is analogous to :doc:`exporting tables <../innobackupex/importing_exporting_tables_ibk>` : apply the logs and use the :option:`--export` option::
+For preparing partial backups, the procedure is analogous to :doc:`restoring individual tables <../innobackupex/restoring_individual_tables_ibk>` : apply the logs and use the :option:`--export` option::
 
   $ innobackupex --apply-log --export /mnt/backup/2012-08-28_10-29-09
 
@@ -65,10 +65,11 @@
 Restoring from the backups
 ==========================
 
-Restoring should be done by :doc:`importing the tables <../innobackupex/importing_exporting_tables_ibk>` in the partial backup to the server. 
+Restoring should be done by :doc:`importing the tables <../innobackupex/restoring_individual_tables_ibk>` in the partial backup to the server. 
 
 .. note::
- Improved table/partition import is only available in |Percona Server|, this means that partitions which were backed up from different server can be imported as well. For |MySQL| only partitions from that server can be imported with some important limitations. There should be no DROP/CREATE/TRUNCATE/ALTER TABLE commands issued between taking the backup and importing the partition.
+
+  Improved table/partition import is only available in |Percona Server| and |MySQL| 5.6, this means that partitions which were backed up from different server can be imported as well. For versions older than |MySQL| 5.6 only partitions from that server can be imported with some important limitations. There should be no DROP/CREATE/TRUNCATE/ALTER TABLE commands issued between taking the backup and importing the partition.
 
 First step is to create new table in which data will be restored :: 
 

=== modified file 'doc/source/index.rst'
--- doc/source/index.rst	2013-04-29 09:29:00 +0000
+++ doc/source/index.rst	2013-11-14 12:32:00 +0000
@@ -7,13 +7,13 @@
  Percona Xtrabackup - Documentation
 ====================================
 
-*Percona* |XtraBackup| is an open-source hot backup utility for |MySQL| - based servers that doesn't lock your database during the backup.
+|Percona XtraBackup| is an open-source hot backup utility for |MySQL| - based servers that doesn't lock your database during the backup.
 
 It can back up data from |InnoDB|, |XtraDB|, and |MyISAM| tables on unmodified |MySQL| 5.0, 5.1, 5.5 and 5.6 servers, as well as |Percona Server| with |XtraDB|. For a high-level overview of many of its advanced features, including a feature comparison, please see :doc:`intro`.
 
-Whether it is a 24x7 highly loaded server or a low-transaction-volume environment, *Percona* |XtraBackup| is designed to make backups a seamless procedure without disrupting the performance of the server in a production environment. `Commercial support contracts are available <http://www.percona.com/mysql-support/>`_.
+Whether it is a 24x7 highly loaded server or a low-transaction-volume environment, |Percona XtraBackup| is designed to make backups a seamless procedure without disrupting the performance of the server in a production environment. `Commercial support contracts are available <http://www.percona.com/mysql-support/>`_.
 
-*Percona* |XtraBackup| is a combination of the |xtrabackup| *C* program, and the |innobackupex| *Perl* script. The |xtrabackup| program copies and manipulates |InnoDB| and |XtraDB| data files, and the *Perl* script enables enhanced functionality, such as interacting with a running |MySQL| server and backing up |MyISAM| tables. 
+|Percona XtraBackup| is a combination of the |xtrabackup| *C* program, and the |innobackupex| *Perl* script. The |xtrabackup| program copies and manipulates |InnoDB| and |XtraDB| data files, and the *Perl* script enables enhanced functionality, such as interacting with a running |MySQL| server and backing up |MyISAM| tables. 
 
 Introduction
 ============

=== modified file 'doc/source/innobackupex/innobackupex_script.rst'
--- doc/source/innobackupex/innobackupex_script.rst	2013-04-29 09:29:00 +0000
+++ doc/source/innobackupex/innobackupex_script.rst	2013-11-14 12:32:00 +0000
@@ -47,7 +47,7 @@
    parallel_copy_ibk
    throttling_ibk
    remote_backups_ibk
-   importing_exporting_tables_ibk
+   restoring_individual_tables_ibk
    pit_recovery_ibk
 
 

=== modified file 'doc/source/innobackupex/partial_backups_innobackupex.rst'
--- doc/source/innobackupex/partial_backups_innobackupex.rst	2013-08-30 08:52:03 +0000
+++ doc/source/innobackupex/partial_backups_innobackupex.rst	2013-11-14 12:32:00 +0000
@@ -14,7 +14,7 @@
 Using the :option:`--include` option
 ------------------------------------
 
-The regular expression provided to this will be matched against the fully qualified tablename, including the database name, in the form ``databasename.tablename``.
+The regular expression provided to this will be matched against the fully qualified table name, including the database name, in the form ``databasename.tablename``.
 
 For example, ::
 
@@ -57,7 +57,7 @@
 Preparing Partial Backups
 =========================
 
-For preparing partial backups, the procedure is analogous to :doc:`exporting tables <importing_exporting_tables_ibk>` : apply the logs and use the :option:`--export` option::
+For preparing partial backups, the procedure is analogous to :doc:`restoring individual tables <restoring_individual_tables_ibk>` : apply the logs and use the :option:`--export` option::
 
   $ innobackupex --apply-log --export /path/to/partial/backup
 
@@ -84,7 +84,7 @@
 Restoring Partial Backups
 =========================
 
-Restoring should be done by :doc:`importing the tables <importing_exporting_tables_ibk>` in the partial backup to the server. 
+Restoring should be done by :doc:`restoring individual tables <restoring_individual_tables_ibk>` in the partial backup to the server. 
 
 It can also be done by copying back the prepared backup to a "clean" :term:`datadir` (in that case, make sure to include the ``mysql`` database). System database can be created with: ::
 

=== renamed file 'doc/source/innobackupex/importing_exporting_tables_ibk.rst' => 'doc/source/innobackupex/restoring_individual_tables_ibk.rst'
--- doc/source/innobackupex/importing_exporting_tables_ibk.rst	2013-03-19 15:21:27 +0000
+++ doc/source/innobackupex/restoring_individual_tables_ibk.rst	2013-11-14 12:32:00 +0000
@@ -1,14 +1,14 @@
 .. _imp_exp_ibk:
 
-===========================================
- Importing and Exporting Individual Tables
-===========================================
-
-In standard |InnoDB|, it is not normally possible to copy tables between servers by copying the files, even with :term:`innodb_file_per_table` enabled. But |XtraBackup| allows to migrate individual table from any |InnoDB| database to |Percona Server| with |XtraDB|.
-
-The table is required to be created with the option :term:`innodb_file_per_table` enabled in the server, as exporting is only possible when table is stored in its own table space.
-
-The importing server (at the moment it only supported by |Percona Server|) should have :term:`innodb_file_per_table` and :term:`innodb_expand_import` options enabled.
+=============================
+ Restoring Individual Tables
+=============================
+
+In server versions prior to 5.6, it is not possible to copy tables between servers by copying the files, even with :term:`innodb_file_per_table`. However, with the |Percona XtraBackup|, you can export individual tables from any |InnoDB| database, and import them into |Percona Server| with |XtraDB| or |MySQL| 5.6 (The source doesn't have to be |XtraDB| or or |MySQL| 5.6, but the destination does). This only works on individual :term:`.ibd` files, and cannot export a table that is not contained in its own :term:`.ibd` file.
+
+.. note:: 
+
+   If you're running |Percona Server| version older than 5.5.10-20.1, variable `innodb_expand_import <http://www.percona.com/doc/percona-server/5.5/management/innodb_expand_import.html#innodb_expand_import>`_ should be used instead of `innodb_import_table_from_xtrabackup <http://www.percona.com/doc/percona-server/5.5/management/innodb_expand_import.html#innodb_import_table_from_xtrabackup>`_.
 
 Exporting tables
 ================
@@ -25,7 +25,20 @@
   `./mydatabase/mytable.exp` (1 indexes)
   ..
 
-Each :term:`.exp` file will be used for importing that table.
+Now you should see a :term:`.exp` file in the target directory: ::
+
+  $ find /data/backups/mysql/ -name export_test.*
+  /data/backups/mysql/test/export_test.exp
+  /data/backups/mysql/test/export_test.ibd
+  /data/backups/mysql/test/export_test.cfg
+
+These three files are all you need to import the table into a server running |Percona Server| with |XtraDB| or |MySQL| 5.6.
+
+.. note:: 
+
+  |MySQL| uses ``.cfg`` file which contains |InnoDB| dictionary dump in special format. This format is different from the ``.exp`` one which is used in |XtraDB| for the same purpose. Strictly speaking, a ``.cfg`` file is **not** required to import a tablespace to |MySQL| 5.6 or |Percona Server| 5.6. A tablespace will be imported successfully even if it is from another server, but |InnoDB| will do schema validation if the corresponding ``.cfg`` file is present in the same directory.
+
+Each :term:`.exp` (or ``.cfg``)  file will be used for importing that table.
 
 .. note::
 
@@ -42,7 +55,7 @@
 
    OTHERSERVER|mysql> ALTER TABLE mydatabase.mytable DISCARD TABLESPACE;
 
-After this, copy :file:`mytable.ibd` and :file:`mytable.exp` files to database's home, and import its tablespace: ::
+After this, copy :file:`mytable.ibd` and :file:`mytable.exp` ( or :file:`mytable.cfg` if importing to |MySQL| 5.6) files to database's home, and import its tablespace: ::
 
    OTHERSERVER|mysql> ALTER TABLE mydatabase.mytable IMPORT TABLESPACE;
 

=== modified file 'doc/source/percona-theme/layout.html'
--- doc/source/percona-theme/layout.html	2013-08-30 08:52:03 +0000
+++ doc/source/percona-theme/layout.html	2013-11-14 12:32:00 +0000
@@ -349,7 +349,7 @@
   _gaq.push(['b._trackPageview']);
   (function() {
   var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
-  ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google- analytics.com/ga.js';
+  ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
   var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
   })();
 </script>

=== renamed file 'doc/source/xtrabackup_bin/exporting_importing_tables.rst' => 'doc/source/xtrabackup_bin/restoring_individual_tables.rst'
--- doc/source/xtrabackup_bin/exporting_importing_tables.rst	2013-05-06 13:52:03 +0000
+++ doc/source/xtrabackup_bin/restoring_individual_tables.rst	2013-11-14 12:32:00 +0000
@@ -1,10 +1,10 @@
 .. _export_import_tables:
 
-================================
- Exporting and Importing Tables
-================================
+=============================
+ Restoring Individual Tables
+=============================
 
-In |InnoDB| versions prior to 5.6, it is not possible to copy tables between servers by copying the files, even with :term:`innodb_file_per_table`. However, with the |xtrabackup| binary, you can export individual tables from any |InnoDB| database, and import them into |Percona Server| with |XtraDB| or |MySQL| 5.6. (The source doesn't have to be |XtraDB| or or |MySQL| 5.6, but the destination does.) This functionality requires :term:`innodb_file_per_table` to be used on both servers, and requires :term:`innodb_expand_import` to be enabled on the destination server. It only works on individual :term:`.ibd` files, and cannot export a table that is not contained in its own :term:`.ibd` file.
+In server versions prior to 5.6, it is not possible to copy tables between servers by copying the files, even with :term:`innodb_file_per_table`. However, with |Percona XtraBackup|, you can export individual tables from any |InnoDB| database, and import them into |Percona Server| with |XtraDB| or |MySQL| 5.6. (The source doesn't have to be |XtraDB| or or |MySQL| 5.6, but the destination does.) This only works on individual :term:`.ibd` files, and cannot export a table that is not contained in its own :term:`.ibd` file.
 
 Let's see how to export and import the following table: ::
 
@@ -12,6 +12,10 @@
     a int(11) DEFAULT NULL
   ) ENGINE=InnoDB DEFAULT CHARSET=latin1;
 
+.. note:: 
+
+   If you're running |Percona Server| version older than 5.5.10-20.1, variable `innodb_expand_import <http://www.percona.com/doc/percona-server/5.5/management/innodb_expand_import.html#innodb_expand_import>`_ should be used instead of `innodb_import_table_from_xtrabackup <http://www.percona.com/doc/percona-server/5.5/management/innodb_expand_import.html#innodb_import_table_from_xtrabackup>`_.
+
 Exporting the Table
 ===================
 
@@ -35,12 +39,12 @@
 
 .. note:: 
 
-  |MySQL| uses ``.cfg`` file which contains |InnoDB| dictionary dump in special format. This format is different from the ``.exp`` one which is used in |XtraDB| for the same purpose.
+  |MySQL| uses ``.cfg`` file which contains |InnoDB| dictionary dump in special format. This format is different from the ``.exp`` one which is used in |XtraDB| for the same purpose. Strictly speaking, a ``.cfg`` file is not required to import a tablespace to |MySQL| 5.6 or |Percona Server| 5.6. A tablespace will be imported successfully even if it is from another server, but |InnoDB| will do schema validation if the corresponding ``.cfg`` file is present in the same directory.
 
 Importing the Table
 ===================
 
-On the destination server running |Percona Server| with |XtraDB| and :term:`innodb_expand_import` option enabled, or |MySQL| 5.6, create a table with the same structure, and then perform the following steps:
+On the destination server running |Percona Server| with |XtraDB| and `innodb_import_table_from_xtrabackup <http://www.percona.com/doc/percona-server/5.5/management/innodb_expand_import.html#innodb_import_table_from_xtrabackup>`_ option enabled, or |MySQL| 5.6, create a table with the same structure, and then perform the following steps:
 
 * Execute ``ALTER TABLE test.export_test DISCARD TABLESPACE;``
   

=== modified file 'doc/source/xtrabackup_bin/xbk_option_reference.rst'
--- doc/source/xtrabackup_bin/xbk_option_reference.rst	2013-04-30 07:33:04 +0000
+++ doc/source/xtrabackup_bin/xbk_option_reference.rst	2013-11-14 12:32:00 +0000
@@ -47,7 +47,7 @@
 
 .. option:: --export
 
-   Create files necessary for exporting tables. See :doc:`Exporting and Importing Tables <exporting_importing_tables>`.
+   Create files necessary for exporting tables. See :doc:`Restoring Individual Tables <restoring_individual_tables>`.
 
 .. option:: --extra-lsndir=name 
 

=== modified file 'doc/source/xtrabackup_bin/xtrabackup_binary.rst'
--- doc/source/xtrabackup_bin/xtrabackup_binary.rst	2013-04-29 09:29:00 +0000
+++ doc/source/xtrabackup_bin/xtrabackup_binary.rst	2013-11-14 12:32:00 +0000
@@ -44,7 +44,7 @@
    scripting_backups_xbk
    analyzing_table_statistics
    working_with_binary_logs
-   exporting_importing_tables
+   restoring_individual_tables
    lru_dump
    
 ..    performance_tunning_innobackupex