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

[Hrvoje Matijakovic]

[Alexey Kopytov (akopytov)]

Same comments as in the 2.0 MP.

review: Needs Fixing

[Alexey Kopytov (akopytov)]

review: Approve

=== modified file 'doc/source/faq.rst'
--- doc/source/faq.rst	2013-08-30 09:55:04 +0000
+++ doc/source/faq.rst	2013-11-15 12:43:54 +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-15 12:43:54 +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-15 12:43:54 +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-06-19 08:48:19 +0000
+++ doc/source/index.rst	2013-11-15 12:43:54 +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 |MySQL| 5.1 [#n-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-07-31 10:55:11 +0000
+++ doc/source/innobackupex/innobackupex_script.rst	2013-11-15 12:43:54 +0000
@@ -48,7 +48,7 @@
    replication_ibk
    parallel_copy_ibk
    throttling_ibk
-   importing_exporting_tables_ibk
+   restoring_individual_tables_ibk
    pit_recovery_ibk
    improved_ftwrl
 

=== 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-15 12:43:54 +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-15 12:43:54 +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;
 

=== 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-15 12:43:54 +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-11-06 15:44:58 +0000
+++ doc/source/xtrabackup_bin/xbk_option_reference.rst	2013-11-15 12:43:54 +0000
@@ -55,7 +55,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-09-19 13:06:49 +0000
+++ doc/source/xtrabackup_bin/xtrabackup_binary.rst	2013-11-15 12:43:54 +0000
@@ -46,7 +46,7 @@
    scripting_backups_xbk
    analyzing_table_statistics
    working_with_binary_logs
-   exporting_importing_tables
+   restoring_individual_tables
    lru_dump
    
 ..    performance_tunning_innobackupex