Merge lp:~hrvojem/percona-server/rn-5.5.37-35.0-5.6 into lp:percona-server/5.6

[Hrvoje Matijakovic]

[Laurynas Biveinis (laurynas-biveinis)]

    - TokuDB secondary clustering keys undocumented

review: Needs Fixing

[Laurynas Biveinis (laurynas-biveinis)]

- Explain what query optimiser support for the clustering keys means: the query optimiser will avoid primary clustered index reads and replace them by secondary clustered index reads in certain scenarios.
- Before the full supported syntax, add a few basic examples of CREATE TABLE etc.
- It would be very nice to have an example with a differing query plan for the same query with regular and with clustering secondary key. Might be possible to ask Tokutek for what would be a flagship example, or maybe there is an example in their docs.

review: Needs Fixing

[Laurynas Biveinis (laurynas-biveinis)]

In the sample CREATE TABLE, define a primary key too for clarity
The query plans with clustering and regular secondary index are identical (except for index name and row estimate).

review: Needs Fixing

[Laurynas Biveinis (laurynas-biveinis)]

review: Approve

=== modified file 'doc/source/conf.py'
--- doc/source/conf.py	2014-04-25 10:55:01 +0000
+++ doc/source/conf.py	2014-05-06 12:44:40 +0000
@@ -54,7 +54,7 @@
 # The short X.Y version.
 version = '5.6'
 # The full version, including alpha/beta/rc tags.
-release = '5.6.16-64.2-tokudb'
+release = '5.6.17-65.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -110,6 +110,8 @@
 
 .. |Percona XtraBackup|  replace:: *Percona XtraBackup*
 
+.. |Percona Toolkit|  replace:: *Percona Toolkit*
+
 .. |Percona Server|  replace:: *Percona Server*
 
 .. |Percona|  replace:: *Percona*
 
=== added file 'doc/source/diagnostics/scalability_metrics_plugin.rst'
--- doc/source/diagnostics/scalability_metrics_plugin.rst	1970-01-01 00:00:00 +0000
+++ doc/source/diagnostics/scalability_metrics_plugin.rst	2014-05-06 12:44:40 +0000
@@ -0,0 +1,99 @@
+.. _scalability_metrics_plugin:
+
+=====================================
+ Metrics for scalability measurement
+=====================================
+
+|Percona Server| has implemented extra scalability metrics in :rn:`5.6.17-65.0`. These metrics allow using Little's Law, queueing theory, and Universal Scalability Law to gain insights into server performance. This feature is implemented as a plugin.
+
+Installation
+============
+
+Scalability Metrics plugin is shipped with |Percona Server|, but it is not installed by default. To enable the plugin you must run the following command: 
+
+.. code-block:: mysql
+
+   INSTALL PLUGIN scalability_metrics SONAME 'scalability_metrics.so';
+
+You can check if the plugin is loaded correctly by running:
+
+.. code-block:: mysql
+
+   SHOW PLUGINS;
+
+The plugin should be listed in the output:
+    
+.. code-block:: mysql
+
+   +--------------------------------+----------+--------------------+------------------------+---------+
+   | Name                           | Status   | Type               | Library                | License |
+   +--------------------------------+----------+--------------------+------------------------+---------+
+   ...
+   | scalability_metrics            | ACTIVE   | AUDIT              | scalability_metrics.so | GPL     |
+   +--------------------------------+----------+--------------------+------------------------+---------+
+
+System Variables
+================
+
+.. variable:: scalability_metrics_control
+
+     :version 5.6.17-65.0: Implemented
+     :cli: Yes
+     :scope: Global
+     :dyn: Yes
+     :vartype: String
+     :default: ``OFF``
+     :values: ``OFF``, ``ON``, ``RESET``
+
+This variable can be used to enable and disable the collection of metrics for scalability measurement. By setting the value to ``RESET`` all counters will be reset while continuing to count metrics.
+
+Status Variables
+================
+
+.. variable:: scalability_metrics_elapsedtime
+   
+   :version 5.6.17-65.0: Implemented
+   :vartype: Numeric
+
+This status variable shows total time elapsed since metrics collection was started.
+
+.. variable:: scalability_metrics_queries
+   
+   :version 5.6.17-65.0: Implemented
+   :vartype: Numeric
+
+This status variable shows number of completed queries since metrics collection was started.
+
+.. variable:: scalability_metrics_concurrency
+   
+   :version 5.6.17-65.0: Implemented
+   :vartype: Numeric
+
+This status variable shows number of queries currently executed.
+
+.. variable:: scalability_metrics_totaltime
+   
+   :version 5.6.17-65.0: Implemented
+   :vartype: Numeric
+
+This status variable shows total execution time of all queries, including the in-progress time of currently executing queries, in microseconds (ie. if two queries executed with 1 second of response time each, the result is 2 seconds).
+
+.. variable:: scalability_metrics_busytime
+   
+   :version 5.6.17-65.0: Implemented
+   :vartype: Numeric
+
+This counter accounts the non-idle server time, that is, time when at least one query was executing. 
+
+
+Version Specific Information
+============================
+
+  * :rn:`5.6.17-65.0`
+    Scalability Metrics plugin has been implemented in |Percona Server|.
+
+Other Reading
+=============
+
+* `Fundamental performance and scalability instrumentation <http://www.xaprb.com/blog/2011/10/06/fundamental-performance-and-scalability-instrumentation/>`_
+* `Forecasting MySQL Scalability with the Universal Scalability Law Whitepaper <http://www.percona.com/files/white-papers/forecasting-mysql-scalability.pdf>`_
 
=== modified file 'doc/source/diagnostics/slow_extended.rst'
--- doc/source/diagnostics/slow_extended.rst	2013-09-20 13:13:37 +0000
+++ doc/source/diagnostics/slow_extended.rst	2014-05-06 12:44:40 +0000
@@ -81,6 +81,8 @@
      :conf: Yes
      :scope: Global, session
      :dyn: Yes
+     :default: 1
+     :range: 1-1000
 
 Behavior of this variable depends from :variable:`log_slow_rate_type`.
 
@@ -94,9 +96,9 @@
 Note that every query has global unique ``query_id`` and every connection can has it own (session) :variable:`log_slow_rate_limit`.
 Decision "log or no" calculated in following manner:
 
- * if ``log_slow_rate_limit`` is 0 - log every query
+ * if ``log_slow_rate_limit`` is 1 - log every query
 
- * If ``log_slow_rate_limit`` > 0 - log query when (``query_id`` % ``log_slow_rate_limit``) is zero.
+ * If ``log_slow_rate_limit`` > 1 - randomly log every 1/``log_slow_rate_limit`` query. 
 
 This allows flexible setup logging behavior.
 
@@ -104,6 +106,8 @@
  
   Log_slow_rate_type: query  Log_slow_rate_limit: 10
 
+Prior to :rn:`5.6.17-65.0` implementation of the :variable:`log_slow_rate_type` set to ``query`` with :variable:`log_slow_rate_limit` feature would log every nth query deterministically. With the current implementation each query has a non-deterministic probability of 1/n to get logged.
+
 .. variable:: log_slow_sp_statements
 
      :cli: Yes
@@ -145,7 +149,7 @@
     Equivalent to enabling ``microtime,innodb``.
 
   * ``full``:
-    Equivalent to all other values OR'ed together.
+    Equivalent to all other values OR'ed together without the ``profiling`` and ``profiling_use_getrusage`` options.
 
   * ``profiling``:
     Enables profiling of all queries in all connections.
 
=== modified file 'doc/source/index.rst'
--- doc/source/index.rst	2014-04-25 10:55:01 +0000
+++ doc/source/index.rst	2014-05-06 12:44:40 +0000
@@ -124,6 +124,7 @@
    management/log_archiving
    management/statement_timeout
    management/backup_locks
+   management/audit_log_plugin
 
 Diagnostics Improvements
 ========================
@@ -142,6 +143,7 @@
    diagnostics/process_list
    diagnostics/misc_info_schema_tables
    diagnostics/thread_based_profiling
+   diagnostics/scalability_metrics_plugin
 
 TokuDB
 ======
@@ -154,6 +156,7 @@
    tokudb/tokudb_installation
    tokudb/using_tokudb
    tokudb/tokudb_compression
+   tokudb/tokudb_multiple_clustering_keys
 
 Reference
 =========
 
=== modified file 'doc/source/installation/apt_repo.rst'
--- doc/source/installation/apt_repo.rst	2014-03-03 18:32:52 +0000
+++ doc/source/installation/apt_repo.rst	2014-05-06 12:44:40 +0000
@@ -37,9 +37,9 @@
 
  * 10.04LTS (lucid)
  * 12.04LTS (precise)
- * 12.10 (quantal)
  * 13.04 (raring)
  * 13.10 (saucy)
+ * 14.04LTS (trusty)
 
 
 Percona `apt` Experimental repository
 
=== added file 'doc/source/management/audit_log_plugin.rst'
--- doc/source/management/audit_log_plugin.rst	1970-01-01 00:00:00 +0000
+++ doc/source/management/audit_log_plugin.rst	2014-05-06 12:44:40 +0000
@@ -0,0 +1,234 @@
+.. _audit_log_plugin:
+
+==================
+ Audit Log Plugin
+==================
+
+Percona Audit Log Plugin provides monitoring and logging of connection and query activity that were performed on specific server. Information about the activity will be stored in the XML log file where each event will have its ``NAME`` field, it's own unique ``RECORD_ID`` field and a ``TIMESTAMP`` field. This implementation is alternative to the `MySQL Enterprise Audit Log Plugin <dev.mysql.com/doc/refman/5.5/en/audit-log-plugin.html>`_
+
+Audit Log plugin produces the log of following events:
+
+* **Audit** - Audit event indicates that audit logging started or finished. ``NAME`` field will be ``Audit`` when logging started and ``NoAudit`` when logging finished. Audit record also includes server version and command-line arguments.
+
+Example of the Audit event: :: 
+
+ <AUDIT_RECORD
+  "NAME"="Audit"
+  "RECORD"="1_2014-04-29T09:29:40"
+  "TIMESTAMP"="2014-04-29T09:29:40 UTC"
+  "MYSQL_VERSION"="5.6.17-65.0-655.trusty"
+  "STARTUP_OPTIONS"="--basedir=/usr --datadir=/var/lib/mysql --plugin-dir=/usr/lib/mysql/plugin --user=mysql --log-error=/var/log/mysql/error.log --pid-file=/var/run/mysqld/mysqld.pid --socket=/var/run/mysqld/mysqld.sock --port=3306"
+  "OS_VERSION"="x86_64-debian-linux-gnu",
+  />
+
+* **Connect**/**Disconnect** - Connect record event will have ``NAME`` field ``Connect`` when user logged in or login failed, or ``Quit`` when connection is closed. Additional fields for this event are ``CONNECTION_ID``, ``STATUS``, ``USER``, ``PRIV_USER``, ``OS_LOGIN``, ``PROXY_USER``, ``HOST``, and ``IP``. ``STATUS`` will be  ``0`` for successful logins and non-zero for failed logins.
+
+Example of the Disconnect event: :: 
+
+ <AUDIT_RECORD
+  "NAME"="Quit"
+  "RECORD"="24_2014-04-29T09:29:40"
+  "TIMESTAMP"="2014-04-29T10:20:13 UTC"
+  "CONNECTION_ID"="49"
+  "STATUS"="0"
+  "USER"=""
+  "PRIV_USER"=""
+  "OS_LOGIN"=""
+  "PROXY_USER"=""
+  "HOST"=""
+  "IP"=""
+  "DB"=""
+  />
+
+* **Query** - Additional fields for this event are: ``COMMAND_CLASS`` (values come from the ``com_status_vars`` array in the :file:`sql/mysqld.cc`` file in a MySQL source distribution. Examples are ``select``, ``alter_table", "create_table", etc.), ``CONNECTION_ID``, ``STATUS`` (indicates error when non-zero), ``SQLTEXT`` (text of SQL-statement, statements are rewritten  to exclude passwords by default, this can be changed by :option:`--log-raw` option ), ``USER``, ``HOST``, ``OS_USER``, ``IP``. Possible values for the ``NAME`` name field for this event are ``Query``, ``Prepare``, ``Execute``, ``Change user``, etc.
+
+Example of the Query event: :: 
+
+ <AUDIT_RECORD
+  "NAME"="Query"
+  "RECORD"="23_2014-04-29T09:29:40"
+  "TIMESTAMP"="2014-04-29T10:20:10 UTC"
+  "COMMAND_CLASS"="select"
+  "CONNECTION_ID"="49"
+  "STATUS"="0"
+  "SQLTEXT"="SELECT * from mysql.user"
+  "USER"="root[root] @ localhost []"
+  "HOST"="localhost"
+  "OS_USER"=""
+  "IP"=""
+  />
+
+Installation
+============
+
+Audit Log plugin is shipped with |Percona Server|, but it is not installed by default. To enable the plugin you must run the following command: 
+
+.. code-block:: mysql
+
+   INSTALL PLUGIN audit_log SONAME 'audit_log.so';
+
+You can check if the plugin is loaded correctly by running:
+
+.. code-block:: mysql
+
+   SHOW PLUGINS;
+
+Audit log should be listed in the output:
+    
+.. code-block:: mysql
+
+   +--------------------------------+----------+--------------------+--------------+---------+
+   | Name                           | Status   | Type               | Library      | License |
+   +--------------------------------+----------+--------------------+--------------+---------+
+   ...
+   | audit_log                      | ACTIVE   | AUDIT              | audit_log.so | GPL     |
+   +--------------------------------+----------+--------------------+--------------+---------+
+
+Log Format
+==========
+
+Audit log plugin supports two formats. In one format (``OLD``) log record properties are saved as XML attributes and in the other (``NEW``) log recored properties are saved as XML tags. Audit log format can be set up with the :variable:`audit_log_format` variable.
+
+Example of the ``OLD`` format: ::
+
+ <AUDIT_RECORD
+  "NAME"="Query"
+  "RECORD"="2_2014-04-28T09:29:40"
+  "TIMESTAMP"="2014-04-28T09:29:40 UTC"
+  "COMMAND_CLASS"="install_plugin"
+  "CONNECTION_ID"="47"
+  "STATUS"="0"
+  "SQLTEXT"="INSTALL PLUGIN audit_log SONAME 'audit_log.so'"
+  "USER"="root[root] @ localhost []"
+  "HOST"="localhost"
+  "OS_USER"=""
+  "IP"=""
+ />
+
+Example of the ``NEW`` format: :: 
+
+ <AUDIT_RECORD>
+  <NAME>Quit</NAME>
+  <RECORD>10902_2014-04-28T11:02:54</RECORD>
+  <TIMESTAMP>2014-04-28T11:02:59 UTC</TIMESTAMP>
+  <CONNECTION_ID>36</CONNECTION_ID>
+  <STATUS>0</STATUS>
+  <USER></USER>
+  <PRIV_USER></PRIV_USER>
+  <OS_LOGIN></OS_LOGIN>
+  <PROXY_USER></PROXY_USER>
+  <HOST></HOST>
+  <IP></IP>
+  <DB></DB>
+ </AUDIT_RECORD>
+
+System Variables
+================
+
+.. variable:: audit_log_strategy
+
+     :version 5.6.17-65.0: Implemented
+     :cli: Yes
+     :scope: Global
+     :dyn: No
+     :vartype: String
+     :default: ASYNCHRONOUS
+     :allowed values: ``ASYNCHRONOUS``, ``PERFORMANCE``, ``SEMISYNCHRONOUS``, ``SYNCHRONOUS``
+
+This variable is used to specify the audit log strategy, possible values are:
+
+* ``ASYNCHRONOUS`` - (default) log using memory buffer, do not drop messages if buffer is full
+* ``PERFORMANCE`` - log using memory buffer, drop messages if buffer is full
+* ``SEMISYNCHRONOUS`` - log directly to file, do not flush and sync every event
+* ``SYNCHRONOUS`` - log directly to file, flush and sync every event
+
+.. variable:: audit_log_file
+
+     :version 5.6.17-65.0: Implemented
+     :cli: Yes
+     :scope: Global
+     :dyn: No
+     :vartype: String
+     :default: audit.log
+
+This variable is used to specify the filename that's going to store the audit log. It can contain the path relative to the datadir or absolute path.
+
+.. variable:: audit_log_flush
+
+     :version 5.6.17-65.0: Implemented
+     :cli: Yes
+     :scope: Global
+     :dyn: No
+     :vartype: String
+     :default: OFF
+
+When this variable is set to ``ON`` log file will be closed and reopened. This can be used for manual log rotation.
+
+.. variable:: audit_log_buffer_size
+
+     :version 5.6.17-65.0: Implemented
+     :cli: Yes
+     :scope: Global
+     :dyn: No
+     :vartype: Numeric
+     :default: 4096
+
+This variable can be used to specify the size of memory buffer used for logging, used when :variable:`audit_log_strategy` variable is set to ``ASYNCHRONOUS`` or ``PERFORMANCE`` values.
+
+.. variable:: audit_log_format
+
+     :version 5.6.17-65.0: Implemented
+     :cli: Yes
+     :scope: Global
+     :dyn: No 
+     :vartype: String
+     :default: OLD
+     :allowed values: ``OLD``, ``NEW``
+
+This variable is used to specify the audit log format. When this variable is set to ``OLD`` information will be logged as XML attributes, and when is set to ``NEW`` it will be logged as XML tags.
+
+.. variable:: audit_log_policy
+
+     :version 5.6.17-65.0: Implemented
+     :cli: Yes
+     :scope: Global
+     :dyn: Yes 
+     :vartype: String
+     :default: ALL
+     :allowed values: ``ALL``, ``LOGINS``, ``QUERIES``, ``NONE``
+
+This variable is used to specify which events should be logged. Possible values are: 
+
+* ``ALL`` - all events will be logged
+* ``LOGINS`` - only logins will be logged
+* ``QUERIES`` - only queries will be logged
+* ``NONE`` - no events will be logged
+
+.. variable:: audit_log_rotate_on_size
+
+     :version 5.6.17-65.0: Implemented
+     :cli: Yes
+     :scope: Global
+     :dyn: No 
+     :vartype: Numeric
+     :default: 0 (don't rotate the log file)
+
+This variable is used to specify the size of the audit log file. When this size is reached log will get rotated. Old log can be found in the same directory, audit log sequential number will be appended to the name specified in the :variable:`audit_log_file` variable.
+ 
+.. variable:: audit_log_rotations
+
+     :version 5.6.17-65.0: Implemented
+     :cli: Yes
+     :scope: Global
+     :dyn: No 
+     :vartype: Numeric
+     :default: 0 
+
+This variable is used to specify how many log files should be kept when :variable:`audit_log_rotate_on_size` variable is set to non-zero value.
+
+Version Specific Information
+============================
+
+  * :rn:`5.6.17-65.0`
+    Audit Log plugin has been implemented in |Percona Server|.
+
 
=== added file 'doc/source/release-notes/Percona-Server-5.6.17-65.0.rst'
--- doc/source/release-notes/Percona-Server-5.6.17-65.0.rst	1970-01-01 00:00:00 +0000
+++ doc/source/release-notes/Percona-Server-5.6.17-65.0.rst	2014-05-06 12:44:40 +0000
@@ -0,0 +1,51 @@
+.. rn:: 5.6.17-65.0
+
+==============================
+ |Percona Server| 5.6.17-65.0 
+==============================
+
+Percona is glad to announce the release of |Percona Server| 5.6.17-65.0 on May 6th, 2014 (Downloads are available `here <http://www.percona.com/downloads/Percona-Server-5.6/Percona-Server-5.6.17-65.0/>`_ and from the :doc:`Percona Software Repositories </installation>`).
+
+Based on `MySQL 5.6.17 <http://dev.mysql.com/doc/relnotes/mysql/5.6/en/news-5-6-17.html>`_, including all the bug fixes in it, |Percona Server| 5.6.17-65.0 is the current GA release in the |Percona Server| 5.6 series. All of |Percona|'s software is open-source and free, all the details of the release can be found in the `5.6.17-65.0 milestone at Launchpad <https://launchpad.net/percona-server/+milestone/5.6.17-65.0>`_.
+
+New Features
+============
+
+ |Percona Server| now supports :ref:`scalability_metrics_plugin`.
+
+ |Percona Server| now supports :ref:`audit_log_plugin`.
+
+ |Percona Server| parser and query optimizer now support :ref:`tokudb_multiple_clustering_keys` when TokuDB engine is used. 
+
+ Storage engine handler interface has been extended with new calls to notify the storage engine of imminent table or index scan. The calls are used by TokuDB to improve performance of these operations.
+
+ |Percona Server| packages are now available for *Ubuntu* 14.04.
+
+Bugs Fixed
+==========
+
+ |Percona Server| couldn't be built with *Bison* 3.0. Bug fixed :bug:`1262439`,upstream :mysqlbug:`71250`.
+
+ Fixed the inadequate background LRU flushing for write workloads with |InnoDB| compression that could lead to lower performance. Bug fixed :bug:`1295268`.
+
+ |Percona Server| debug packages were not built for the previous releases. Bug fixed :bug:`1298352`.
+
+ Queries that no longer exceed :variable:`long_query_time` were written to the slow query log if they matched the previous :variable:`long_query_time` value when :variable:`slow_query_log_use_global_control` variable was set to ``all``. Bug fixed :bug:`1016991`.
+
+ When writing audit plugins it was not possible to get notifications for general-log events without enabling the general-log. Bug fixed :bug:`1182535` (upstream :mysqlbug:`60782`).
+
+ ``mysqld_safe`` did not correctly parse :variable:`flush_caches` and :variable:`numa_interleave` options. Bug fixed :bug:`1231110`.
+
+ :ref:`threadpool` would handle a new client connection without notifying Audit Plugin. Bug fixed :bug:`1282008`.
+
+ Fixed a performance issue in extending tablespaces if running under ``fusionIO`` with :ref:`atomic writes <atomic_fio>` enabled. Bug fixed :bug:`1286114` (*Jan Lindström*).
+
+ Previous implementation of the :variable:`log_slow_rate_type` set to ``query`` with :variable:`log_slow_rate_limit` feature would log every nth query deterministically instead of each query having a 1/n probability to get logged. Fixed by randomly selecting the queries to be logged instead of logging every nth query. Bug fixed :bug:`1287650`.
+
+ |Percona Server| source files were referencing *Maatkit* instead of |Percona Toolkit|. Bug fixed :bug:`1174779`.
+
+ Maximum allowed value for :variable:`log_slow_rate_limit` was ``ULONG_MAX`` (ie. either ``4294967295`` or ``18446744073709551615``, depending on the platform). As it was unreasonable to configure the slow log for every four billionth session/query, new maximum allowed value is set to ``1000``. Bug fixed :bug:`1290714`.
+
+Other bugs fixed :bug:`1295523`, :bug:`1299688` (upstream :mysqlbug:`72163`) and :bug:`1272732`.
+
+
 
=== modified file 'doc/source/release-notes/release-notes_index.rst'
--- doc/source/release-notes/release-notes_index.rst	2014-04-25 10:55:01 +0000
+++ doc/source/release-notes/release-notes_index.rst	2014-05-06 12:44:40 +0000
@@ -6,6 +6,7 @@
    :maxdepth: 1
    :glob:
 
+   Percona-Server-5.6.17-65.0
    Percona-Server-5.6.16-64.2-tokudb
    Percona-Server-5.6.16-64.2
    Percona-Server-5.6.16-64.1
 
=== added file 'doc/source/tokudb/tokudb_multiple_clustering_keys.rst'
--- doc/source/tokudb/tokudb_multiple_clustering_keys.rst	1970-01-01 00:00:00 +0000
+++ doc/source/tokudb/tokudb_multiple_clustering_keys.rst	2014-05-06 12:44:40 +0000
@@ -0,0 +1,62 @@
+.. _tokudb_multiple_clustering_keys:
+
+==========================
+ Multiple Clustering Keys
+==========================
+
+TokuDB allows a secondary key to be defined as a clustering key. This means that all of the columns in the table are clustered with the secondary key. |Percona Server| parser and query optimizer support Multiple Clustering Keys when TokuDB engine is used. This means that the query optimizer will avoid primary clustered index reads and replace them by secondary clustered index reads in certain scenarios.
+
+The parser has been extended to support following syntax:
+
+.. code-block:: mysql
+
+  CREATE TABLE ... ( ..., CLUSTERING KEY identifier (column list), ...
+  CREATE TABLE ... ( ..., UNIQUE CLUSTERING KEY identifier (column list), ...
+  CREATE TABLE ... ( ..., CLUSTERING UNIQUE KEY identifier (column list), ...
+  CREATE TABLE ... ( ..., CONSTRAINT identifier UNIQUE CLUSTERING KEY identifier (column list), ...
+  CREATE TABLE ... ( ..., CONSTRAINT identifier CLUSTERING UNIQUE KEY identifier (column list), ...
+
+  CREATE TABLE ... (... column type CLUSTERING [UNIQUE] [KEY], ...)
+  CREATE TABLE ... (... column type [UNIQUE] CLUSTERING [KEY], ...)
+
+  ALTER TABLE ..., ADD CLUSTERING INDEX identifier (column list), ...
+  ALTER TABLE ..., ADD UNIQUE CLUSTERING INDEX identifier (column list), ...
+  ALTER TABLE ..., ADD CLUSTERING UNIQUE INDEX identifier (column list), ...
+  ALTER TABLE ..., ADD CONSTRAINT identifier UNIQUE CLUSTERING INDEX identifier (column list), ...
+  ALTER TABLE ..., ADD CONSTRAINT identifier CLUSTERING UNIQUE INDEX identifier (column list), ...
+
+  CREATE CLUSTERING INDEX identifier ON ...
+
+Examples
+========
+
+To create clustered index in TokuDB table, you need to add ``CLUSTERING`` keyword in front of any index that is to be created.
+
+* To create a clustered index while creating a new table:
+
+.. code-block:: mysql
+
+  CREATE TABLE city (city_id int PRIMARY KEY, name varchar(50), CLUSTERING KEY (citry_id)) engine=tokudb; 
+
+* To add a clustered index on already existing table:
+
+.. code-block:: mysql
+
+  ALTER TABLE city ADD CLUSTERING INDEX clstr_key(city_id);
+
+or 
+
+.. code-block:: mysql
+
+   CREATE CLUSTERING INDEX clstr_key ON city(city_id);
+
+Version Specific Information
+============================
+* :rn:`5.6.17-65.0` - |Percona Server| implemented support for Multiple Clustering Keys
+
+Other Reading
+=============
+
+* `Introducing Multiple Clustering Indexes <http://www.tokutek.com/2009/05/introducing_multiple_clustering_indexes/>`_ 
+* `Clustering indexes vs. Covering indexes <HTTP://www.tokutek.com/2009/05/clustering_indexes_vs_covering_indexes/>`_
+
 
=== modified file 'doc/source/upstream-bug-fixes.rst'
--- doc/source/upstream-bug-fixes.rst	2014-04-25 10:55:01 +0000
+++ doc/source/upstream-bug-fixes.rst	2014-05-06 12:44:40 +0000
@@ -5,21 +5,39 @@
 =============================================================
 
 +-------------------------------------------------------------------------------------------------------------+
+|:Upstream bug: :mysqlbug:`72163` - Rev 5774 broke rpl_plugin_load                                            |
+|:Launchpad bug: :bug:`1299688`                                                                               |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
+|:Fix Released: :rn:`5.6.17-65.0`                                                                             |
+|:Upstream fix: N/A                                                                                           |
++-------------------------------------------------------------------------------------------------------------+
+|:Upstream bug: :mysqlbug:`60782` - Audit plugin API: no MYSQL_AUDIT_GENERAL_LOG notifications with general...|
+|:Launchpad bug: :bug:`1182535`                                                                               |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
+|:Fix Released: :rn:`5.6.17-65.0`                                                                             |
+|:Upstream fix: N/A                                                                                           |
++-------------------------------------------------------------------------------------------------------------+
+|:Upstream bug: :mysqlbug:`71250` - Bison 3 breaks mysql build                                                |
+|:Launchpad bug: :bug:`1262439`                                                                               |
+|:Upstream state: Closed                                                                                      |
+|:Fix Released: :rn:`5.6.17-65.0`                                                                             |
+|:Upstream fix: N/A                                                                                           |
++-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`71374` - Slave IO thread won't attempt auto reconnect to the master/error-code 1159|
 |:Launchpad bug: :bug:`1268729`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.16-64.1`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`71988` - page_cleaner: aggressive background flushing                              |
 |:Launchpad bug: :bug:`1238039`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.16-64.0`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`71624` - printf size_t results in a fatal warning in 32-bit debug builds           |
 |:Launchpad bug: :bug:`1277505`                                                                               |
-|:Upstream state: Can't repeat (checked on 2014-03-17)                                                        |
+|:Upstream state: Can't repeat (checked on 2014-04-30)                                                        |
 |:Fix Released: :rn:`5.6.16-64.0`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -37,9 +55,9 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`71708` - 70768 fix perf regression: high rate of RW lock creation and destruction  |
 |:Launchpad bug: :bug:`1279671`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Closed                                                                                      |
 |:Fix Released: :rn:`5.6.16-64.0`                                                                             |
-|:Upstream fix: N/A                                                                                           |
+|:Upstream fix: 5.6.19                                                                                        |
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`54430` - innodb should retry partial reads/writes where errno was 0                |
 |:Launchpad bug: :bug:`1262500`                                                                               |
@@ -61,13 +79,13 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`71270` - Failures to end bulk insert for partitioned tables handled incorrectly    |
 |:Launchpad bug: :bug:`1204871`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.16-64.0`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`71217` - Threadpool - add thd_wait_begin/thd_wait_end to the network IO functions  |
 |:Launchpad bug: :bug:`1159743`                                                                               |
-|:Upstream state: Open (checked on 2014-03-17)                                                                |
+|:Upstream state: Open (checked on 2014-04-30)                                                                |
 |:Fix Released: :rn:`5.6.15-63.0`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -85,7 +103,7 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`71411` - buf_flush_LRU() does not return correct number in case of compressed pages|
 |:Launchpad bug: :bug:`1231918`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.13-61.0`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -97,7 +115,7 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`70490` - Suppression is too strict on some systems                                 |
 |:Launchpad bug: :bug:`1205196`                                                                               |
-|:Upstream state: No Feedback (checked on 2014-03-17)                                                         |
+|:Upstream state: No Feedback (checked on 2014-04-30)                                                         |
 |:Fix Released: :rn:`5.6.13-61.0`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -109,7 +127,7 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`70500` - Page cleaner should perform LRU flushing regardless of server activity    |
 |:Launchpad bug: :bug:`1234562`                                                                               |
-|:Upstream state: Open (checked on 2014-03-17)                                                                |
+|:Upstream state: Open (checked on 2014-04-30)                                                                |
 |:Fix Released: :rn:`5.6.13-61.0`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -127,31 +145,31 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`68481` - InnoDB LRU flushing for MySQL 5.6 needs work                              |
 |:Launchpad bug: :bug:`1232406`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.13-61.0`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`70453` - Add hard timeouts to page cleaner flushes                                 |
 |:Launchpad bug: :bug:`1232101`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.13-61.0`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`69170` - buf_flush_LRU is lazy                                                     |
 |:Launchpad bug: :bug:`1231918`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.13-61.0`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`68555` - thread convoys from log_checkpoint_margin with innodb_buffer_pool_inst... |
 |:Launchpad bug: :bug:`1236884`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.13-61.0`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`70228` - Is buf_LRU_free_page() really supposed to make non-zip block sticky at ...|
 |:Launchpad bug: :bug:`1220544`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.13-60.6`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -169,13 +187,13 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`70216` - Unnecessary overhead from persistent adaptive hash index latches          |
 |:Launchpad bug: :bug:`1218347`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.13-60.6`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`62018` - innodb adaptive hash index mutex contention                               |
 |:Launchpad bug: :bug:`1216804`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.13-60.6`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -193,13 +211,13 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`42415` - UPDATE/DELETE with LIMIT clause unsafe for SBL even with ORDER BY PK ...  |
 |:Launchpad bug: :bug:`1132194`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.13-60.5`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`69639` - mysql failed to build with dtrace Sun D 1.11                              |
 |:Launchpad bug: :bug:`1196460`                                                                               |
-|:Upstream state: Open (checked on 2014-03-17)                                                                |
+|:Upstream state: Open (checked on 2014-04-30)                                                                |
 |:Fix Released: :rn:`5.6.13-60.5`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -217,7 +235,7 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`69856` - mysql_install_db does not function properly in 5.6 for debug builds       |
 |:Launchpad bug: :bug:`1179359`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.12-60.4`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -229,7 +247,7 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`71183` - os_file_fsync() should handle fsync() returning EINTR                     |
 |:Launchpad bug: :bug:`1262651`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.11-60.3`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -259,7 +277,7 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`68714` - Remove literal statement digest values from perfschema tests              |
 |:Launchpad bug: :bug:`1157078`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.11-60.3`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -283,13 +301,13 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`68970` - fsp_reserve_free_extents switches from small to big tblspace handling ... |
 |:Launchpad bug: :bug:`1169494`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.11-60.3`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`68713` - create_duplicate_weedout_tmp_table() leaves key_part_flag uninitialized   |
 |:Launchpad bug: :bug:`1157037`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.11-60.3`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -301,13 +319,13 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`68999` - SSL_OP_NO_COMPRESSION not defined                                         |
 |:Launchpad bug: :bug:`1183610`                                                                               |
-|:Upstream state: No Feedback (checked on 2014-03-17)                                                         |
+|:Upstream state: No Feedback (checked on 2014-04-30)                                                         |
 |:Fix Released: :rn:`5.6.11-60.3`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`68845` - Unnecessary log_sys->mutex reacquisition in mtr_log_reserve_and_write()   |
 |:Launchpad bug: :bug:`1163439`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.11-60.3`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -337,7 +355,7 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`68476` - Suboptimal code in my_strnxfrm_simple()                                   |
 |:Launchpad bug: :bug:`1132350`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.11-60.3`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -397,7 +415,7 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`61178` - Incorrect implementation of intersect(ulonglong) in non-optimized Bitmap..|
 |:Launchpad bug: :bug:`1042517`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.11-60.3`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -409,7 +427,7 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`64800` - mysqldump with --include-master-host-port putting quotes around port no.  | 
 |:Launchpad bug: :bug:`1013432`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.11-60.3`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -439,13 +457,13 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`25007` - memory tables with dynamic rows format                                    |
 |:Launchpad bug: N/A                                                                                          |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.11-60.3`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`61595` - mysql-test/include/wait_for_slave_param.inc timeout logic is incorrect    |
 |:Launchpad bug: :bug:`800035`                                                                                |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.11-60.3`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -457,7 +475,7 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`68116` - InnoDB monitor may hit an assertion error in buf_page_get_gen in debug ...|
 |:Launchpad bug: :bug:`1100178`                                                                               |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.10-60.2`                                                                             |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
@@ -469,13 +487,13 @@
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`20001` - Support for temp-tables in INFORMATION_SCHEMA                             |
 |:Launchpad bug: N/A                                                                                          |
-|:Upstream state: Verified (checked on 2014-03-17)                                                            |
+|:Upstream state: Verified (checked on 2014-04-30)                                                            |
 |:Fix Released: :rn:`5.6.5-60.0`                                                                              |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+
 |:Upstream bug: :mysqlbug:`69146` - Optimization in buf_pool_get_oldest_modification if srv_buf_pool_instances|
 |:Launchpad bug: :bug:`1176496`                                                                               |
-|:Upstream state: Open (checked on 2014-03-17)                                                                |
+|:Upstream state: Open (checked on 2014-04-30)                                                                |
 |:Fix Released: :rn:`5.6.5-60.0`                                                                              |
 |:Upstream fix: N/A                                                                                           |
 +-------------------------------------------------------------------------------------------------------------+